Samordna resurser i Aspire

I den här artikeln lär du dig att anpassa resursernas beteende ytterligare genom att skriva kod i AppHost-projektet. I Aspireär en resurs en beroende del av ett molnbaserat program. Här är några av resurstyperna:

• .NET Projekt: En anpassad mikrotjänst som ansvarar för specifika funktioner i ditt molnbaserade program och som ofta skapas av ett separat team med utvecklare.
• Körbar: Om du behöver skapa mikrotjänster med verktyg som Node.js eller Orleanskörs de som körbara resurser.
• Container: Du kan lägga till Docker containrar baserat på specifika avbildningar i din Aspire lösning.
• Integreringsresurser: Integreringar lägger ofta till resurser som databaser, cacheminnen och meddelandetjänster i ditt program.
• Extern tjänst: Representerar ett API eller en tjänst från tredje part som ditt program är beroende av men inte hanteras av Aspire. Använd detta för resurser som offentliga API:er eller SaaS-slutpunkter.

Grunderna Aspire för orkestrering och hur den hanterar resurser Aspire finns i översikt över orkestrering.

Namngivningskonventioner för resurser

Resurser i Aspire måste följa namngivningsbegränsningarna som anges av Aspire och den teknik som resursen representerar. En resurs har till exempel Aspire en maximal namnlängd på 64 tecken, men en Azure containerapp har en maximal längd på 32. När du publicerar containerresursen Aspire för Azurefår namnet inte vara längre än 32 tecken.

Aspire resursnamn måste följa dessa grundläggande regler:

• Måste vara mellan 1 och 64 tecken långt.
• Måste börja med en ASCII-bokstav.
• Får endast innehålla ASCII-bokstäver, siffror och bindestreck.
• Får inte sluta med ett bindestreck.
• Får inte innehålla bindestreck i följd.

Konfigurera start för explicit resurs

Projekt-, körbara och containerresurser startas automatiskt med ditt distribuerade program som standard. En resurs kan konfigureras för att vänta på en explicit startinstruktion med metoden WithExplicitStart. En resurs som konfigurerats med WithExplicitStart initieras med KnownResourceStates.NotStarted.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

builder.AddProject<Projects.AspireApp_DbMigration>("dbmigration")
       .WithReference(postgresdb)
       .WithExplicitStart();

I föregående kod konfigureras resursen så att den "dbmigration" inte startar automatiskt med det distribuerade programmet.

Resurser med tydlig start kan startas från Aspire instrumentpanelen genom att klicka på kommandot "Start". Mer information finns påAspire instrumentpanelen: Stoppa eller Starta en resurs.

Väntar på resurser

I vissa fall kanske du vill vänta tills en resurs är klar innan du startar en annan resurs. Du kanske till exempel vill vänta tills en databas är klar innan du startar ett API som är beroende av den. Använd metoden WaitFor för att uttrycka det här beroendet:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
       .WithReference(postgresdb)
       .WaitFor(postgresdb);

I föregående kod väntar projektresursen "apiservice" på att databasresursen "postgresdb" ska ange KnownResourceStates.Running tillståndet. Exempelkoden visar AspirePostgreSQL integrering, men samma mönster kan tillämpas på andra resurser.

Andra fall kan kräva att man väntar tills en resurs körs klart, antingen KnownResourceStates.Exited eller KnownResourceStates.Finished, innan den beroende resursen kan börja. För att vänta tills en resurs har körts klart, använd metoden WaitForCompletion:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var migration = builder.AddProject<Projects.AspireApp_Migration>("migration")
                       .WithReference(postgresdb)
                       .WaitFor(postgresdb);

builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
       .WithReference(postgresdb)
       .WaitForCompletion(migration);

I den föregående koden väntar projektresursen "apiservice" på att projektresursen "migrering" ska köras klart innan den startar. Projektresursen "migrering" väntar på att databasresursen "postgresdb" ska ange KnownResourceStates.Running tillståndet. Detta kan vara användbart i scenarier där du till exempel vill köra en databasmigrering innan du startar API-tjänsten.

Tvinga resursstart på instrumentpanelen

Du kan kringgå att vänta på en resurs med hjälp av startkommandot på instrumentpanelen. Om du väljer Starta på en väntande resurs på instrumentpanelen instrueras den att starta omedelbart utan att vänta på att resursen ska vara felfri eller slutförd. Detta kan vara användbart när du vill testa en resurs omedelbart och inte vill vänta tills appen har rätt tillstånd.

API:er för att lägga till och uttrycka resurser

Aspire värdintegreringar och klientintegreringar levereras båda som NuGet-paket, men de har olika syften. Även om klientintegreringar ger klientbibliotekskonfiguration för användning av appar utanför AppHosts omfång, tillhandahåller värdintegreringar API:er för att uttrycka resurser och beroenden i AppHost. Mer information finns i Aspire integrationsöversikt: Integrationsansvar.

Expresscontainerresurser

För att uttrycka en ContainerResource lägger du till den i en IDistributedApplicationBuilder-instans genom att anropa metoden AddContainer:

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddContainer("ollama", "ollama/ollama")
    .WithBindMount("ollama", "/root/.ollama")
    .WithBindMount("./ollamaconfig", "/usr/config")
    .WithHttpEndpoint(port: 11434, targetPort: 11434, name: "ollama")
    .WithEntrypoint("/usr/config/entrypoint.sh")
    .WithContainerRuntimeArgs("--gpus=all");

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddContainer("ollama", "ollama/ollama")
    .WithBindMount("ollama", "/root/.ollama")
    .WithBindMount("./ollamaconfig", "/usr/config")
    .WithHttpEndpoint(port: 11434, targetPort: 11434, name: "ollama")
    .WithEntrypoint("/usr/config/entrypoint.sh")
    .WithContainerRuntimeArgs("--device", "nvidia.com/gpu=all");

Föregående kod lägger till en containerresurs med namnet "ollama" med avbildningen ollama/ollama. Containerresursen konfigureras med flera bind-mounts, en namngiven HTTP-slutpunkt, en startpunkt som leder till Unix shell-skript och containerkörningsargument med metoden WithContainerRuntimeArgs.

Anpassa containerresurser

Alla ContainerResource underklasser kan anpassas för att uppfylla dina specifika krav. Detta kan vara användbart när du använder en hostingintegration som modellerar en containerresurs, men som dock kräver modifieringar. När du har en IResourceBuilder<ContainerResource> kan du länka anrop till någon av de tillgängliga API:erna för att ändra containerresursen. Aspire containerresurser pekar vanligtvis på fästa taggar, men du kanske vill använda taggen latest i stället.

Tänk dig ett scenario där du använder AspireRedis integrationför att hjälpa till att illustrera detta. Om Redis-integreringen förlitar sig på taggen 7.4 och du vill använda taggen latest i stället kan du länka ett anrop till WithImageTag-API:et:

var builder = DistributedApplication.CreateBuilder(args);

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

// Instead of using the "7.4" tag, the "cache" 
// container resource now uses the "latest" tag.

Mer information och ytterligare API:er finns i ContainerResourceBuilderExtensions.

Livscykel för containerresurser

När AppHost körs används den ContainerResource för att avgöra vilken containeravbildning som ska skapas och startas. I bakgrunden kör Aspire containern med den definierade containeravbilden genom att överföra anrop till en lämplig OCI-kompatibel container-runtime, antingen Docker eller Podman. Följande kommandon används:

Utöver de grundläggande resurstyperna ProjectResourcetillhandahåller , ContainerResourceoch ExecutableResource, Aspire tilläggsmetoder för att lägga till vanliga resurser i din appmodell. För mer information, se Hostingintegrationer.

Livslängd för containerresurser

Som standard använder containerresurser session containerns livslängd. Det innebär att varje gång AppHost-processen startas skapas och startas containern. När AppHost stoppas stoppas och tas containern bort. Containerresurser kan välja en beständig livslängd för att undvika onödiga omstarter och bevara containertillståndet. För att uppnå detta kedjar du ett anrop till ContainerResourceBuilderExtensions.WithLifetime-API:et och skickar ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddContainer("ollama", "ollama/ollama")
    .WithLifetime(ContainerLifetime.Persistent);

Föregående kod lägger till en containerresurs med namnet "ollama" med avbildningen "ollama/ollama" och en beständig livslängd.

Express-resurser för externa tjänster

Externa tjänster är API:er och tjänster från tredje part som ditt program är beroende av men som finns utanför din Aspire lösning. Dessa tjänster körs redan någon annanstans och hanteras inte av Aspire. För att uttrycka en ExternalServiceResource du lägger till den i en IDistributedApplicationBuilder instans genom att anropa AddExternalService metoden:

var builder = DistributedApplication.CreateBuilder(args);

var nuget = builder.AddExternalService("nuget", "https://api.nuget.org/")
    .WithHttpHealthCheck(path: "/v3/index.json");

var frontend = builder.AddProject<Projects.Frontend>("frontend")
    .WithReference(nuget);

Föregående kod lägger till en extern tjänstresurs med namnet "nuget" som pekar på NuGet-API:et. Den externa tjänsten har konfigurerats med en HTTP-hälsokontroll för att övervaka dess tillgänglighet. Klientdelsprojektet kan sedan referera till den här externa tjänsten för tjänstidentifiering.

Externa tjänster stöder flera konfigurationsmetoder:

Konfiguration av statisk URL

Du kan konfigurera en extern tjänst med en statisk URL med antingen en sträng eller en URI:

var builder = DistributedApplication.CreateBuilder(args);

// Using a string URL
var nuget = builder.AddExternalService("nuget", "https://api.nuget.org/");

// Using a URI
var uri = new Uri("https://api.example.com/");
var api = builder.AddExternalService("external-api", uri);

Parameterbaserad URL-konfiguration

I scenarier där url:en för den externa tjänsten kan variera mellan miljöer eller måste vara konfigurerbar kan du använda parametrar:

var builder = DistributedApplication.CreateBuilder(args);

var externalServiceUrl = builder.AddParameter("external-service-url");
var externalService = builder.AddExternalService("external-service", externalServiceUrl);

var frontend = builder.AddProject<Projects.Frontend>("frontend")
    .WithReference(externalService);

När du använder parameterbaserad konfiguration kan URL-värdet anges via konfiguration, miljövariabler eller användarhemligheter. Under utvecklingen kan Aspire be dig att ange URL-värdet. Mer information finns i Externa parametrar.

Url-krav för externa tjänster

URL:er för externa tjänster måste uppfylla specifika krav:

• Måste vara en absolut URI (inklusive schema, värd och valfri port).
• Den absoluta sökvägen måste vara inställd på "/" (inga ytterligare sökvägssegment).
• Får inte innehålla frågeparametrar eller fragment.

Giltiga exempel:

• https://api.example.com/
• http://localhost:8080/
• https://service.example.com:9443/

Ogiltiga exempel:

• https://api.example.com/v1/api (innehåller sökväg)
• https://api.example.com/?version=1 (innehåller fråga)
• https://api.example.com/#section (innehåller fragment)

Hälsokontroller för externa tjänster

Externa tjänster kan konfigureras med HTTP-hälsokontroller för att övervaka deras tillgänglighet:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddExternalService("api", "https://api.example.com/")
    .WithHttpHealthCheck(path: "/health", statusCode: 200);

Metoden WithHttpHealthCheck lägger till en hälsokontroll som regelbundet avfrågar den externa tjänsten. Du kan ange:

• path: Den relativa sökvägen för slutpunkten för hälsokontroll (valfritt, standardinställningen är ingen ytterligare sökväg).
• statusCode: Den förväntade HTTP-statuskoden (valfritt, standardvärdet är 200).

Tjänstidentifiering med externa tjänster

När du refererar till en extern tjänst från en annan resurs Aspire konfigurerar du automatiskt tjänstidentifiering genom att mata in miljövariabler i standardformatet:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddExternalService("api", "https://api.example.com/");

var frontend = builder.AddProject<Projects.Frontend>("frontend")
    .WithReference(api);

Den här konfigurationen matar in en miljövariabel som services__api__https__0=https://api.example.com/ i klientdelsprojektet, vilket möjliggör tjänstidentifiering via standardmekanismerna .NET för tjänstidentifiering.

Livscykel för extern tjänst

Externa tjänster implementerar IResourceWithoutLifetime, vilket innebär att de inte hanteras av Aspirelivscykelsystemet. De förväntas köras oberoende av varandra. Under utvecklingen visas externa tjänster på Aspire instrumentpanelen med tillståndet "Körs" om de kan nås eller visar fel vid hälsokontroll om de inte är tillgängliga.

Resursrelationer

Resursrelationer länkar samman resurser. Relationer är informativa och påverkar inte applikationens körningsbeteende. I stället används de när du visar information om resurser på instrumentpanelen. Relationer visas till exempel i instrumentpanelens resursinformationoch Parent relationer styr resurskapsling på resurssidan.

Relationer skapas automatiskt av vissa appmodell-API:er. Till exempel:

• WithReference lägger till en relation till målresursen med typen Reference.
• WaitFor lägger till en relation till målresursen med typen WaitFor.
• Om du lägger till en databas i en DB-container skapas en relation från databasen till containern med typen Parent.

Relationer kan också uttryckligen läggas till i appmodellen med hjälp av WithRelationship och WithParentRelationship.

var builder = DistributedApplication.CreateBuilder(args);

var catalogDb = builder.AddPostgres("postgres")
                       .WithDataVolume()
                       .AddDatabase("catalogdb");

builder.AddProject<Projects.AspireApp_CatalogDbMigration>("migration")
       .WithReference(catalogDb)
       .WithParentRelationship(catalogDb);

builder.Build().Run();

I föregående exempel används WithParentRelationship för att konfigurera catalogdb databasen som migration projektets överordnade. Den Parent relationen är speciell eftersom den styr resurskapsling på resurssidan. I det här exemplet kapslas migration under catalogdb.

Se även

• Aspire översikt över orkestrering
• Händelse i Aspire