Omówienie orkiestracji .NET.NET Aspire

2025-05-20

.NET .NET Aspire udostępnia interfejsy API do wyrażania zasobów i zależności w aplikacji rozproszonej. Oprócz tych interfejsów API istnieją narzędzia, które umożliwiają kilka interesujących scenariuszy. Orkiestrator jest przeznaczony do celów lokalnego rozwoju i nie jest wspierany w środowiskach produkcyjnych.

Przed kontynuowaniem rozważ kilka typowych terminologii używanych w .NET.NET Aspire:

model aplikacji: kolekcja zasobów tworzących aplikację rozproszoną (DistributedApplication) zdefiniowana w przestrzeni nazw Aspire.Hosting.ApplicationModel. Aby uzyskać bardziej formalną definicję, zobacz Definiowanie modelu aplikacji.
host aplikacji/projekt koordynatora: projekt .NET, który koordynuje model aplikacji , nazwany przy użyciu sufiksu *.AppHost (zgodnie z konwencją).
zasób: zasób jest zależną częścią aplikacji, taką jak projekt .NET, kontener, plik wykonywalny, baza danych, pamięć podręczna lub usługa w chmurze. Reprezentuje ona dowolną część aplikacji, którą można zarządzać lub przywoływać.
Integration: Integracja to pakiet NuGet dla hosta aplikacji , który modeluje zasób, lub pakiet, który konfiguruje klienta do użycia w aplikacji odbiorczej. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.
Referencja: Referencja definiuje połączenie między zasobami, wyrażone jako zależność z użyciem interfejsu API WithReference. Aby uzyskać więcej informacji, zobacz Materiały referencyjne lub Istniejące zasoby referencyjne.

Notatka

Orkiestracja .NET.NET Aspirezostała zaprojektowana, aby uprościć zarządzanie konfiguracją i wzajemnymi połączeniami chmurowej aplikacji natywnej, zwiększając doświadczenie w lokalnym rozwoju aplikacji. Chociaż jest to nieocenione narzędzie do rozwoju, nie jest przeznaczone do zastępowania systemów środowiska produkcyjnego, takich jak Kubernetes, które zostały specjalnie zaprojektowane, aby wyróżniać się w tym kontekście.

Definiowanie modelu aplikacji

.NET .NET Aspire Umożliwia wydajne kompilowanie, aprowizowania, wdrażania, konfigurowania, testowania, uruchamiania i monitorowania aplikacji rozproszonych. Te możliwości są obsługiwane przez model aplikacji, który definiuje zasoby w rozwiązaniu .NET.NET Aspire i ich wzajemne połączenia.

Model aplikacji to nie tylko lista zasobów — reprezentuje pełną topologię aplikacji. Obejmuje to relacje między zasobami, ich zależnościami i konfiguracjami. Zasoby mogą obejmować projekty, pliki wykonywalne, kontenery, usługi zewnętrzne i zasoby w chmurze, na których opiera się aplikacja.

.NET .NET Aspire W projekcieProgram hosta aplikacji plik definiuje model aplikacji:

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

Gdy wywołujesz DistributedApplication.CreateBuilder, otrzymujesz wystąpienie IDistributedApplicationBuilder, które jest używane do konfigurowania modelu aplikacji. Ten konstruktor udostępnia metody dodawania zasobów, definiowania zależności i konfigurowania ogólnej struktury aplikacji. Po dodaniu zasobów wywołaj metodę Build , aby utworzyć model aplikacji. Szablony zawierają kod, który tworzy łańcuch wywołań, zaczynając od Build(), co zwraca instancję DistributedApplication, a następnie wywołuje Run().

Projekt hosta aplikacji

Projekt hosta aplikacji obsługuje uruchamianie wszystkich projektów, które są częścią projektu .NET.NET Aspire. Innymi słowy, odpowiada za organizowanie wszystkich aplikacji w modelu aplikacji. Sam projekt jest .NET projektem wykonywalnym, który odwołuje się do pakietu NuGet 📦Aspire Hosting.AppHost i korzysta z SDK-u .NET.NET Aspire:

<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>

Poniższy kod opisuje host aplikacji Program z dwoma odwołaniami do projektu i pamięcią podręczną Redis:

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();

Powyższy kod:

Tworzy nowego konstruktora modelu aplikacji przy użyciu metody CreateBuilder.
Dodaje zasób Rediscache o nazwie "cache" przy użyciu metody AddRedis.
Dodaje zasób projektu o nazwie "apiservice" przy użyciu metody AddProject.
Dodaje zasób projektu o nazwie "webfrontend" przy użyciu metody AddProject.
- Określa, że projekt ma zewnętrzne punkty końcowe HTTP przy użyciu metody WithExternalHttpEndpoints.
- Dodaje odwołanie do zasobu cache i oczekuje na przygotowanie go przy użyciu metod WithReference i WaitFor.
- Dodaje odwołanie do zasobu apiservice i oczekuje na przygotowanie go przy użyciu metod WithReference i WaitFor.
Kompiluje i uruchamia model aplikacji przy użyciu metod Build i Run.

Kod przykładowy używa integracji hostingu .NET AspireRedis.

Aby ułatwić wizualizowanie relacji między projektem hosta aplikacji a opisanymi zasobami, należy wziąć pod uwagę następujący diagram:

Każdy zasób musi być unikatowo nazwany. Ten diagram przedstawia każdy zasób i relacje między nimi. Zasób kontenera nosi nazwę "cache", a zasoby projektu mają nazwę "apiservice" i "webfrontend". Projekt frontend internetowego odnosi się do projektów usług pamięci podręcznej i API. W przypadku wyrażania odwołań w ten sposób projekt internetowego interfejsu sugeruje, że zależy od tych dwóch zasobów: "pamięci podręcznej" i "serwisu API".

Wbudowane typy zasobów

.NET .NET Aspire projekty składają się z zestawu zasobów. Rodzaje podstawowych zasobów w pakiecie NuGet 📦Aspire.Hosting.AppHost są opisane w poniższej tabeli:

Metoda	Typ zasobu	Opis
AddProject	ProjectResource	Projekt .NET, na przykład aplikacja internetowa ASP.NET Core.
AddContainer	ContainerResource	Obraz kontenera, taki jak obraz Docker.
AddExecutable	ExecutableResource	Plik wykonywalny, taki jak aplikacja Node.js.
AddParameter	ParameterResource	Zasób parametru, który może służyć do wyrażania parametrów zewnętrznych.

Zasoby projektu reprezentują projekty .NET, które są częścią modelu aplikacji. Po dodaniu odwołania do projektu hosta aplikacji zestaw SDK .NET.NET Aspire generuje typ w przestrzeni nazw Projects dla każdego projektu, do którego odwołuje się odwołanie. Aby uzyskać więcej informacji, zobacz .NET.NET Aspire SDK: Dokumentacja projektu.

Aby dodać projekt do modelu aplikacji, użyj metody AddProject:

var builder = DistributedApplication.CreateBuilder(args);

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

Projekty można replikować i zwiększać rozmiar, dodając wiele wystąpień tego samego projektu do modelu aplikacji. Aby skonfigurować repliki, użyj metody WithReplicas:

var builder = DistributedApplication.CreateBuilder(args);

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

Powyższy kod dodaje trzy repliki zasobu projektu "apiservice" do modelu aplikacji. Aby uzyskać więcej informacji, zobacz .NET.NET Aspire panel sterowania: repliki zasobów.

Zasoby referencyjne

Referencja reprezentuje zależność między zasobami. Na przykład można sobie wyobrazić scenariusz, w którym fronton internetowy zależy od pamięci podręcznej Redis . Rozważmy poniższy przykład kodu C# dla aplikacji hosta Program:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Zasób projektu "webfrontend" używa WithReference, aby dodać zależność od zasobu kontenera "cache". Te zależności mogą reprezentować łańcuchy połączenia lub informacje odnajdywania usługi. W poprzednim przykładzie zmienna środowiskowa jest wstrzykiwana do zasobu "webfrontend" o nazwie ConnectionStrings__cache. Ta zmienna środowiskowa zawiera ciąg połączenia, którego webfrontend używa do nawiązywania połączenia z Redis poprzez integrację .NET AspireRedis, na przykład ConnectionStrings__cache="localhost:62354".

Ciąg połączenia i odwołania do punktów końcowych

Często wyraża się zależności między zasobami projektu. Rozważmy następujący przykładowy kod:

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);

Odwołania między projektami są obsługiwane inaczej niż zasoby, które mają dobrze zdefiniowane parametry połączenia. Zamiast wstrzykiwania parametrów połączenia do zasobu "webfrontend", wstrzykiwane są zmienne środowiskowe do obsługi odkrywania usług.

Metoda	Zmienna środowiskowa
`WithReference(cache)`	`ConnectionStrings__cache="localhost:62354"`
`WithReference(apiservice)`	`services__apiservice__http__0="http://localhost:5455"` `services__apiservice__https__0="https://localhost:7356"`

Dodanie odwołania do projektu "apiservice" powoduje dodanie zmiennych środowiskowych odnajdywania usługi do frontonu. Dzieje się tak, ponieważ zazwyczaj komunikacja między projektami odbywa się za pośrednictwem protokołu HTTP/gRPC. Aby uzyskać więcej informacji, zobacz .NET.NET Aspire odnajdywanie usług.

Aby uzyskać określone punkty końcowe z ContainerResource lub ExecutableResource, użyj jednego z następujących interfejsów API punktów końcowych:

Następnie wywołaj interfejs API GetEndpoint, aby uzyskać punkt końcowy, który może służyć do odwoływania się do punktu końcowego w metodzie WithReference:

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);

Metoda	Zmienna środowiskowa
`WithReference(endpoint)`	`services__myapp__endpoint__0=https://localhost:9043`

Parametr port to port, na który nasłuchuje kontener. Aby uzyskać więcej informacji na temat portów kontenera, zobacz Porty kontenera. Aby uzyskać więcej informacji na temat odnajdywania usług, zobacz .NET.NET Aspire service discovery.

Format zmiennej środowiskowej punktu końcowego usługi

W poprzedniej sekcji metoda WithReference służy do wyrażania zależności między zasobami. Gdy punkty końcowe usługi powodują wstrzyknięcie zmiennych środowiskowych do zasobu zależnego, format może nie być oczywisty. Ta sekcja zawiera szczegółowe informacje na temat tego formatu.

Gdy jeden zasób zależy od innego zasobu, host aplikacji wprowadza zmienne środowiskowe do zasobu zależnego. Te zmienne środowiskowe konfigurują zasób zależny, aby połączył się z zasobem, od którego jest zależny. Format zmiennych środowiskowych jest specyficzny dla .NET.NET Aspire i wyraża punkty końcowe usługi w sposób zgodny z Service Discovery.

Nazwy zmiennych środowiskowych punktu końcowego usługi mają prefiks services__ (podwójne podkreślenie), a następnie nazwę usługi, nazwę punktu końcowego i na koniec indeks. Indeks obsługuje wiele punktów końcowych dla jednej usługi, zaczynając od 0 dla pierwszego punktu końcowego i zwiększając numerację dla każdego kolejnego punktu końcowego.

Rozważmy następujące przykłady zmiennych środowiskowych:

services__apiservice__http__0

Poprzednia zmienna środowiskowa wyraża pierwszy punkt końcowy HTTP dla usługi apiservice. Wartość zmiennej środowiskowej to adres URL punktu końcowego usługi. Nazwany punkt końcowy może być wyrażony w następujący sposób:

services__apiservice__myendpoint__0

W poprzednim przykładzie usługa apiservice ma nazwany punkt końcowy o nazwie myendpoint. Wartość zmiennej środowiskowej to adres URL punktu końcowego usługi.

Odwołuj się do istniejących zasobów

Niektóre sytuacje gwarantują, że odwołujesz się do istniejącego zasobu, być może takiego, który został wdrożony u dostawcy usług w chmurze. Możesz na przykład odwołać się do bazy danych Azure. W takim przypadku należy opierać się na kontekście wykonywania, aby dynamicznie określić, czy host aplikacji jest uruchomiony w trybie "uruchomienia" lub "publikowania". Jeśli korzystasz lokalnie i chcesz polegać na zasobie w chmurze, możesz użyć właściwości IsRunMode, aby warunkowo dodać odwołanie. Zamiast tego możesz utworzyć zasób w trybie publikowania. Niektóre integracje hostingu obsługują bezpośrednie dostarczanie ciągu połączenia, który może służyć do odwoływania się do istniejącego zasobu.

Podobnie mogą wystąpić przypadki użycia, w których chcesz zintegrować .NET.NET Aspire z istniejącym rozwiązaniem. Jednym z typowych podejść jest dodanie projektu hosta aplikacji .NET.NET Aspire do istniejącego rozwiązania. Na hoście aplikacji wyrażasz zależności, dodając odwołania do projektów w hoście aplikacji i rozwijając model aplikacji. Na przykład jeden projekt może zależeć od innego. Te zależności są wyrażane przy użyciu metody WithReference. Aby uzyskać więcej informacji, zobacz Dodaj .NET Aspire do istniejącej aplikacji .NET.

Kontekst wykonywania

IDistributedApplicationBuilder udostępnia kontekst wykonawczy (DistributedApplicationExecutionContext), który dostarcza informacje o bieżącym działaniu hosta aplikacji. Za pomocą tego kontekstu można ocenić, czy host aplikacji wykonuje tryb "uruchom", czy w ramach operacji publikowania. Rozważ następujące właściwości:

IsRunMode: zwraca true, jeśli bieżąca operacja jest uruchomiona.
IsPublishMode: zwraca true, jeśli bieżąca operacja polega na publikowaniu.

Te informacje mogą być przydatne, gdy chcesz warunkowo wykonać kod na podstawie bieżącej operacji. Rozważmy poniższy przykład, który pokazuje użycie właściwości IsRunMode. W takim przypadku metoda rozszerzająca służy do generowania stabilnej nazwy węzła dla RabbitMQ podczas lokalnych uruchomień deweloperskich.

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;
}

Kontekst wykonywania jest często używany do warunkowego dodawania zasobów lub parametrów połączenia wskazujących istniejące zasoby. Rozważmy następujący przykład, który pokazuje warunkowe dodawanie Redis lub parametrów połączenia na podstawie kontekstu wykonywania:

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();

W poprzednim kodzie:

Jeśli host aplikacji jest w trybie "uruchom", zostanie dodany zasób kontenera Redis .
Jeśli host aplikacji jest w trybie "publikowania", dodawane są parametry połączenia.

Tę logikę można łatwo przywrócić, aby nawiązać połączenie z istniejącym zasobem Redis podczas uruchamiania lokalnego i utworzyć nowy zasób Redis podczas publikowania.

Ważny

.NET .NET Aspire udostępnia typowe interfejsy API do kontrolowania modalności konstruktorów zasobów, dzięki czemu zasoby zachowują się inaczej na podstawie trybu wykonywania. Płynne interfejsy API są oznaczone RunAs* i PublishAs*. Interfejsy API RunAs* wpływają na zachowanie lokalnego programowania (lub trybu uruchamiania), natomiast interfejsy API PublishAs* wpływają na publikowanie zasobu. Aby uzyskać więcej informacji na temat używania tych interfejsów API przez zasoby Azure, zobacz Używanie istniejących zasobów Azure.

Zobacz też

Organizowanie zasobów w programie .NET.NET Aspire
Omówienie integracji .NET.NET Aspire
.NET .NET Aspire SDK
Wydarzenia w .NET.NET Aspire
odkrywanie usług w .NET.NET Aspire
Ustawienia domyślne usługi .NET.NET Aspire
wyrażanie parametrów zewnętrznych
omówienie sieciowania pętli wewnętrznej .NET.NET Aspire

Udostępnij za pośrednictwem