オーケストレーション .NET.NET Aspire の概要

.NET .NET Aspire には、分散アプリケーション内のリソースと依存関係を表す API が用意されています。 これらの API に加えて、いくつかの説得力のあるシナリオを可能にするツール があります。 オーケストレーターは、ローカル開発 を目的として意図されていますが、運用環境ではサポートされていません。

続行する前に、.NET.NET Aspireで使用される一般的な用語を検討してください。

• アプリ モデル: DistributedApplication 名前空間内で定義された分散アプリケーション (Aspire.Hosting.ApplicationModel) を構成するリソースのコレクション。 より正式な定義については、「アプリ モデルのを定義する」を参照してください。
• App host/Orchestrator プロジェクト: .NETをオーケストレーションするプロジェクトで、慣例により*.AppHostサフィックスが名前に付けられます。
• リソース: リソース は、.NET プロジェクト、コンテナー、実行可能ファイル、データベース、キャッシュ、クラウド サービスなどのアプリケーションの依存部分です。 これは、管理または参照できるアプリケーションの任意の部分を表します。
• 統合: 統合とは、リソース をモデル化する アプリ ホスト、または使用しているアプリで使用するクライアントを構成するパッケージのいずれかの NuGet パッケージです。 詳細については、.NET.NET Aspire 統合の概要を参照してください。
• リファレンス: WithReference API を使用して依存関係として表されるリソース間の接続を定義します。 詳細については、「リソース 参照」または「既存のリソースを参照する」を参照してください。

アプリ モデルを定義する

.NET .NET Aspire を使用すると、分散アプリケーションのビルド、プロビジョニング、デプロイ、構成、テスト、実行、監視を効率的に行うことができます。 これらの機能は、.NET.NET Aspire ソリューション内のリソースとその相互接続を定義するアプリ モデルを利用します。

アプリ モデルは単なるリソースの一覧ではなく、アプリケーションの完全なトポロジを表します。 これには、リソース間の関係、依存関係、およびそれらの構成が含まれます。 リソースには、アプリケーションが依存するプロジェクト、実行可能ファイル、コンテナー、外部サービス、クラウド リソースを含めることができます。

.NET .NET Aspire アプリ ホスト プロジェクトでは、Program ファイルによってアプリ モデルが定義されます。

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

DistributedApplication.CreateBuilderを呼び出すと、アプリ モデルの構成に使用されるIDistributedApplicationBuilderのインスタンスが取得されます。 このビルダーには、リソースの追加、依存関係の定義、アプリケーションの全体的な構造の設定を行うメソッドが用意されています。 リソースを追加したら、 Build を呼び出してアプリ モデルを作成します。 テンプレートには、Build()への呼び出しをチェーンするコードが含まれています。これにより、DistributedApplication インスタンスが返され、Run()が呼び出されます。

アプリ ホスト プロジェクト

アプリ ホスト プロジェクトは、.NET.NET Aspire プロジェクトの一部であるすべてのプロジェクトの実行を処理します。 つまり、アプリ モデル内のすべてのアプリを調整する必要があります。 プロジェクト自体は、.NET📦を参照するAspire NuGetパッケージを含む、実行可能プロジェクトであり、.NET.NET Aspire SDKを使用します。

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

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

    <ItemGroup>
        <PackageReference Include="Aspire.Hosting.AppHost" Version="9.1.0" />
    </ItemGroup>

    <!-- Omitted for brevity -->

</Project>

次のコードでは、2 つのプロジェクト参照と Program キャッシュを持つアプリ ホスト Redis について説明します。

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

上記のコード:

• CreateBuilder メソッドを使用して、新しいアプリ モデル ビルダーを作成します。
• Redis メソッドを使用して、"cache" という名前の cacheAddRedis リソースを追加します。
• AddProject メソッドを使用して、"apiservice" という名前のプロジェクト リソースを追加します。
• AddProject メソッドを使用して、"webfrontend" という名前のプロジェクト リソースを追加します。
  • WithExternalHttpEndpoints メソッドを使用して、プロジェクトに外部 HTTP エンドポイントがあることを指定します。
  • cache リソースへの参照を追加し、WithReference メソッドと WaitFor メソッドを使用して準備が整うのを待ちます。
  • apiservice リソースへの参照を追加し、WithReference メソッドと WaitFor メソッドを使用して準備が整うのを待ちます。
• Build メソッドと Run メソッドを使用して、アプリ モデルをビルドして実行します。

このコード例では、.NET AspireRedis ホスティング統合を使用します。

アプリ ホスト プロジェクトと説明されているリソースの関係を視覚化するには、次の図を検討してください。

各リソースには一意の名前を付ける必要があります。 この図は、各リソースとその間の関係を示しています。 コンテナー リソースの名前は "cache" で、プロジェクト リソースの名前は "apiservice" と "webfrontend" です。 Web フロントエンド プロジェクトは、キャッシュ および API サービス プロジェクトを参照します。 この方法で参照を表現する場合、Web フロントエンド プロジェクトでは、それぞれ "cache" と "apiservice" という 2 つのリソースに依存していると言われます。

組み込みのリソースの種類

.NET .NET Aspire プロジェクトは、一連のリソースで構成されます。 📦 Aspireの主要な基本リソースのタイプについて、.Hosting.AppHost NuGet パッケージが次の表で説明します。

プロジェクト リソースは、アプリ モデルの一部である .NET プロジェクトを表します。 アプリ ホスト プロジェクトにプロジェクト参照を追加すると、.NET.NET Aspire SDK によって、参照される各プロジェクトの Projects 名前空間に型が生成されます。 詳細については、「.NET.NET Aspire SDK: プロジェクト参照」を参照してください。

アプリ モデルにプロジェクトを追加するには、AddProject メソッドを使用します。

var builder = DistributedApplication.CreateBuilder(args);

// Adds the project "apiservice" of type "Projects.AspireApp_ApiService".
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

同じプロジェクトの複数のインスタンスをアプリ モデルに追加することで、プロジェクトをレプリケートおよびスケールアウトできます。 レプリカを構成するには、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);

上記のコードは、"apiservice" プロジェクト リソースの 3 つのレプリカをアプリ モデルに追加します。 詳細については、「.NET.NET Aspire ダッシュボード: リソース レプリカ」を参照してください。

参照リソース

参照は、リソース間の依存関係を表します。 たとえば、Web フロントエンドが Redis キャッシュに依存するシナリオを想像できます。 C# コード Program アプリ ホストの例を次に示します。

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithReference(cache);

"webfrontend" プロジェクト リソースは、WithReference を使用して、"キャッシュ" コンテナー リソースへの依存関係を追加します。 これらの依存関係は、接続文字列またはサービス検出情報を示すことができます。 前の例では、環境変数を "webfrontend" リソースに 。 この環境変数には、webfrontend(Redisなど) を介して .NET Aspire に接続するために Redis が使用する接続文字列が含まれています。

接続文字列とエンドポイント参照

プロジェクト リソース間の依存関係を表すのが一般的です。 次のコード例を考えてみます。

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

プロジェクト間参照は、適切に定義された接続文字列を持つリソースとは異なる方法で処理されます。 接続文字列が "webfrontend" リソースに挿入される代わりに、サービス検出をサポートする環境変数が挿入されます。

"apiservice" プロジェクトへの参照を追加すると、サービス検出環境変数がフロントエンドに追加されます。 これは、通常、プロジェクト間通信が HTTP/gRPC 経由で行われるためです。 詳細については、サービス検出の .NET.NET Aspireを参照してください。

ContainerResource または ExecutableResourceから特定のエンドポイントを取得するには、次のいずれかのエンドポイント API を使用します。

• WithEndpoint
• WithHttpEndpoint
• WithHttpsEndpoint

次に、GetEndpoint API を呼び出して、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);

port パラメーターは、コンテナーがリッスンしているポートです。 コンテナー ポートの詳細については、「コンテナー ポート」を参照してください。 サービス検出の詳細については、.NET.NET Aspire サービス検出を参照してください。

サービス エンドポイント環境変数の形式

前のセクションでは、WithReference メソッドを使用してリソース間の依存関係を表します。 サービス エンドポイントによって環境変数が依存リソースに挿入される場合、形式が明確でない可能性があります。 このセクションでは、この形式について詳しく説明します。

あるリソースが別のリソースに依存している場合、アプリ ホストは依存リソースに環境変数を挿入します。 これらの環境変数は、依存するリソースに接続するように依存リソースを構成します。 環境変数の形式は .NET.NET Aspire に固有であり、Service Discoveryと互換性のある方法でサービス エンドポイントを表します。

サービス エンドポイント環境変数の前には、services__ (二重アンダースコア)、サービス名、エンドポイント名、最後にインデックスが付きます。 インデックスでは、1 つのサービスに対して複数のエンドポイントがサポートされます。最初のエンドポイントの 0 から始まり、エンドポイントごとにインクリメントされます。

次の環境変数の例を考えてみましょう。

services__apiservice__http__0

上記の環境変数は、apiservice サービスの最初の HTTP エンドポイントを表します。 環境変数の値は、サービス エンドポイントの URL です。 名前付きエンドポイントは、次のように表される場合があります。

services__apiservice__myendpoint__0

前の例では、apiservice サービスには myendpointという名前付きエンドポイントがあります。 環境変数の値は、サービス エンドポイントの URL です。

既存のリソースを参照する

状況によっては、既存のリソース (おそらくクラウド プロバイダーにデプロイされているリソース) を参照することが保証される場合があります。 たとえば、Azure データベースを参照できます。 この場合は、実行コンテキスト に依存して、アプリ ホストが "実行" モードで実行されているか、"発行" モードで実行されているかを動的に判断します。 ローカルで実行していて、クラウド リソースに依存する場合は、IsRunMode プロパティを使用して条件付きで参照を追加できます。 代わりに、発行モードでリソースを作成することもできます。 一部の ホスティング統合、接続文字列を直接提供することがサポートされており、これを使用して既存のリソースを参照できます。

同様に、.NET.NET Aspire を既存のソリューションに統合するユース ケースが存在する場合もあります。 一般的な方法の 1 つは、.NET.NET Aspire アプリ ホスト プロジェクトを既存のソリューションに追加することです。 アプリ ホスト内で依存関係を表現するには、プロジェクト参照をアプリ ホストに追加し、アプリ モデルを構築 します。 たとえば、あるプロジェクトが別のプロジェクトに依存している場合があります。 これらの依存関係は、WithReference メソッドを使用して表されます。 詳細については、「.NET Aspireに .NET を追加する」を参照してください。

実行コンテキスト

IDistributedApplicationBuilder は、アプリ ホストの現在の実行に関する情報を提供する実行コンテキスト (DistributedApplicationExecutionContext) を公開します。 このコンテキストを使用して、アプリ ホストが "実行" モードとして実行されているか、発行操作の一部として実行されているかを評価できます。 次のプロパティについて考えてみましょう。

• IsRunMode: 現在の操作が実行されている場合に true を返します。
• IsPublishMode: 現在の操作が発行である場合、true を返します。

この情報は、現在の操作に基づいてコードを条件付きで実行する場合に役立ちます。 IsRunMode プロパティの使用例を次に示します。 この場合、拡張メソッドを使用して、ローカル開発実行の RabbitMQ の安定したノード名を生成します。

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

実行コンテキストは、多くの場合、既存のリソースを指すリソースまたは接続文字列を条件付きで追加するために使用されます。 実行コンテキストに基づいて Redis または接続文字列を条件付きで追加する例を次に示します。

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

前のコードでは、次のようになります。

• アプリ ホストが "実行" モードの場合は、 Redis コンテナー リソースが追加されます。
• アプリ ホストが "発行" モードの場合は、接続文字列が追加されます。

このロジックを簡単に反転して、ローカルで実行しているときに既存の Redis リソースに接続し、発行時に新しい Redis リソースを作成できます。

参照

• でリソースを調整する .NET.NET Aspire
• .NET .NET Aspire 統合の概要
• .NET .NET Aspire SDK
• .NET .NET Aspire におけるイベント
• でのサービス発見
• .NET .NET Aspire 既定のサービス
• 外部パラメーターを表す
• .NET .NET Aspire 内部ループ ネットワークの概要