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.

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 refererar till 📦Aspire. Hosting.AppHost NuGet-paketet och använder Aspire SDK:

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

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

    <ItemGroup>
        <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.2" />
    </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:

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.

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.

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.

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

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 det här formatet.

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. Formatet för miljövariablerna är specifikt för Aspire och uttrycker tjänstslutpunkter på ett sätt som är kompatibelt med Service Discovery.

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

Den föregående miljövariabeln uttrycker den första HTTP-slutpunkten för apiservice-tjänsten. Värdet för miljövariabeln är URL:en för tjänstslutpunkten. En namngiven slutpunkt kan uttryckas på följande sätt:

services__apiservice__myendpoint__0

I föregående exempel har apiservice-tjänsten en namngiven slutpunkt med namnet myendpoint. Värdet för miljövariabeln är URL:en för tjänstslutpunkten.

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.

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