Aspire Přehled orchestrace

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 některé běžné terminologie použité v 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 AppHost/Orchestrator: .NET Projekt, který orchestruje model aplikace s názvem *. Přípona 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 appHost , který modeluje prostředek nebo balíček, který konfiguruje klienta pro použití v aplikaci využívající. Další informace najdete v přehleduAspire 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

AspireOrchestrace je navržena tak, aby zlepšila vaše místní vývojové prostředí zjednodušením správy konfigurace a propojení cloud-native 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

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

Aspire V projektu AppHost definuje váš Program soubor 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 AppHost

Projekt AppHost zpracovává spouštění všech projektů, které jsou součástí Aspire projektu. Jinými slovy, zodpovídá za orchestraci všech aplikací v modelu aplikace. Samotný projekt je .NET spustitelný projekt, který používá Aspire sadu SDK. Počínaje verzí Aspire 13.0 Aspire.AppHost.Sdk lze nastavit jako jedinou sadu SDK projektu, která implicitně přidá odkaz na NuGet balíček .📦Aspire Hosting.AppHost.

<Project Sdk="Aspire.AppHost.Sdk/13.0.0">
    
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net10.0</TargetFramework>
        <!-- Omitted for brevity -->
    </PropertyGroup>

    <!-- Omitted for brevity -->

</Project>

Poznámka

Alternativní přístup explicitního výpisu odkazů na sadu SDK a balíčků stále funguje a není nutné měnit stávající projekty:

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

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

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

    <!-- Omitted for brevity -->

</Project>

Následující kód popisuje AppHost 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.
- Určuje, že projekt má externí koncové body HTTP pomocí metody WithExternalHttpEndpoints.
- Přidá odkaz na prostředek cache a počká, až bude připravený pomocí metod WithReference a WaitFor.
- Přidá odkaz na prostředek apiservice a počká, až bude připravený pomocí metod WithReference a WaitFor.
Sestaví a spustí model aplikace pomocí Build a Run metod.

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

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

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ů

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.
`AddCSharpApp`	`CSharpAppResource`	Projekt nebo souborová aplikace jazyka C#, například soubor .cs , soubor .csproj nebo adresář projektu.
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 AppHost, Aspire sada SDK vygeneruje typ v Projects oboru názvů pro každý odkazovaný projekt. Další informace najdete v tématu Aspire SDK: Odkazy na projekt. Alternativně můžete přidat projekty jazyka C# nebo souborové aplikace bez odkazu na AddCSharpApp projekt pomocí metody.

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 najdete na Aspire řídicím panelu: Repliky prostředků.

Prostředky aplikace jazyka C# představují projekty c# nebo souborové aplikace, které jsou součástí modelu aplikace. Na rozdíl od AddProjectprojektu, který vyžaduje odkaz na projekt, AddCSharpApp může metoda přidat projekty jazyka C# nebo aplikace založené na souborech pomocí cesty k souboru *.cs , souboru *.csproj nebo adresáři projektu. To je užitečné pro přidávání souborových aplikací zavedených v .NET 10 nebo pro zahrnutí projektů bez přidání odkazu na projekt na AppHost.

Pokud chcete do modelu aplikace přidat aplikaci v jazyce C#, použijte metodu AddCSharpApp :

var builder = DistributedApplication.CreateBuilder(args);

// Adds a file-based C# app "inventoryservice" from a .cs file.
var inventoryService = builder.AddCSharpApp("inventoryservice", @"..\InventoryService.cs");

// Adds a C# project "catalogservice" from a project directory.
var catalogService = builder.AddCSharpApp("catalogservice", @"..\CatalogService");

Metoda AddCSharpApp podporuje stejné možnosti konfigurace jako AddProject, včetně replik, proměnných prostředí a závislostí prostředků.

Poznámka

Metoda AddCSharpApp je označena jako experimentální a vyžaduje .NET 10 SDK pro podporu souborových aplikací C#. Další informace o souborových aplikacích najdete v dokumentaci Novinky ve Aspire verzi 9.5.

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. Podívejte se na následující příklad kódu AppHost Program C#:

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 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)`	`APISERVICE_HTTP="http://localhost:5455"` `APISERVICE_HTTPS="https://localhost:7356"` `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.

Aspire vloží dva typy proměnných prostředí pro referencování služeb:

Zjednodušený formát (např APISERVICE_HTTP. ): Používá vzor {RESOURCENAME}_{ENDPOINTNAME} velkými písmeny. Tento formát je jednodušší a vhodnější pro jiné.NET jazyky a scénáře polyglotu.
.NET formát zjišťování služby (např services__apiservice__http__0. ): Používá vzor services__{servicename}__{endpointname}__{index} malými písmeny. Tento formát se používá .NETpři zjišťování služeb založených na konfiguraci.

Další informace najdete v tématu Aspire zjišťování služeb.

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)`	`MYAPP_ENDPOINT="https://localhost:9043"` `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žeb najdete v tématu Aspire zjišťování služeb.

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 dostupných formátech.

Pokud jeden prostředek závisí na jiném prostředku, AppHost 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í. Aspire poskytuje dva formáty proměnných prostředí pro podporu různých scénářů:

Zjednodušený formát (vhodný pro více jazyků)

Zjednodušený formát používá vzor {RESOURCENAME}_{ENDPOINTNAME} velkými písmeny. Tento formát se snadněji používá z jiných než .NET jazyků a doporučuje se pro vícejazyčné scénáře.

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

APISERVICE_HTTP
APISERVICE_HTTPS

Předchozí proměnné prostředí vyjadřují koncové body HTTP a HTTPS pro apiservice službu. Pojmenovaný koncový bod může být vyjádřen takto:

APISERVICE_MYENDPOINT

V předchozím příkladu má služba apiservice pojmenovaný koncový bod s názvem myendpoint.

Poznámka

Název proměnné prostředí je odvozen od názvu prostředku, nikoli od volitelného parametru názvu připojení. I když používáte WithReference(resource, "customname") k zadání vlastního názvu připojení, vygenerované proměnné prostředí stále používají název prostředku (např APISERVICE_HTTP. ), nikoli vlastní název.

.NET formát zjišťování služeb

Formát .NET pro zjišťování služeb se používá pro zjišťování služeb na základě konfigurace .NET. 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
services__apiservice__https__0

Předchozí proměnné prostředí vyjadřují první koncové body HTTP a HTTPS pro apiservice službu. Pojmenovaný koncový bod může být vyjádřen takto:

APISERVICE_MYENDPOINT

V předchozím příkladu má služba apiservice pojmenovaný koncový bod s názvem myendpoint.

Použití konkrétního koncového bodu s WithEnvironment

Pokud chcete zadat název vlastní proměnné prostředí pro konkrétní koncový bod, použijte metodu WithEnvironment v kombinaci s GetEndpoint:

var projectA = builder.AddProject<Projects.ProjectA>("projecta");
var projectB = builder.AddProject<Projects.ProjectB>("projectb")
                      .WithEnvironment("PROJECTA_URL", projectA.GetEndpoint("https"));

Tím se vygeneruje jedna proměnná PROJECTA_URL prostředí s adresou URL koncového projecta bodu HTTPS 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 k dynamickému určení, jestli je AppHost spuštěný v režimu spuštění nebo v režimu publikování, spoléháte na kontext spuště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ě můžou existovat případy použití, kdy chcete integrovat Aspire do stávajícího řešení. Jedním z běžných přístupů je přidání Aspire projektu AppHost do existujícího řešení. V rámci appHost vyjadřujete závislosti tak, že přidáte odkazy na projekt na AppHost a sestavíte model 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í Aspire do existující aplikace .NET.

Kontext spuštění

Zpřístupňuje IDistributedApplicationBuilder kontext spuštění (DistributedApplicationExecutionContext), který poskytuje informace o aktuálním spuštění AppHost. Tento kontext lze použít k vyhodnocení, jestli se AppHost spouští jako režim spuštění 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 AppHost v režimu spuštění, přidá se prostředek kontejneru Redis .
Pokud je AppHost 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ý

Aspire poskytuje běžná rozhraní API pro řízení způsobu vytváření prostředků, což umožňuje, aby se prostředky v závislosti na režimu provádění chovaly odliš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é

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-11-11

Sdílet prostřednictvím

Aspire Přehled orchestrace

Definování modelu aplikace

Projekt AppHost

Předdefinované typy prostředků

Referenční zdroje

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

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

Zjednodušený formát (vhodný pro více jazyků)

.NET formát zjišťování služeb

Použití konkrétního koncového bodu s WithEnvironment

Odkaz na existující prostředky

Kontext spuštění

Viz také

Váš názor

Další materiály