でリソースを調整する .NET.NET Aspire

2025-04-21

この記事では、アプリホストプロジェクトでコードを記述して、リソースの動作をさらにカスタマイズする方法について説明します。 .NET .NET Aspireでは、リソースはクラウドネイティブアプリケーションの依存部分です。リソースの種類は次のとおりです。

.NET プロジェクト: カスタムマイクロサービス。クラウドネイティブアプリケーションの特定の機能を担当し、多くの場合、別の開発者チームによって構築されます。
実行可能ファイル: Node.js や Orleansなどのツールを使用してマイクロサービスを構築する必要がある場合は、実行可能リソースとして実行されます。
コンテナー: 特定のイメージに基づいて Docker コンテナーを .NET Aspire ソリューションに追加できます。
統合リソース: 多くの場合、統合によって、データベース、キャッシュ、メッセージングサービスなどのリソースがアプリケーションに追加されます。

.NET .NET Aspire オーケストレーションの基礎とリソースの管理方法については、オーケストレーションの概要.NET.NET Aspire参照してください。

リソースの名前付け規則

.NET Aspire内のリソースは、.NET Aspireによって設定された名前付け制限と、リソースが表すテクノロジに従う必要があります。たとえば、 .NET Aspire リソースの名前の最大長は 64 文字ですが、 Azure Container App の最大長は 32 です。 Azureの.NET Aspire コンテナーリソースを発行する場合、名前の長さは 32 文字以下にする必要があります。

.NET .NET Aspire リソース名は、次の基本規則に従う必要があります。

長さは 1 ~ 64 文字にする必要があります。
ASCII 文字で始まる必要があります。
ASCII 文字、数字、ハイフンのみを含める必要があります。
ハイフンで終わる必要はありません。
連続するハイフンを含めてはなりません。

明示的なリソース開始を設定する

既定では、プロジェクト、実行可能ファイル、およびコンテナーリソースは、分散アプリケーションで自動的に開始されます。リソースは、WithExplicitStart メソッドを使用して明示的なスタートアップ命令を待機するように構成できます。 WithExplicitStart で構成されたリソースは、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();

上記のコードでは、 "dbmigration" リソースは、分散アプリケーションで自動的に開始されないように構成されています。

明示的に開始されたリソースは、.NET.NET Aspire ダッシュボードで [開始] コマンドをクリックして開始できます。詳細については、「.NET.NET Aspire ダッシュボード: リソースを停止または開始する」を参照してください。

リソース待ち

場合によっては、別のリソースを開始する前に、リソースの準備が整うのを待つ必要がある場合があります。たとえば、データベースに依存する API を開始する前に、データベースの準備が整うのを待つ必要がある場合があります。この依存関係を表すには、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);

前のコードでは、"apiservice" プロジェクトリソースは、"postgresdb" データベースリソースが KnownResourceStates.Running 状態になるまで待機します。コード例は、.NET AspirePostgreSQL 統合を示していますが、同じパターンを他のリソースに適用できます。

その他のケースでは、依存リソースが開始される前に、KnownResourceStates.Exited または KnownResourceStates.Finished のいずれかで、リソースの実行が完了するまで待機することが必要になる場合があります。リソースの実行が完了するまで待機するには、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);

前のコードでは、"apiservice" プロジェクトリソースは、"移行" プロジェクトリソースが完了するまで待機してから開始します。 "移行" プロジェクトリソースは、"postgresdb" データベースリソースが KnownResourceStates.Running 状態になるまで待機します。これは、たとえば、API サービスを開始する前にデータベース移行を実行するシナリオで役立ちます。

ダッシュボードでリソースを強制開始する

リソースの待機は、ダッシュボードの [開始 ] コマンドを使用してバイパスできます。ダッシュボードで [待機中のリソースで開始 ] を選択すると、リソースが正常または完了するのを待たずにすぐに開始するように指示されます。これは、リソースをすぐにテストし、アプリが正しい状態になるまで待たないようにする場合に便利です。

リソースを追加および表現するための API

.NET .NET Aspire ホスティング統合とクライアント統合はどちらも NuGet パッケージとして提供されますが、異なる目的で提供されます。 クライアント統合、アプリホストの範囲外でアプリを使用するためのクライアントライブラリ構成を提供しますが、ホスティング統合、アプリホスト内のリソースと依存関係を表す API を提供します。詳細については、「.NET.NET Aspire 統合の概要: 統合の責任」を参照してください。

エクスプレスコンテナリソース

ContainerResource を表現するには、IDistributedApplicationBuilder メソッドを呼び出して AddContainer インスタンスに追加します。

Docker
Podman

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

詳細については、 Desktopでの GPU サポート参照してください。

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

詳細については、の GPU サポートを参照してください。

上記のコードは、イメージ ollama/ollamaを持つ "ollama" という名前のコンテナーリソースを追加します。コンテナーリソースは、複数のバインドマウント、名前付き HTTP エンドポイント、Unix シェルスクリプトに解決されるエントリポイント、および WithContainerRuntimeArgs メソッドを使用したコンテナー実行引数で構成されます。

コンテナーリソースをカスタマイズする

すべての ContainerResource サブクラスは、特定の要件を満たすようにカスタマイズできます。これは、コンテナーリソースをモデル化するが変更が必要なホスティング統合を使用する場合に便利です。 IResourceBuilder<ContainerResource> がある場合は、使用可能な API の呼び出しをチェーンしてコンテナーリソースを変更できます。 .NET .NET Aspire コンテナーリソースは通常、ピン留めされたタグを指しますが、代わりに latest タグを使用することもできます。

これを例示するために、.NET AspireRedis 統合を使用しているシナリオを想像してください。 Redis 統合が 7.4 タグに依存していて、代わりに latest タグを使用する場合は、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.

使用可能なその他の API の詳細については、「ContainerResourceBuilderExtensions」を参照してください。

コンテナーリソースのライフサイクル

アプリホストを実行すると、ContainerResource を使用して、作成して開始するコンテナーイメージが決定されます。内部 .NET Aspire、Docker または Podmanのいずれかの適切な OCI 準拠コンテナーランタイムへの呼び出しを委任することで、定義されたコンテナーイメージを使用してコンテナーを実行します。次のコマンドが使用されます。

Docker
Podman

まず、docker container create コマンドを使用してコンテナーを作成します。次に、docker container start コマンドを使用してコンテナーが開始されます。

docker コンテナーの作成: 指定したイメージから開始せずに新しいコンテナーを作成します。
docker コンテナを起動: 1つ以上の停止したコンテナを起動します。

これらのコマンドは、接続されたコンテナーネットワーク、ボリューム、ポートを管理するために docker run の代わりに使用されます。これらのコマンドをこの順序で呼び出すと、初期起動時に IP (ネットワーク構成) が既に存在できるようになります。

まず、podman container create コマンドを使用してコンテナーを作成します。次に、podman container start コマンドを使用してコンテナーが開始されます。

podman コンテナーの作成: 指定したイメージ上に書き込み可能なコンテナーレイヤーを作成し、実行用に準備します。
podman container start: 停止したコンテナーを1つ以上開始する。

これらのコマンドは、接続されたコンテナーネットワーク、ボリューム、ポートを管理するために podman run の代わりに使用されます。これらのコマンドをこの順序で呼び出すと、初期起動時に IP (ネットワーク構成) が既に存在できるようになります。

基本リソースの種類、ProjectResource、ContainerResource、および ExecutableResource以外にも、.NET.NET Aspire は、アプリモデルに共通のリソースを追加するための拡張メソッドを提供します。詳細については、「ホスティング統合」を参照してください。

コンテナーリソースの有効期間

既定では、コンテナーリソースはコンテナーの有効期間セッションを使用します。つまり、アプリホストプロセスが開始されるたびに、コンテナーが作成されて開始されます。アプリホストが停止すると、コンテナーは停止され、削除されます。コンテナーリソースは、不要な再起動を回避し、永続化されたコンテナーの状態を使用するために、永続的な の有効期間にオプトインできます。これを実現するには、ContainerResourceBuilderExtensions.WithLifetime API の呼び出しをチェーンし、ContainerLifetime.Persistent渡します。

var builder = DistributedApplication.CreateBuilder(args);

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

上記のコードでは、イメージ "ollama/ollama" と永続的な有効期間を持つ "ollama" という名前のコンテナーリソースが追加されます。

リソースのリレーションシップ

リソースリレーションシップは、リソースをリンクします。リレーションシップは情報であり、アプリのランタイム動作には影響しません。代わりに、ダッシュボードにリソースに関する詳細を表示するときに使用されます。たとえば、リレーションシップはダッシュボードのリソースの詳細に表示され、Parent リレーションシップはリソースページでのリソースの入れ子を制御します。

リレーションシップは、一部のアプリモデル API によって自動的に作成されます。例えば次が挙げられます。

WithReference は、種類が Referenceのターゲットリソースにリレーションシップを追加します。
WaitFor は、種類が WaitForのターゲットリソースにリレーションシップを追加します。
データベースを DB コンテナーに追加すると、データベースからコンテナーへのリレーションシップが Parent型で作成されます。

リレーションシップは、WithRelationship と 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();

前の例では、WithParentRelationship を使用して、catalogdb プロジェクトの親として migration データベースを構成します。 Parent リレーションシップは、リソースページでのリソースの入れ子を制御するため、特別です。この例では、migration は catalogdbの下に組み込まれています。

注

親リレーションシップのバリデーションがあります。これにより、リソースが複数の親を持ったり、循環参照を作成したりすることが防止されます。これらの構成は UI 上でレンダリングされないため、アプリモデルがエラーを発生させます。

こちらも参照ください

.NET .NET Aspire オーケストレーション概要
.NET .NET Aspire におけるイベント

次の方法で共有