Übersicht über .NET.NET Aspire Orchestrierung

2025-04-23

.NET .NET Aspire stellt APIs zum Ausdrücken von Ressourcen und Abhängigkeiten in Ihrer verteilten Anwendung bereit. Zusätzlich zu diesen APIs gibt es Werkzeuge, die mehrere überzeugende Szenarien ermöglichen. Der Orchestrator ist für lokale Entwicklungszwecke vorgesehen und wird in Produktionsumgebungen nicht unterstützt.

Bevor Sie fortfahren, sollten Sie einige allgemeine Termini in .NET.NET Aspirebedenken.

App-Modell: Eine Sammlung von Ressourcen, die Ihre verteilte Anwendung (DistributedApplication) bilden, die im Aspire.Hosting.ApplicationModel-Namespace definiert ist. Eine formellere Definition finden Sie unter Definieren des App-Modells.
App-Host/Orchestrator-Projekt: Das .NET-Projekt, das das App-Modellkoordiniert, benannt mit dem *.AppHost Suffix (nach Konvention).
Ressource: Eine Ressource ist ein abhängiger Teil einer Anwendung, z. B. ein .NET Projekt, Container, ausführbare Datei, Datenbank, Cache oder Clouddienst. Er stellt einen beliebigen Teil der Anwendung dar, der verwaltet oder referenziert werden kann.
Integration: Eine Integration ist ein NuGet-Paket für den App-Host, das eine Ressource oder ein Paket modelliert, das einen Client für die Verwendung in einer verbrauchenden App konfiguriert. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.
Referenz-: Eine Referenz definiert eine Verbindung zwischen Ressourcen, die als Abhängigkeit mithilfe der WithReference-API ausgedrückt wird. Weitere Informationen finden Sie unter Referenzressourcen oder Verweisen auf vorhandene Ressourcen.

Anmerkung

.NET .NET AspireDie Orchestrierung ist darauf ausgelegt, Ihre lokale Entwicklungserfahrung zu verbessern, indem sie die Verwaltung der Konfiguration und der Verbindungen Ihrer Cloud-nativen App vereinfacht. Obwohl es ein unschätzbares Tool für die Entwicklung ist, ist es nicht dafür vorgesehen, Produktionsumgebungssysteme wie Kuberneteszu ersetzen, die speziell dafür konzipiert sind, in diesem Kontext hervorragende Leistungen zu erbringen.

Definieren des App-Modells

.NET .NET Aspire ermöglicht es Ihnen, Ihre verteilten Anwendungen effizient zu erstellen, bereitzustellen, bereitzustellen, zu konfigurieren, zu testen, auszuführen und zu überwachen. Diese Funktionen werden von einem App-Modell unterstützt, das die Ressourcen in Ihrer .NET.NET Aspire Lösung und deren Verbindungen definiert.

Das App-Modell ist mehr als nur eine Liste von Ressourcen – sie stellt die vollständige Topologie Ihrer Anwendung dar. Dazu gehören die Beziehungen zwischen Ressourcen, deren Abhängigkeiten und deren Konfigurationen. Ressourcen können Projekte, ausführbare Dateien, Container, externe Dienste und Cloudressourcen enthalten, auf die Ihre Anwendung angewiesen ist.

In Ihrem .NET.NET Aspire App-Hostprojekt definiert die Program Datei Ihr App-Modell:

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

Wenn Sie aufrufen DistributedApplication.CreateBuilder, erhalten Sie eine Instanz von IDistributedApplicationBuilder, die zum Konfigurieren Ihres App-Modells verwendet wird. Dieser Generator stellt Methoden zum Hinzufügen von Ressourcen bereit, definiert Abhängigkeiten und richtet die gesamtstruktur Ihrer Anwendung ein. Nachdem Sie Ressourcen hinzugefügt haben, rufen Sie auf Build , um das App-Modell zu erstellen. Die Vorlagen enthalten Code, der einen Aufruf mit Build() verkettet, der eine DistributedApplication Instanz zurückgibt und dann Run() aufruft.

App-Hostprojekt

Das App-Hostprojekt behandelt die Ausführung aller Projekte, die Teil des .NET.NET Aspire Projekts sind. Mit anderen Worten: Sie ist dafür verantwortlich, alle Apps im App-Modell zu koordinieren. Das Projekt selbst ist ein .NET ausführbares Projekt, das auf das 📦AspireProjekt verweist. Hosting.AppHost NuGet-Paket und verwendet das .NET.NET Aspire SDK:

<Project Sdk="Microsoft.NET.Sdk">

    <Sdk Name="Aspire.AppHost.Sdk" Version="9.1.0" />
    
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net9.0</TargetFramework>
        <!-- Omitted for brevity -->
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Aspire.Hosting.AppHost" Version="9.1.0" />
    </ItemGroup>

    <!-- Omitted for brevity -->

</Project>

Der folgende Code beschreibt einen App-Host Program mit zwei Projektverweisen und einem Redis Cache:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithExternalHttpEndpoints()
       .WithReference(cache)
       .WaitFor(cache)
       .WithReference(apiService)
       .WaitFor(apiService);

builder.Build().Run();

Der vorherige Code:

Erstellt einen neuen App-Modell-Generator mithilfe der CreateBuilder-Methode.
Fügt eine Rediscache Ressource mit dem Namen "cache" mithilfe der AddRedis-Methode hinzu.
Fügt eine Projektressource namens "apiservice" mithilfe der AddProject-Methode hinzu.
Fügt eine Projektressource namens "webfrontend" mithilfe der AddProject-Methode hinzu.
- Gibt an, dass das Projekt über externe HTTP-Endpunkte mit der WithExternalHttpEndpoints-Methode verfügt.
- Fügt einen Verweis auf die cache-Ressource hinzu und wartet darauf, dass sie mithilfe der Methoden WithReference und WaitFor bereitgestellt wird.
- Fügt einen Verweis auf die apiservice-Ressource hinzu und wartet darauf, dass sie mithilfe der Methoden WithReference und WaitFor bereitgestellt wird.
Erstellt und führt das App-Modell mit den Methoden Build und Run aus.

Im Beispielcode wird die .NET AspireRedis Hosting-Integrationverwendet.

Um die Beziehung zwischen dem App-Hostprojekt und den beschriebenen Ressourcen zu visualisieren, ziehen Sie das folgende Diagramm in Betracht:

Jede Ressource muss eindeutig benannt werden. Dieses Diagramm zeigt jede Ressource und die Beziehungen zwischen ihnen. Die Containerressource heißt "cache", und die Projektressourcen heißen "apiservice" und "webfrontend". Das Web-Frontend-Projekt verweist auf die Cache- und API-Dienstprojekte. Wenn Sie Verweise auf diese Weise ausdrücken, sagt das Web-Frontend-Projekt, dass es von diesen beiden Ressourcen abhängt, dem „Cache“ bzw. „Apiservice“.

Integrierte Ressourcentypen

.NET .NET Aspire Projekte bestehen aus einer Reihe von Ressourcen. Die primären Basisressourcentypen im NuGet-Paket 📦Aspire.Hosting.AppHost werden in der folgenden Tabelle beschrieben.

Methode	Ressourcentyp	Beschreibung
AddProject	ProjectResource	Ein .NET Projekt, z. B. eine ASP.NET Core Web-App.
AddContainer	ContainerResource	Ein Containerbild, zum Beispiel ein Docker-Bild.
AddExecutable	ExecutableResource	Eine ausführbare Datei, z. B. eine Node.js App.
AddParameter	ParameterResource	Eine Parameterressource, die verwendet werden kann, um externe Parameter auszudrücken.

Projektressourcen stellen .NET Projekte dar, die Teil des App-Modells sind. Wenn Sie dem App-Hostprojekt einen Projektverweis hinzufügen, generiert das .NET.NET Aspire SDK für jedes referenzierte Projekt einen Typ im Projects Namespace. Weitere Informationen finden Sie unter .NET.NET Aspire SDK: Projektverweise.

Um dem App-Modell ein Projekt hinzuzufügen, verwenden Sie die AddProject-Methode:

var builder = DistributedApplication.CreateBuilder(args);

// Adds the project "apiservice" of type "Projects.AspireApp_ApiService".
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

Projekte können repliziert und skaliert werden, indem dem App-Modell mehrere Instanzen desselben Projekts hinzugefügt werden. Verwenden Sie zum Konfigurieren von Replikaten die WithReplicas Methode:

var builder = DistributedApplication.CreateBuilder(args);

// Adds the project "apiservice" of type "Projects.AspireApp_ApiService".
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
                        .WithReplicas(3);

Im vorherigen Code werden dem App-Modell drei Replikate der Projektressource "apiservice" hinzugefügt. Weitere Informationen finden Sie unter .NET.NET Aspire Dashboard: Ressourcenreplikate.

Referenzressourcen

Ein Verweis stellt eine Abhängigkeit zwischen Ressourcen dar. Sie können sich beispielsweise ein Szenario vorstellen, in dem ein Web-Frontend von einem Redis Cache abhängt. Betrachten Sie den folgenden Beispiel-App-Host Program C#-Code:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithReference(cache);

Die Projektressource "webfrontend" verwendet WithReference, um eine Abhängigkeit von der Containerressource "cache" hinzuzufügen. Diese Abhängigkeiten können Verbindungszeichenfolgen oder Dienstermittlungsinformationen darstellen. Im vorherigen Beispiel wird eine Umgebungsvariable eingespeist. Diese Umgebungsvariable enthält eine Verbindungszeichenfolge, die vom webfrontend zum Herstellen einer Verbindung mit Redis über die .NET AspireRedis Integrationverwendet wird, z. B. ConnectionStrings__cache="localhost:62354".

Verbindungsstring- und Endpunktverweise

Es ist üblich, Abhängigkeiten zwischen Projektressourcen auszudrücken. Betrachten Sie den folgenden Beispielcode:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithReference(cache)
       .WithReference(apiservice);

Projekt-zu-Projekt-Verweise werden anders behandelt als Ressourcen mit klar definierten Verbindungszeichenfolgen. Anstatt die Verbindungszeichenfolge in die Ressource "webfrontend" einzufügen, werden Umgebungsvariablen zur Unterstützung der Dienstermittlung eingefügt.

Methode	Umgebungsvariable
`WithReference(cache)`	`ConnectionStrings__cache="localhost:62354"`
`WithReference(apiservice)`	`services__apiservice__http__0="http://localhost:5455"` `services__apiservice__https__0="https://localhost:7356"`

Das Hinzufügen eines Verweises auf das "apiservice"-Projekt führt dazu, dass Dienstermittlungsumgebungsvariablen dem Frontend hinzugefügt werden. Dies liegt daran, dass die Projekt-zu-Projekt-Kommunikation in der Regel über HTTP/gRPC erfolgt. Weitere Informationen finden Sie unter .NET.NET Aspire Dienstentdeckung.

Um bestimmte Endpunkte aus einem ContainerResource oder einem ExecutableResourceabzurufen, verwenden Sie eine der folgenden Endpunkt-APIs:

Rufen Sie dann die GetEndpoint-API auf, um den Endpunkt abzurufen, der zum Verweisen auf den Endpunkt in der WithReference-Methode verwendet werden kann:

var builder = DistributedApplication.CreateBuilder(args);

var customContainer = builder.AddContainer("myapp", "mycustomcontainer")
                             .WithHttpEndpoint(port: 9043, name: "endpoint");

var endpoint = customContainer.GetEndpoint("endpoint");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
                        .WithReference(endpoint);

Methode	Umgebungsvariable
`WithReference(endpoint)`	`services__myapp__endpoint__0=https://localhost:9043`

Der parameter port ist der Port, auf den der Container lauscht. Weitere Informationen über Containerhäfen finden Sie unter Containerhäfen. Weitere Informationen zur Dienstentdeckung finden Sie unter .NET.NET Aspire Dienstentdeckung.

Variablenformat der Dienstendpunktumgebung

Im vorherigen Abschnitt wird die WithReference-Methode verwendet, um Abhängigkeiten zwischen Ressourcen auszudrücken. Wenn Dienstendpunkte dazu führen, dass Umgebungsvariablen in die abhängige Ressource eingefügt werden, ist das Format möglicherweise nicht offensichtlich. Dieser Abschnitt enthält Details zu diesem Format.

Wenn eine Ressource von einer anderen Ressource abhängt, fügt der App-Host Umgebungsvariablen in die abhängige Ressource ein. Diese Umgebungsvariablen konfigurieren die abhängige Ressource, um eine Verbindung mit der Ressource herzustellen, von der sie abhängt. Das Format der Umgebungsvariablen ist spezifisch für .NET.NET Aspire und expressiert Dienstendpunkte auf eine Weise, die mit Service Discoverykompatibel ist.

Variablennamen der Dienstendpunktumgebung werden in der Reihenfolge mit services__ (doppelter Unterstrich), dann dem Dienstnamen, dem Endpunktnamen und schließlich dem Index vorangestellt. Der Index unterstützt mehrere Endpunkte für einen einzelnen Dienst, beginnend mit 0 für den ersten Endpunkt und wird für jeden weiteren Endpunkt inkrementiert.

Betrachten Sie die folgenden Beispiele für Umgebungsvariablen:

services__apiservice__http__0

Die vorangehende Umgebungsvariable drückt den ersten HTTP-Endpunkt für den apiservice-Dienst aus. Der Wert der Umgebungsvariable ist die URL des Dienstendpunkts. Ein benannter Endpunkt kann wie folgt ausgedrückt werden:

services__apiservice__myendpoint__0

Im vorherigen Beispiel verfügt der apiservice Dienst über einen benannten Endpunkt namens myendpoint. Der Wert der Umgebungsvariable ist die URL des Dienstendpunkts.

Verweisen auf vorhandene Ressourcen

Einige Situationen erfordern, dass Sie auf eine bestehende Ressource verweisen, zum Beispiel eine, die bei einem Cloud-Anbieter bereitgestellt wird. Zum Beispiel könnten Sie auf eine Azure-Datenbank verweisen. In diesem Fall verlassen Sie sich auf den Ausführungskontext, um dynamisch zu bestimmen, ob der Anwendungshost im Modus "Ausführen" oder "Veröffentlichen" läuft. Wenn Sie lokal arbeiten und auf eine Cloud-Ressource zugreifen möchten, können Sie die IsRunMode-Eigenschaft verwenden, um die Referenz bedingungsgesteuert hinzuzufügen. Sie können stattdessen die Ressource im Veröffentlichungsmodus erstellen. Einige Hostingintegrationen, unterstützen die Bereitstellung einer Verbindungszeichenfolge direkt, die verwendet werden kann, um auf eine vorhandene Ressource zu verweisen.

Ebenso kann es Anwendungsfälle geben, in denen Sie .NET.NET Aspire in eine vorhandene Lösung integrieren möchten. Ein gängiger Ansatz ist das Hinzufügen des .NET.NET Aspire App-Hostprojekts zu einer vorhandenen Lösung. Innerhalb Ihres App-Hosts definieren Sie Abhängigkeiten, indem Sie dem App-Host Projektverweise hinzufügen und das App-Modellerweitern. Beispielsweise kann ein Projekt von einem anderen abhängen. Diese Abhängigkeiten werden mithilfe der WithReference-Methode ausgedrückt. Weitere Informationen finden Sie unter Hinzufügen von .NET Aspire zu einer vorhandenen .NET App-.

Ausführungskontext

Die IDistributedApplicationBuilder macht einen Ausführungskontext (DistributedApplicationExecutionContext) verfügbar, der Informationen zur aktuellen Ausführung des App-Hosts bereitstellt. Dieser Kontext kann verwendet werden, um zu überprüfen, ob der App-Host im Modus 'Ausführen' oder als Teil eines Veröffentlichungsvorgangs ausgeführt wird. Berücksichtigen Sie die folgenden Eigenschaften:

IsRunMode: Gibt true zurück, wenn der aktuelle Vorgang ausgeführt wird.
IsPublishMode: Gibt true zurück, wenn der aktuelle Vorgang eine Veröffentlichung ist.

Diese Informationen können nützlich sein, wenn Sie Code basierend auf dem aktuellen Vorgang bedingt ausführen möchten. Betrachten Sie das folgende Beispiel, das die Verwendung der IsRunMode-Eigenschaft veranschaulicht. In diesem Fall wird eine Erweiterungsmethode verwendet, um einen stabilen Knotennamen für RabbitMQ für lokale Entwicklungsläufe zu generieren.

private static IResourceBuilder<RabbitMQServerResource> RunWithStableNodeName(
    this IResourceBuilder<RabbitMQServerResource> builder)
{
    if (builder.ApplicationBuilder.ExecutionContext.IsRunMode)
    {
        builder.WithEnvironment(context =>
        {
            // Set a stable node name so queue storage is consistent between sessions
            var nodeName = $"{builder.Resource.Name}@localhost";
            context.EnvironmentVariables["RABBITMQ_NODENAME"] = nodeName;
        });
    }

    return builder;
}

Der Ausführungskontext wird häufig verwendet, um Ressourcen oder Verbindungszeichenfolgen bedingt hinzuzufügen, die auf vorhandene Ressourcen verweisen. Betrachten Sie das folgende Beispiel, das das bedingte Hinzufügen von Redis oder einer Verbindungszeichenfolge basierend auf dem Ausführungskontext veranschaulicht:

var builder = DistributedApplication.CreateBuilder(args);

var redis = builder.ExecutionContext.IsRunMode
    ? builder.AddRedis("redis")
    : builder.AddConnectionString("redis");

builder.AddProject<Projects.WebApplication>("api")
       .WithReference(redis);

builder.Build().Run();

Im vorherigen Code:

Wenn sich der App-Host im Modus "Ausführen" befindet, wird eine Redis Containerressource hinzugefügt.
Wenn sich der App-Host im Modus "veröffentlichen" befindet, wird eine Verbindungszeichenfolge hinzugefügt.

Diese Logik kann ganz einfach umgekehrt werden, um eine Verbindung mit einer vorhandenen Redis-Ressource herzustellen, wenn Sie lokal ausgeführt werden, und eine neue Redis-Ressource zu erstellen, wenn Sie veröffentlichen.

Wichtig

.NET .NET Aspire stellt allgemeine APIs bereit, um die Modalität von Ressourcen-Generatoren zu steuern, sodass Ressourcen sich je nach Ausführungsmodus unterschiedlich verhalten können. Die Fluent-APIs werden mit RunAs* und PublishAs*vorangestellt. Die RunAs* APIs beeinflussen das Verhalten der lokalen Entwicklung (oder des Ausführungsmodus), während die PublishAs* APIs die Veröffentlichung der Ressource beeinflussen. Weitere Informationen dazu, wie die Azure Ressourcen diese APIs verwenden, finden Sie unter Verwenden vorhandener Azure Ressourcen.