Sdílet prostřednictvím

Orchestrace prostředků v .NET.NET Aspire

V tomto článku se dozvíte, jak dále přizpůsobit chování prostředků napsáním kódu v hostitelském projektu aplikace. V .NET.NET Aspire je prostředek závislou částí cloudově nativní aplikace. Mezi typy prostředků patří:

  • .NET Projekt: Vlastní mikroslužba zodpovědná za konkrétní funkce v nativní cloudové aplikaci a často vytvořená samostatným týmem vývojářů.
  • Spustitelný soubor: Pokud potřebujete vytvořit mikroslužby s nástroji, jako jsou Node.js nebo Orleans, běží jako spustitelné prostředky.
  • Kontejner: Kontejnery můžete přidat Docker na základě konkrétních imagí do vašeho .NET Aspire řešení.
  • Prostředky integrace: Integrace často přidávají do aplikace prostředky, jako jsou databáze, mezipaměti a služby zasílání zpráv.

Základní informace o .NET.NET Aspire orchestraci a způsobu správy prostředků najdete .NET.NET Aspire v přehledu orchestrace.

Zásady vytváření názvů prostředků

Prostředky v .NET Aspire musí dodržovat omezení pojmenování nastavená .NET Aspire a technologií, kterou prostředek představuje. Například .NET Aspire prostředek má maximální délku názvu 64 znaků, ale Azure Kontejnerová aplikace má maximální délku 32 znaků. Při publikování prostředku kontejneru .NET Aspire nesmí název Azure překročit délku 32 znaků.

.NET .NET Aspire Názvy prostředků musí dodržovat tato základní pravidla:

  • Musí mít délku 1 až 64 znaků.
  • Musí začínat písmenem ASCII.
  • Musí obsahovat pouze písmena ASCII, číslice a pomlčky.
  • Nesmí končit spojovníkem.
  • Nesmí obsahovat po sobě jdoucí pomlčky.

Nakonfigurujte explicitní spuštění zdroje

Ve výchozím nastavení se prostředky projektu, spustitelné soubory a kontejnery automaticky spouštějí s vaší distribuovanou aplikací. Prostředek lze nakonfigurovat tak, aby čekal na explicitní spouštěcí instrukci pomocí metody WithExplicitStart. Prostředek nakonfigurovaný s WithExplicitStart se inicializuje pomocí 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();

V předchozím kódu je prostředek "dbmigration" nakonfigurován tak, aby se automaticky nespouštěl společně s distribuovanou aplikací.

Prostředky s explicitním startem je možné spustit z řídicího panelu .NET.NET Aspire kliknutím na příkaz Spustit. Další informace najdete na řídicím panelu: .NET.NET Aspire, Zastavení nebo spuštění prostředku.

Čekání na prostředky

V některých případech můžete chtít počkat, až bude prostředek připravený, než začnete s jiným prostředkem. Před spuštěním rozhraní API, které na něm závisí, můžete například chtít počkat, než bude databáze připravená. K vyjádření této závislosti použijte metodu 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);

V předchozím kódu prostředek projektu "apiservice" čeká, až prostředek databáze postgresdb přejde do KnownResourceStates.Running stavu. Ukázkový kód ukazuje .NET AspirePostgreSQL integraci, ale stejný vzor lze použít u jiných prostředků.

Jiné případy mohou vyžadovat čekání na dokončení prostředku, a to buď KnownResourceStates.Exited, nebo KnownResourceStates.Finished, než začne závislý prostředek. Pokud chcete počkat na dokončení zdroje, použijte metodu 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);

V předchozím kódu prostředek projektu "apiservice" čeká, až se prostředek projektu "migration" dokončí, a teprve poté začne. Projektový prostředek "migrace" čeká, až prostředek databáze "postgresdb" přejde do stavu KnownResourceStates.Running. To může být užitečné ve scénářích, kdy chcete spustit migraci databáze před spuštěním služby API, například.

Nucené spuštění prostředku na řídicím panelu

Čekání na prostředek je možné obejít pomocí příkazu Start na řídicím panelu. Když na řídicím panelu vyberete Start na čekající prostředek, dá se pokyn, aby se spustil okamžitě bez čekání na to, aby byl prostředek v pořádku nebo dokončený. To může být užitečné, když chcete okamžitě otestovat prostředek a nechcete čekat, až bude aplikace ve správném stavu.

Rozhraní API pro přidávání a zobrazení zdrojů

.NET .NET Aspire integrace pro hostování a integrace klientů se doručují jako balíčky NuGet, ale slouží různým účelům. I když klientské integrace poskytují konfiguraci klientské knihovny pro použití aplikací mimo rozsah hostitele aplikace, integrace hostování poskytují rozhraní API pro vyjádření prostředků a závislostí v rámci hostitele aplikace. Další informace najdete v tématu přehled integrace .NET.NET Aspire: odpovědnosti za integraci.

Prostředky kontejneru Express

Pokud chcete vyjádřit ContainerResource, přidáte ho do instance IDistributedApplicationBuilder voláním metody 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");

Další informace najdete v tématu podpora GPU v Docker Desktop.

Předchozí kód přidá kontejnerový zdroj s názvem "ollama" s image ollama/ollama. Prostředek kontejneru je nakonfigurován s několika bind mounty, pojmenovaným koncovým bodem HTTP, vstupním bodem, který odkazuje na shell skript Unix, a parametry spuštění kontejneru s metodou WithContainerRuntimeArgs.

Přizpůsobte prostředky kontejneru

Všechny podtřídy ContainerResource je možné přizpůsobit tak, aby splňovaly vaše konkrétní požadavky. Toto může být užitečné při použití hostovací integrace, která reprezentuje prostředek kontejneru, ale vyžaduje úpravy. Pokud máte IResourceBuilder<ContainerResource>, můžete zřetězovat volání na jakékoliv z dostupných rozhraní API pro úpravu zdroje kontejneru. .NET .NET Aspire kontejnerové prostředky obvykle odkazují na připnuté značky, ale možná byste chtěli použít značku latest místo toho.

Abychom vám to pomohli, představte si scénář, ve kterém používáte integraci .NET AspireRedis. Pokud integrace Redis spoléhá na značku 7.4 a chcete místo toho použít značku latest, můžete zřetězit volání na rozhraní API WithImageTag.

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.

Další informace a další dostupná rozhraní API najdete v tématu ContainerResourceBuilderExtensions.

Životní cyklus kontejnerových zdrojů

Při spuštění hostitele aplikace se ContainerResource použije k určení image kontejneru, která se má vytvořit a spustit. V zákulisí spustí .NET Aspire kontejner pomocí definovaného obrazu kontejneru delegováním volání na odpovídající kontejnerový runtime podle standardu OCI, buď Docker, nebo Podman. Používají se následující příkazy:

Nejprve se kontejner vytvoří pomocí příkazu docker container create. Kontejner se pak spustí pomocí příkazu docker container start.

Tyto příkazy se používají místo docker run ke správě připojených sítí kontejnerů, svazků a portů. Volání těchto příkazů v tomto pořadí umožňuje, aby již při počátečním spuštění byla přítomna jakákoli IP adresa (konfigurace sítě).

Kromě základních typů prostředků poskytuje ProjectResource, ContainerResourcea ExecutableResource, .NET.NET Aspire rozšiřující metody pro přidání běžných prostředků do modelu aplikace. Další informace najdete v tématu Integrace hostování.

Životnost zdroje kontejneru

Ve výchozím nastavení prostředky kontejneru používají životnost relace jako dobu životnosti kontejneru. To znamená, že při každém spuštění hostitelského procesu aplikace se kontejner vytvoří a spustí. Když se hostitel aplikace zastaví, kontejner se rovněž zastaví a je odstraněn. Prostředky kontejneru mohou zvolit trvalý režim, aby se zabránilo zbytečnému restartování a pro využití trvalého stavu kontejneru. Pokud toho chcete dosáhnout, použijte zřetězené volání rozhraní API ContainerResourceBuilderExtensions.WithLifetime a předejte ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

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

Předchozí kód přidá kontejnerový zdroj s názvem "ollama" s imagí "ollama/ollama" a perzistentní životností.

Vztahy zdrojů

Vztahy zdrojů spojují prostředky. Relace jsou informativní a nemají vliv na chování aplikace za běhu. Místo toho se používají při zobrazení podrobností o prostředcích na řídicím panelu. Relace jsou například viditelné v podrobnostech o prostředcích na řídicím panelu a Parent relace ovládají vnoření prostředků na stránce prostředků.

Relace se automaticky vytvářejí pomocí některých rozhraní API modelu aplikace. Například:

  • WithReference přidá vztah k cílovému zdroji s typem Reference.
  • WaitFor přidá vztah k cílovému zdroji s typem WaitFor.
  • Přidání databáze do kontejneru databáze vytvoří relaci z databáze do kontejneru s typem Parent.

Relace lze také explicitně přidat do modelu aplikace pomocí WithRelationship a 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();

Předchozí příklad používá WithParentRelationship ke konfiguraci catalogdb databáze jako nadřazeného projektu migration. Relace Parent je zvláštní, protože řídí vnoření prostředků na stránce zdrojů. V tomto příkladu je migration vnořený pod catalogdb.

Poznámka:

Pro vztahy rodiče existuje ověření, které brání prostředku mít více rodičů nebo vytvořit cyklický odkaz. Tyto konfigurace nelze vykreslit v uživatelském rozhraní a model aplikace vyvolá chybu.

Viz také