Aspire översikt över orkestrering

Aspire tillhandahåller API:er för att uttrycka resurser och beroenden i ditt distribuerade program. Utöver dessa API:er finns det verktyg som möjliggör flera övertygande scenarier. Orkestratorn är avsedd för lokal utveckling och stöds inte i produktionsmiljöer.

Innan du fortsätter bör du överväga någon vanlig terminologi som används i Aspire:

• Appmodell: En samling resurser som utgör ditt distribuerade program (DistributedApplication), som definierats i Aspire.Hosting.ApplicationModel namnområdet. En mer formell definition finns i Definiera appmodellen.
• AppHost/Orchestrator-projekt: Projektet .NET som samordnar appmodellen med namnet *. AppHost-suffix (enligt konvention).
• Resurs: En resurs är en beroende del av ett program, till exempel ett projekt, en container, en körbar fil, en databas, en cache eller en .NET molntjänst. Den representerar alla delar av programmet som kan hanteras eller refereras till.
• Integrering: En integrering är ett NuGet-paket för antingen AppHost som modellerar en resurs eller ett paket som konfigurerar en klient för användning i en förbrukande app. Mer information finns i Aspire översikten över integreringar.
• Referens: En referens definierar en anslutning mellan resurser, uttryckt som ett beroende med hjälp av API:et WithReference . Mer information finns i Referensresurser eller Referera till befintliga resurser.

Obs

AspireOrkestreringen är utformad för att förbättra din lokala utvecklingsupplevelse genom att förenkla hanteringen av din molnbaserade appkonfiguration och sammankopplingar. Även om det är ett ovärderligt verktyg för utveckling är det inte avsett att ersätta produktionsmiljösystem som Kubernetes, som är särskilt utformade för att fungera i det sammanhanget.

Definiera appmodellen

Aspire gör att du effektivt kan skapa, etablera, distribuera, konfigurera, testa, köra och övervaka dina distribuerade program. De här funktionerna drivs av en appmodell som definierar resurserna i din Aspire lösning och deras sammankopplingar.

Appmodellen är mer än bara en lista över resurser – den representerar programmets fullständiga topologi. Detta inkluderar relationerna mellan resurser, deras beroenden och deras konfigurationer. Resurser kan omfatta projekt, körbara filer, containrar, externa tjänster och molnresurser som programmet förlitar sig på.

I DittAspire AppHost-projektProgram definierar filen din appmodell:

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

När du anropar DistributedApplication.CreateBuilderfår du en instans av IDistributedApplicationBuilder, som används för att konfigurera din appmodell. Den här byggaren tillhandahåller metoder för att lägga till resurser, definiera beroenden och konfigurera programmets övergripande struktur. När du har lagt till resurser anropar du Build för att skapa appmodellen. Mallarna innehåller kod som kedjar ett anrop till Build()– som returnerar en DistributedApplication instans och sedan anropar Run().

AppHost-projekt

AppHost-projektet hanterar körningen av alla projekt som ingår i Aspire projektet. Med andra ord ansvarar den för att orkestrera alla appar i appmodellen. Själva projektet är ett .NET körbart projekt som använder SDK:etAspire. Från och med Aspire 13.0 kan Aspire.AppHost.Sdk anges som det enda project-SDK:t, som implicit lägger till en paketreferens till 📦Aspire. Hosting.AppHost NuGet-paketet.

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

    <!-- Omitted for brevity -->

</Project>

Obs

Den alternativa metoden för att uttryckligen lista SDK och paketreferens fungerar fortfarande och är inte ett krav för att ändra befintliga projekt:

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

Följande kod beskriver en AppHost Program med två projektreferenser och en 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();

Föregående kod:

• Skapar en ny appmodellbyggare med hjälp av metoden CreateBuilder.
• Lägger till en Rediscache resurs med namnet "cache" med hjälp av metoden AddRedis.
• Lägger till en projektresurs med namnet "apiservice" med hjälp av metoden AddProject.
• Lägger till en projektresurs med namnet "webfrontend" med hjälp av metoden AddProject.
  • Anger att projektet har externa HTTP-slutpunkter med hjälp av metoden WithExternalHttpEndpoints.
  • Lägger till en referens till resursen cache och väntar tills den är klar med hjälp av metoderna WithReference och WaitFor.
  • Lägger till en referens till resursen apiservice och väntar tills den är klar med hjälp av metoderna WithReference och WaitFor.
• Skapar och kör appmodellen med hjälp av metoderna Build och Run.

Exempelkoden använder värdmiljöintegrationAspireRedis.

Tänk på följande diagram för att visualisera relationen mellan AppHost-projektet och de resurser som beskrivs:

Varje resurs måste ha ett unikt namn. Det här diagrammet visar varje resurs och relationerna mellan dem. Containerresursen heter "cache" och projektresurserna heter "apiservice" och "webfrontend". Webbklientdelsprojektet refererar till cache- och API-tjänstprojekten. När du uttrycker referenser på det här sättet säger webbklientdelsprojektet att det beror på dessa två resurser, "cache" respektive "apiservice".

Inbyggda resurstyper

Aspire projekt består av en uppsättning resurser. De primära basresurstyperna 📦Aspirei . Hosting.AppHost NuGet-paketet beskrivs i följande tabell:

Metod	Resurstyp	Beskrivning
AddProject	ProjectResource	Ett .NET projekt, till exempel en ASP.NET Core webbapp.
AddCSharpApp	CSharpAppResource	Ett C#-projekt eller en filbaserad app, till exempel en *.cs-fil , *.csproj-fil eller projektkatalog.
AddContainer	ContainerResource	En containeravbildning, till exempel en Docker avbildning.
AddExecutable	ExecutableResource	En körbar fil, till exempel en Node.js app.
AddParameter	ParameterResource	En parameterresurs som kan användas för att uttrycka externa parametrar.

Projektresurser representerar .NET projekt som ingår i appmodellen. När du lägger till en projektreferens till AppHost-projektet Aspire genererar SDK:t en typ i Projects namnområdet för varje refererat projekt. Mer information finns i Aspire SDK: Projektreferenser. Du kan också lägga till C#-projekt eller filbaserade appar utan en projektreferens med hjälp av AddCSharpApp metoden.

Om du vill lägga till ett projekt i appmodellen använder du metoden AddProject:

var builder = DistributedApplication.CreateBuilder(args);

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

Projekt kan replikeras och skalas ut genom att lägga till flera instanser av samma projekt i appmodellen. Om du vill konfigurera repliker använder du metoden 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);

Föregående kod lägger till tre repliker av projektresursen "apiservice" i appmodellen. Mer information finns påAspire instrumentpanelen: Resursrepliker.

C#-appresurser representerar C#-projekt eller filbaserade appar som ingår i appmodellen. Till skillnad från AddProject, som kräver en projektreferens, AddCSharpApp kan metoden lägga till C#-projekt eller filbaserade appar med hjälp av en sökväg till en *.cs-fil , *.csproj-fil eller projektkatalog. Detta är användbart för att lägga till filbaserade appar som introduceras i .NET 10 eller för att inkludera projekt utan att lägga till en projektreferens till AppHost.

Om du vill lägga till en C#-app i appmodellen använder du AddCSharpApp metoden:

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

Metoden AddCSharpApp stöder samma konfigurationsalternativ som AddProject, inklusive repliker, miljövariabler och resursberoenden.

Obs

Metoden AddCSharpApp är markerad som experimentell och kräver .NET 10 SDK för filbaserat C#-appstöd. Mer information om filbaserade appar finns i dokumentationen Nyheter i Aspire 9.5 .

Referensresurser

En referens representerar ett beroende mellan resurser. Du kan till exempel förmodligen föreställa dig ett scenario där en webbklientdel är beroende av en Redis cache. Tänk dig följande exempel på AppHost Program C#-kod:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Projektresursen "webfrontend" använder WithReference för att lägga till ett beroende av containerresursen "cache". Dessa beroenden kan representera anslutningssträngar eller information om tjänsteupptäckt. I föregående exempel matas en miljövariabel in i resursen "webfrontend" med namnet ConnectionStrings__cache. Den här miljövariabeln innehåller en anslutningssträng som webfrontend använder för att ansluta till Redis via AspireRedis-integreringen, till exempel ConnectionStrings__cache="localhost:62354".

Anslutningssträng och slutpunktsreferenser

Det är vanligt att uttrycka beroenden mellan projektresurser. Tänk på följande exempelkod:

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

Referenser från projekt till projekt hanteras på ett annat sätt än resurser som har väldefinierade anslutningssträngar. I stället för att anslutningssträngen matas in i resursen "webfrontend" matas miljövariabler som stöd för tjänstidentifiering in.

Metod	Miljövariabel
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"

Om du lägger till en referens till projektet "apiservice" läggs miljövariabler för tjänstidentifiering till i klientdelen. Det beror på att kommunikation mellan projekt vanligtvis sker via HTTP/gRPC.

Aspire matar in två typer av miljövariabler för tjänstreferenser:

• Förenklat format (t.ex. APISERVICE_HTTP): Använder mönstret {RESOURCENAME}_{ENDPOINTNAME} i versaler. Det här formatet är enklare och mer lämpligt för språk som inte är .NET och för flerspråkiga scenarier.
• .NET tjänstidentifieringsformat (t.ex. services__apiservice__http__0): Använder mönstret services__{servicename}__{endpointname}__{index} i gemener. Det här formatet används av .NET:s konfigurationsbaserade tjänstupptäckt.

Mer information finns i Aspire Tjänstidentifiering.

Om du vill hämta specifika slutpunkter från en ContainerResource eller en ExecutableResourceanvänder du något av följande slutpunkts-API:er:

• WithEndpoint
• WithHttpEndpoint
• WithHttpsEndpoint

Anropa sedan GetEndpoint-API:et för att hämta slutpunkten som kan användas för att referera till slutpunkten i metoden 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);

Metod	Miljövariabel
WithReference(endpoint)	MYAPP_ENDPOINT="https://localhost:9043" services__myapp__endpoint__0="https://localhost:9043"

Parametern port är porten som containern lyssnar på. Mer information om containerportar finns i Containerportar. Mer information om tjänstidentifiering finns i Aspire Tjänstidentifiering.

Miljövariabelformat för tjänstslutpunktsmiljö

I föregående avsnitt används metoden WithReference för att uttrycka beroenden mellan resurser. När tjänstslutpunkter resulterar i att miljövariabler matas in i den beroende resursen kanske formatet inte är uppenbart. Det här avsnittet innehåller information om tillgängliga format.

När en resurs är beroende av en annan resurs matar AppHost in miljövariabler i den beroende resursen. Dessa miljövariabler konfigurerar den beroende resursen för att ansluta till den resurs som den är beroende av. Aspire innehåller två miljövariabelformat som stöder olika scenarier:

Förenklat format (polyglotvänligt)

Det förenklade formatet använder mönstret {RESOURCENAME}_{ENDPOINTNAME} i versaler. Det här formatet är enklare att använda från icke-språk.NET och rekommenderas för flerspråkiga scenarier.

Överväg följande miljövariabelexempel:

APISERVICE_HTTP
APISERVICE_HTTPS

Föregående miljövariabler uttrycker HTTP- och HTTPS-slutpunkter för apiservice tjänsten. En namngiven slutpunkt kan uttryckas på följande sätt:

APISERVICE_MYENDPOINT

I föregående exempel har apiservice-tjänsten en namngiven slutpunkt med namnet myendpoint.

Obs

Miljövariabelnamnet baseras på resursnamnet, inte den valfria anslutningsnamnsparametern. Även när du använder WithReference(resource, "customname") för att ange ett anpassat anslutningsnamn använder de genererade miljövariablerna fortfarande resursens namn (t.ex. APISERVICE_HTTP), inte det anpassade namnet.

.NET tjänstidentifieringsformat

Tjänstidentifieringsformatet .NET används av .NETkonfigurationsbaserad tjänstidentifiering. Namn på tjänstslutpunktsmiljövariabler är försedda med prefixet services__ (dubbelt understreck), följt av tjänstens namn, slutpunktens namn och slutligen indexet. Indexet stöder flera slutpunkter för en enda tjänst, från och med 0 för den första slutpunkten och ökar för varje slutpunkt.

Överväg följande miljövariabelexempel:

services__apiservice__http__0
services__apiservice__https__0

Föregående miljövariabler uttrycker de första HTTP- och HTTPS-slutpunkterna för apiservice tjänsten. En namngiven slutpunkt kan uttryckas på följande sätt:

APISERVICE_MYENDPOINT

I föregående exempel har apiservice-tjänsten en namngiven slutpunkt med namnet myendpoint.

Använda en specifik slutpunkt med WithEnvironment

Om du vill ange ett namn på en anpassad miljövariabel för en specifik slutpunkt använder du WithEnvironment metoden kombinerad med GetEndpoint:

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

Detta genererar en enskild miljövariabel PROJECTA_URL med HTTPS-slutpunkts-URL:en för projecta tjänsten.

Referera till befintliga resurser

Vissa situationer garanterar att du refererar till en befintlig resurs, kanske en som distribueras till en molnleverantör. Du kanske till exempel vill referera till en Azure databas. I det här fallet förlitar du dig på körningskontexten för att dynamiskt avgöra om AppHost körs i "körningsläge" eller "publicera"-läge. Om du kör lokalt och vill förlita dig på en molnresurs kan du använda egenskapen IsRunMode för att villkorligt lägga till referensen. Du kan välja att i stället skapa resursen i publiceringsläge. Vissa värdintegreringar stöder att leverera en anslutningssträng direkt, vilket kan användas för att referera en befintlig resurs.

På samma sätt kan det finnas användningsfall där du vill integrera Aspire i en befintlig lösning. En vanlig metod är att lägga Aspire till AppHost-projektet i en befintlig lösning. I din AppHost uttrycker du beroenden genom att lägga till projektreferenser till AppHost och skapa appmodellen. Ett projekt kan till exempel vara beroende av ett annat. Dessa beroenden uttrycks med hjälp av metoden WithReference. För mer information, se Lägg till Aspire till en befintlig .NET app.

Exekveringskontext

IDistributedApplicationBuilder Exponerar en körningskontext (DistributedApplicationExecutionContext), som innehåller information om den aktuella körningen av AppHost. Den här kontexten kan användas för att utvärdera om AppHost körs som "kör"-läge eller som en del av en publiceringsåtgärd. Tänk på följande egenskaper:

• IsRunMode: Returnerar true om den aktuella åtgärden körs.
• IsPublishMode: Returnerar true om den aktuella åtgärden är publicering.

Den här informationen kan vara användbar när du vill köra kod villkorligt baserat på den aktuella åtgärden. Tänk dig följande exempel som visar hur du använder egenskapen IsRunMode. I det här fallet används en tilläggsmetod för att generera ett stabilt nodnamn för RabbitMQ för lokala utvecklingskörningar.

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

Körningskontexten används ofta för att villkorligt lägga till resurser eller anslutningssträngar som pekar på befintliga resurser. Tänk dig följande exempel som visar hur du villkorligt lägger till Redis eller en anslutningssträng baserat på körningskontexten:

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

I föregående kod:

• Om AppHost är i "körningsläge" läggs en Redis containerresurs till.
• Om AppHost är i "publiceringsläge" läggs en anslutningssträng till.

Den här logiken kan enkelt inverteras för att ansluta till en befintlig Redis resurs när du kör lokalt och skapa en ny Redis resurs när du publicerar.

Viktig

Aspire innehåller vanliga API:er för att styra resursskaparnas modalitet, så att resurser kan bete sig annorlunda baserat på körningsläget. De flytande API:erna är prefixade med RunAs* och PublishAs*. De RunAs* API:erna påverkar beteendet för lokal utveckling (eller körningsläge), medan PublishAs* API:er påverkar publiceringen av resursen. Mer information om hur Azure resurserna använder dessa API:er finns i Använda befintliga Azure resurser.

Se även

• Samordna resurser i Aspire
• Aspire översikt över integreringar
• Aspire SDK
• Händelse i Aspire
• Tjänstidentifiering i Aspire
• Aspire standardinställningar för tjänsten
• Uttrycka externa parametrar
• Aspire Översikt över inre loopnätverk