Resources orkestreren in Aspire

In dit artikel leert u hoe u het gedrag van resources verder kunt aanpassen door code te schrijven in het AppHost-project. Een Aspireresource is een afhankelijk onderdeel van een cloudeigen toepassing. Resourcetypen zijn onder andere:

• .NET Project: Een aangepaste microservice, verantwoordelijk voor specifieke functionaliteit in uw cloudeigen toepassing en vaak gebouwd door een afzonderlijk team van ontwikkelaars.
• Uitvoerbaar: Als u microservices wilt bouwen met hulpprogramma's zoals Node.js of Orleans, worden ze uitgevoerd als uitvoerbare resources.
• Container: U kunt op basis van specifieke afbeeldingen containers toevoegen aan uw Docker oplossing.
• Integratieresources: integraties voegen vaak resources toe, zoals databases, caches en berichtenservices aan uw toepassing.
• Externe service: Vertegenwoordigt een API of service van derden waaraan uw toepassing afhankelijk is, maar die niet wordt beheerd door Aspire. Gebruik dit voor resources zoals openbare API's of SaaS-eindpunten.

Zie het overzicht van Aspire orkestratie voor de basisprincipes van orkestratie en hoe resources worden beheerdAspire.

Naamconventies voor resources

Resources in Aspire moeten de naamgevingsbeperkingen volgen die zijn ingesteld door Aspire en de technologie die de resource vertegenwoordigt. Een Aspire resource heeft bijvoorbeeld een maximale naamlengte van 64 tekens, maar een Azure container-app heeft een maximale lengte van 32. Wanneer u de Aspire containerresource publiceert Azure, mag de naam niet langer zijn dan 32 tekens.

Aspire resource-namen moeten aan de volgende basisregels voldoen:

• Moet tussen de 1 en 64 tekens lang zijn.
• Moet beginnen met een ASCII-letter.
• Mag alleen ASCII-letters, cijfers en afbreekstreepjes bevatten.
• Mag niet eindigen met een afbreekstreepje.
• Mag geen opeenvolgende afbreekstreepjes bevatten.

Configureren van expliciete bronstart

Project-, uitvoerbare en containerbronnen worden standaard automatisch gestart met uw gedistribueerde toepassing. Een resource kan worden geconfigureerd om te wachten op een expliciete opstartinstructie met de methode WithExplicitStart. Een resource die is geconfigureerd met WithExplicitStart wordt geïnitialiseerd met 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();

In de voorgaande code is de "dbmigration" resource zo geconfigureerd dat deze niet automatisch begint met de gedistribueerde toepassing.

Resources met expliciete start kunnen vanuit het Aspire dashboard worden gestart door op de opdracht Start te klikken. Zie het dashboard: Een resource stoppen of starten voor meer informatieAspire.

Wachten op middelen

In sommige gevallen wilt u wellicht wachten totdat een resource gereed is voordat u een andere resource start. U kunt bijvoorbeeld wachten totdat een database gereed is voordat u een API start die ervan afhankelijk is. Als u deze afhankelijkheid wilt uitdrukken, gebruikt u de methode WaitFor:

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

In de voorgaande code wacht de projectresource 'apiservice' totdat de postgresdb-databaseresource de KnownResourceStates.Running status heeft ingevoerd. In de voorbeeldcode ziet u de AspirePostgreSQL integratie, maar hetzelfde patroon kan worden toegepast op andere resources.

In andere gevallen kan het nodig zijn om te wachten tot een resource is voltooid, of dat nu KnownResourceStates.Exited of KnownResourceStates.Finished is, voordat de afhankelijke resource start. Als u wilt wachten totdat een resource is voltooid, gebruikt u de methode 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);

In de voorgaande code wacht de projectresource 'apiservice' totdat de projectresource 'migratie' is voltooid voordat deze wordt gestart. De projectresource 'migratie' wacht tot de postgresdb-databaseresource de KnownResourceStates.Running status heeft ingevoerd. Dit kan handig zijn in scenario's waarin u bijvoorbeeld een databasemigratie wilt uitvoeren voordat u de API-service start.

Het afdwingen van de start van een resource in het dashboard

Wachten op een resource kan worden overgeslagen met behulp van de opdracht Start in het dashboard. Als u Start selecteert voor een wachtende resource in het dashboard, wordt de resource geïnstrueerd om onmiddellijk te beginnen zonder te wachten tot de resource in orde of voltooid is. Dit kan handig zijn als u een resource onmiddellijk wilt testen en niet wilt wachten totdat de app de juiste status heeft.

API's voor het toevoegen en uitdrukken van resources

Aspire hostingintegraties en clientintegraties worden beide geleverd als NuGet-pakketten, maar ze dienen verschillende doeleinden. Clientintegraties bieden clientbibliotheekconfiguratie voor het gebruik van apps buiten het bereik van AppHost, maar hostingintegraties bieden API's voor het uitdrukken van resources en afhankelijkheden binnen de AppHost. Zie Aspire het overzicht van integraties voor meer informatie: Integratieverantwoordelijkheden.

Express-containerresources

Als u een ContainerResource wilt uitdrukken, voegt u deze toe aan een IDistributedApplicationBuilder exemplaar door de methode AddContainer aan te roepen:

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

Met de voorgaande code wordt een containerresource met de naam 'ollama' toegevoegd met de afbeelding ollama/ollama. De containerresource is geconfigureerd met meerdere bind mounts, een benoemd HTTP-eindpunt, een invoerpunt dat wordt omgezet naar Unix shell script en argumenten voor het uitvoeren van containers met de WithContainerRuntimeArgs methode.

Containerbronnen aanpassen

Alle ContainerResource subklassen kunnen worden aangepast om te voldoen aan uw specifieke vereisten. Dit kan handig zijn bij het gebruik van een hostingintegratie die een containerresource modellt, maar wijzigingen vereist. Wanneer u een IResourceBuilder<ContainerResource> heeft, kunt u oproepen met elkaar verbinden naar een van de beschikbare API's om de containerbron aan te passen. Aspire containerbronnen verwijzen doorgaans naar vastgemaakte tags, maar u kunt in plaats daarvan de latest tag gebruiken.

Om dit te illustreren, stelt u zich een scenario voor waarin u de AspireRedis-integratiegebruikt. Als de Redis-integratie afhankelijk is van de 7.4-tag en u in plaats daarvan de latest-tag wilt gebruiken, kunt u een aanroep koppelen aan de WithImageTag-API:

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.

Zie ContainerResourceBuilderExtensionsvoor meer informatie en aanvullende API's.

Levenscyclus van containerbronnen

Wanneer de AppHost wordt uitgevoerd, wordt deze ContainerResource gebruikt om te bepalen welke containerinstallatiekopieën moeten worden gemaakt en gestart. Onder de motorkap voert Aspire de container uit met behulp van de gedefinieerde containerimage door oproepen te delegeren naar de juiste OCI-compatibele containerruntime, hetzij Docker of Podman. De volgende opdrachten worden gebruikt:

Naast de basisresourcetypen, ProjectResourceen ContainerResource, ExecutableResourceAspire biedt extensiemethoden voor het toevoegen van algemene resources aan uw app-model. Zie Hosting-integratiesvoor meer informatie.

Levensduur van een containerresource

Containerbronnen maken standaard gebruik van de levensduur van de sessie container. Dit betekent dat telkens wanneer het AppHost-proces wordt gestart, de container wordt gemaakt en gestart. Wanneer de AppHost stopt, wordt de container gestopt en verwijderd. Containerbronnen kunnen zich aanmelden voor een permanente levensduur om onnodig opnieuw opstarten te voorkomen en permanente containerstatus te gebruiken. Om dit te bereiken, koppelt u een aanroep van de ContainerResourceBuilderExtensions.WithLifetime-API en geeft ContainerLifetime.Persistent door.

var builder = DistributedApplication.CreateBuilder(args);

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

Met de voorgaande code wordt een containerresource met de naam 'ollama' met de afbeelding 'ollama/ollama' en een permanente levensduur toegevoegd.

Externe serviceresources voor Express

Externe services zijn API's van derden en services waarop uw toepassing afhankelijk is, maar die buiten uw Aspire oplossing bestaan. Deze services worden al elders uitgevoerd en worden niet beheerd door Aspire. Om een ExternalServiceResource uit te drukken, voegt u het toe aan een IDistributedApplicationBuilder exemplaar door de AddExternalService methode aan te roepen.

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

Met de voorgaande code wordt een externe serviceresource met de naam nuget toegevoegd die verwijst naar de NuGet-API. De externe service is geconfigureerd met een HTTP-statuscontrole om de beschikbaarheid ervan te controleren. Het front-endproject kan vervolgens verwijzen naar deze externe service voor servicedetectie.

Externe services ondersteunen verschillende configuratiemethoden:

Statische URL-configuratie

U kunt een externe service configureren met een statische URL met behulp van een tekenreeks of een 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);

Url-configuratie op basis van parameters

Voor scenario's waarin de URL van de externe service kan variëren tussen omgevingen of moet kunnen worden geconfigureerd, kunt u parameters gebruiken:

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

Wanneer u een configuratie op basis van parameters gebruikt, kan de URL-waarde worden ingesteld via configuratie, omgevingsvariabelen of gebruikersgeheimen. Tijdens de ontwikkeling Aspire wordt u mogelijk gevraagd om de URL-waarde op te geven. Zie Externe parametersvoor meer informatie.

Url-vereisten voor externe service

Externe service-URL's moeten voldoen aan specifieke vereisten:

• Moet een absolute URI zijn (inclusief schema, host en optionele poort).
• Het absolute pad moet zijn ingesteld op '/' (geen extra padsegmenten).
• Mag geen queryparameters of fragmenten bevatten.

Geldige voorbeelden:

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

Ongeldige voorbeelden:

• https://api.example.com/v1/api (bevat pad)
• https://api.example.com/?version=1 (bevat query)
• https://api.example.com/#section (bevat fragment)

Gezondheidscontroles voor externe services

Externe services kunnen worden geconfigureerd met HTTP-statuscontroles om hun beschikbaarheid te bewaken:

var builder = DistributedApplication.CreateBuilder(args);

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

Met de WithHttpHealthCheck methode wordt een statuscontrole toegevoegd die de externe service periodiek opvraagt. U kunt het volgende opgeven:

• path: het relatieve pad voor het eindpunt van de statuscontrole (optioneel, wordt standaard ingesteld op geen extra pad).
• statusCode: De verwachte HTTP-statuscode (optioneel, wordt standaard ingesteld op 200).

Servicedetectie met externe services

Wanneer u vanuit een andere resource naar een externe service verwijst, Aspire configureert u automatisch servicedetectie door omgevingsvariabelen in de standaardindeling te injecteren:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Deze configuratie injecteert een omgevingsvariabele zoals services__api__https__0=https://api.example.com/ in het front-endproject, waardoor servicedetectie mogelijk wordt gemaakt via de standaardmechanismen .NET voor servicedetectie.

Levenscyclus van externe service

Externe services implementeren IResourceWithoutLifetime, wat betekent dat ze niet worden beheerd door Aspirehet levenscyclussysteem. Ze worden naar verwachting onafhankelijk uitgevoerd. Tijdens de ontwikkelfase verschijnen externe services in het Aspire dashboard met de status 'Actief' als ze bereikbaar zijn, of ze laten gezondheidscontrolefouten zien als ze niet beschikbaar zijn.

Resource relaties

Resourcerelaties koppelen resources aan elkaar. Relaties zijn informatief en hebben geen invloed op het runtimegedrag van een app. In plaats daarvan worden ze gebruikt bij het weergeven van details over resources in het dashboard. Relaties zijn bijvoorbeeld zichtbaar in de resourcedetails van het -dashboard, en de Parent-relaties bepalen de resource-inbedding op de resources-pagina.

Relaties worden automatisch gemaakt door sommige app-model-API's. Voorbeeld:

• WithReference voegt een relatie toe aan de doelresource met het type Reference.
• WaitFor voegt een relatie toe aan de doelresource met het type WaitFor.
• Als u een database toevoegt aan een DB-container, wordt er een relatie tussen de database en de container gemaakt met het type Parent.

Relaties kunnen ook expliciet aan het app-model worden toegevoegd met behulp van WithRelationship en 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();

In het voorgaande voorbeeld wordt WithParentRelationship gebruikt om de database catalogdb als bovenliggend project voor migration te configureren. De Parent-relatie is speciaal omdat hiermee het nesten van resources op de pagina met resources wordt gecontroleerd. In dit voorbeeld is migration genest onder catalogdb.

Zie ook

• Aspire orkestratieoverzicht
• Gebeurtenis in Aspire