Sdílet prostřednictvím

Přehled orchestrace .NET.NET Aspire

.NET .NET Aspire poskytuje rozhraní API pro vyjádření prostředků a závislostí v rámci distribuované aplikace. Kromě těchto rozhraní API existují nástroje, které umožňují několik zajímavých scénářů. Orchestrátor je určený pro místní vývoj účely a není podporován v produkčních prostředích.

Než budete pokračovat, zvažte určitou běžnou terminologii použitou v .NET.NET Aspire:

  • model aplikace: Kolekce prostředků, které tvoří vaši distribuovanou aplikaci (DistributedApplication), definovanou v rámci oboru názvů Aspire.Hosting.ApplicationModel. Formální definici najdete v tématu Definování modelu aplikace.
  • Projekt hostitele aplikace/orchestrátoru: Projekt .NET, který orchestruje aplikační model s názvem s příponou *.AppHost (podle konvence).
  • zdroje: zdroj je závislou součástí aplikace, například projekt .NET, kontejner, spustitelný soubor, databáze, mezipaměť nebo cloudová služba. Představuje jakoukoli část aplikace, na kterou lze spravovat nebo na ni odkazovat.
  • Integrace: Integrace je balíček NuGet pro hostitele aplikace, sloužící k modelování prostředku, nebo balíček, který konfiguruje klienta pro použití ve spotřebitelské aplikaci. Další informace naleznete v tématu .NET.NET Aspire přehled integrací.
  • Referenční: Odkaz definuje propojení mezi prostředky vyjádřené závislostí pomocí rozhraní API WithReference. Další informace naleznete v tématu Referenční zdroje nebo Referenční existující zdroje.

Poznámka

Orchestrace .NET.NET Aspire je navržena tak, aby zlepšila váš zážitek z místního vývoje zjednodušením správy konfigurace a propojení vaší cloudově-nativní aplikace. I když je to neocenitelný nástroj pro vývoj, není určen k tomu, aby nahradil systémy pro produkční prostředí, jako je Kubernetes, které jsou speciálně navržené tak, aby v tomto kontextu excelovaly.

Definování modelu aplikace

.NET .NET Aspire umožňuje efektivně sestavovat, zřizovat, nasazovat, konfigurovat, testovat, spouštět a monitorovat distribuované aplikace. Tyto funkce využívají model aplikace, který definuje prostředky ve vašem .NET.NET Aspire řešení a jejich propojení.

Model aplikace je více než jen seznam prostředků – představuje úplnou topologii vaší aplikace. To zahrnuje vztahy mezi prostředky, jejich závislostmi a jejich konfiguracemi. Mezi prostředky můžou patřit projekty, spustitelné soubory, kontejnery, externí služby a cloudové prostředky, na které vaše aplikace spoléhá.

.NET .NET Aspire V projektu hostitele aplikace váš Program soubor definuje váš model aplikace.

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

Při volání DistributedApplication.CreateBuilderzískáte instanci IDistributedApplicationBuilder, která se používá ke konfiguraci modelu aplikace. Tento tvůrce poskytuje metody pro přidání prostředků, definování závislostí a nastavení celkové struktury aplikace. Po přidání prostředků zavolejte Build a vytvořte model aplikace. Šablony obsahují kód, který zřetězuje volání na Build(), které vrací instanci DistributedApplication, a poté volá Run().

Projekt hostingu aplikace

Projekt hostitele aplikace zpracovává spouštění všech projektů, které jsou součástí .NET.NET Aspire projektu. Jinými slovy, zodpovídá za orchestraci všech aplikací v modelu aplikace. Samotný projekt je .NET spustitelný projekt, který odkazuje na balíček NuGet 📦Aspire.Hosting.AppHost a používá SDK sadu.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>

Následující kód popisuje hostitele aplikace Program se dvěma odkazy na projekt a mezipamětí 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();

Předchozí kód:

  • Vytvoří nového tvůrce modelů aplikací pomocí metody CreateBuilder.
  • Přidá prostředek Rediscache s názvem "cache" pomocí metody AddRedis.
  • Přidá prostředek projektu s názvem "apiservice" pomocí metody AddProject.
  • Přidá zdroj projektu s názvem "webfrontend" pomocí metody AddProject.
  • Sestaví a spustí model aplikace pomocí Build a Run metod.

Ukázkový kód používá hostovací integraci .NET AspireRedis.

Pokud chcete pomoct vizualizovat vztah mezi hostitelským projektem aplikace a prostředky, které popisuje, zvažte následující diagram:

Vztah mezi projekty v šabloně .NET.NET Aspire Starter Application.

Každý prostředek musí mít jedinečný název. Tento diagram znázorňuje jednotlivé prostředky a vztahy mezi nimi. Prostředek kontejneru má název "cache" a prostředky projektu mají název "apiservice" a "webfrontend". Webový front-endový projekt odkazuje na projekty služby mezipaměti a rozhraní API. Když tímto způsobem vyjadřujete odkazy, webový front-endový projekt říká, že závisí na těchto dvou prostředcích, "mezipaměti" a "apiservice".

Předdefinované typy prostředků

.NET .NET Aspire projekty se skládají ze sady zdrojů. Primární základní typy prostředků v balíčku NuGet 📦Aspire.Hosting.AppHost jsou popsány v následující tabulce.

Metoda Typ prostředku Popis
AddProject ProjectResource Projekt .NET, například webová aplikace ASP.NET Core.
AddContainer ContainerResource Image kontejneru, například Docker image.
AddExecutable ExecutableResource Spustitelný soubor, například aplikace Node.js.
AddParameter ParameterResource Parametrický prostředek, který lze použít k vyjádření externích parametrů.

Zdroje projektu představují .NET projekty, které jsou součástí modelu aplikace. Když přidáte odkaz na projekt hostitele aplikace, sada .NET.NET Aspire SDK vygeneruje typ v oboru názvů Projects pro každý odkazovaný projekt. Další informace naleznete v tématu .NET.NET Aspire SDK: Odkazy na projekty.

Pokud chcete do modelu aplikace přidat projekt, použijte metodu AddProject:

var builder = DistributedApplication.CreateBuilder(args);

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

Projekty je možné replikovat a škálovat přidáním více instancí stejného projektu do modelu aplikace. Ke konfiguraci replik použijte metodu 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);

Předchozí kód přidá do modelu aplikace tři repliky prostředku projektu "apiservice". Další informace viz .NET.NET Aspire ovládací panel: Repliky prostředků.

Referenční zdroje

Odkaz představuje závislost mezi zdroji. Můžete si například představit scénář, ve kterém webový front-end závisí na Redis mezipaměti. Zvažte následující ukázkový kód hostitele aplikace v C# s identifikátorem Program:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Zdroj projektu "webfrontend" používá WithReference k přidání závislosti na kontejnerový prostředek "cache". Tyto závislosti mohou představovat připojovací řetězce nebo informace o zjišťování služeb. V předchozím příkladu je proměnná prostředí vložena do prostředku "webfrontend" s názvem ConnectionStrings__cache. Tato proměnná prostředí obsahuje připojovací řetězec, který webfrontend používá k připojení k Redis prostřednictvím integrace .NET AspireRedis, například ConnectionStrings__cache="localhost:62354".

Odkazy na připojovací řetězec a koncový bod

Je běžné vyjádřit závislosti mezi projektovými zdroji. Podívejte se na následující ukázkový kód:

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

Odkazy mezi projekty se zpracovávají jinak než prostředky, které mají dobře definované připojovací řetězce. Místo toho, aby byl do prostředku "webfrontend" vložen připojovací řetězec, jsou vloženy proměnné prostředí pro podporu zjišťování služeb.

Metoda Proměnná prostředí
WithReference(cache) ConnectionStrings__cache="localhost:62354"
WithReference(apiservice) services__apiservice__http__0="http://localhost:5455"
services__apiservice__https__0="https://localhost:7356"

Přidání odkazu na projekt "apiservice" vede k přidání proměnných prostředí zjišťování služeb do front-endu. Důvodem je to, že obvykle dochází ke komunikaci mezi projekty přes HTTP/gRPC. Další informace naleznete v tématu .NET.NET Aspire zjišťování služby.

Pokud chcete získat konkrétní koncové body z ContainerResource nebo ExecutableResource, použijte jedno z následujících rozhraní API koncových bodů:

Potom zavolejte rozhraní API GetEndpoint a získejte koncový bod, který se dá použít k odkazu na koncový bod v metodě 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 Proměnná prostředí
WithReference(endpoint) services__myapp__endpoint__0=https://localhost:9043

Parametr port je port, na který kontejner naslouchá. Další informace o portech kontejneru najdete v tématu Porty kontejneru. Další informace o zjišťování služby naleznete v tématu .NET.NET Aspire zjišťování služby.

Formát proměnné prostředí koncového bodu služby

V předchozí části se metoda WithReference používá k vyjádření závislostí mezi prostředky. Pokud koncové body služby vedou k injekci proměnných prostředí do závislého zdroje, formát nemusí být zřejmý. Tato část obsahuje podrobnosti o tomto formátu.

Pokud jeden prostředek závisí na jiném prostředku, hostitel aplikace vloží proměnné prostředí do závislého prostředku. Proměnné prostředí konfigurují závislý prostředek tak, aby se mohl připojit k prostředku, na kterém závisí. Formát proměnných prostředí je specifický pro .NET.NET Aspire a vyjadřuje koncové body služby způsobem, který je kompatibilní se službou Service Discovery.

Názvy proměnných prostředí koncového bodu služby mají předponu services__ (dvojité podtržítko), název služby, název koncového bodu a nakonec index. Index podporuje více koncových bodů pro jednu službu, počínaje 0 pro první koncový bod a postupně se zvyšující pro každý další koncový bod.

Představte si následující příklady proměnných prostředí:

services__apiservice__http__0

Proměnná předchozího prostředí určuje první HTTP koncový bod pro službu apiservice. Hodnota proměnné prostředí je adresa URL koncového bodu služby. Pojmenovaný koncový bod může být vyjádřen takto:

services__apiservice__myendpoint__0

V předchozím příkladu má služba apiservice pojmenovaný koncový bod s názvem myendpoint. Hodnota proměnné prostředí je adresa URL koncového bodu služby.

Odkaz na existující prostředky

Některé situace zaručují, že odkazujete na existující prostředek, třeba na ten, který je nasazený u poskytovatele cloudu. Můžete například chtít odkazovat na databázi Azure. V tomto případě byste se spoléhali na kontext spouštění , abyste dynamicky určili, jestli je hostitel aplikace spuštěný v režimu "spuštění" nebo "publikování". Pokud pracujete lokálně a chcete se spoléhat na cloudový zdroj, můžete použít vlastnost IsRunMode k podmíněnému přidání odkazu. Místo toho můžete prostředek vytvořit v režimu publikování. Některé hostovací integrace podporují přímé poskytování připojovacího řetězce, který lze použít k odkazování na existující prostředek.

Podobně mohou existovat případy použití, kdy chcete integrovat .NET.NET Aspire do stávajícího řešení. Jedním z běžných přístupů je přidání projektu hostitele aplikace .NET.NET Aspire do existujícího řešení. V rámci hostitele vaší aplikace vyjadřujete závislosti přidáním odkazů na projekt na hostitele aplikace a vytvářením modelu aplikace. Jeden projekt může například záviset na jiném projektu. Tyto závislosti jsou vyjádřeny pomocí metody WithReference. Další informace najdete v tématu Přidání .NET Aspire do existující aplikace .NET.

Kontext spuštění

IDistributedApplicationBuilder zveřejňuje kontext spuštění (DistributedApplicationExecutionContext), který poskytuje informace o aktuálním spuštění hostitele aplikace. Tento kontext lze použít k vyhodnocení, jestli hostitel aplikace běží v režimu 'run' nebo jako součást operace publikování. Vezměte v úvahu následující vlastnosti:

  • IsRunMode: Vrátí true, pokud je aktuální operace spuštěná.
  • IsPublishMode: Vrátí true, pokud je aktuální operace publikování.

Tyto informace můžou být užitečné, když chcete podmíněně spouštět kód na základě aktuální operace. Podívejte se na následující příklad, který ukazuje použití vlastnosti IsRunMode. V tomto případě se metoda rozšíření používá ke generování stabilního názvu uzlu pro RabbitMQ pro místní běhy vývoje.

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

Kontext spuštění se často používá k podmíněnému přidání prostředků nebo připojovacích řetězců, které odkazují na existující prostředky. Podívejte se na následující příklad, který ukazuje podmíněné přidání Redis nebo připojovacího řetězce na základě kontextu spuštění:

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

V předchozím kódu:

  • Pokud je hostitel aplikace v režimu spuštění, přidá se prostředek kontejneru Redis .
  • Pokud je hostitel aplikace v režimu publikování, přidá se připojovací řetězec.

Tato logika se dá snadno převrátit pro připojení k existujícímu Redis prostředku, když běžíte lokálně, a vytvoření nového Redis prostředku, když publikujete.

Důležitý

.NET .NET Aspire poskytuje běžná rozhraní API pro řízení způsobu vytváření prostředků, což umožňuje, aby se prostředky chovaly jinak v závislosti na režimu provádění. Rozhraní API fluent mají předponu RunAs* a PublishAs*. Rozhraní API RunAs* ovlivňují chování místního vývoje (nebo režimu spuštění), zatímco rozhraní API PublishAs* ovlivňují publikování zdroje. Další informace o tom, jak prostředky Azure používají tato rozhraní API, najdete v tématu Použití existujících prostředků Azure.

Viz také