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

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

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

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

手記

Aspireのオーケストレーションは、クラウドネイティブ アプリの構成と相互接続の管理を簡素化することで、 ローカル開発 エクスペリエンスを強化するように設計されています。 開発のための非常に貴重なツールですが、Kubernetesなどの運用環境システムを置き換えることを意図したものではありません。これは、そのコンテキストで優れた機能を発揮するように特別に設計されています。

アプリ モデルを定義する

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

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

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

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

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

AppHost プロジェクト

AppHost プロジェクトは、 Aspire プロジェクトの一部であるすべてのプロジェクトの実行を処理します。 つまり、アプリ モデル内のすべてのアプリを調整する必要があります。 プロジェクト自体は、.NET SDK を使用するAspire実行可能プロジェクトです。 Aspire 13.0 以降では、Aspire.AppHost.Sdkを唯一のプロジェクト SDK として設定できます。これは、📦Aspireへのパッケージ参照を暗黙的に追加します。Hosting.AppHost NuGet パッケージ:

<Project Sdk="Aspire.AppHost.Sdk/13.0.0">
    
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net10.0</TargetFramework>
        <!-- Omitted for brevity -->
    </PropertyGroup>

    <!-- Omitted for brevity -->

</Project>

手記

SDK とパッケージ参照を明示的に一覧表示する別の方法は引き続き機能し、既存のプロジェクトを変更する必要はありません。

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

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

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

    <!-- Omitted for brevity -->

</Project>

次のコードでは、2 つのプロジェクト参照とProgram キャッシュを含む AppHost 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 メソッドを使用して、アプリ モデルをビルドして実行します。

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

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

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

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

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

方式	リソースの種類	説明
AddProject	ProjectResource	.NET プロジェクト、例えば ASP.NET Core Web アプリ。
AddCSharpApp	CSharpAppResource	C# プロジェクトまたはファイル ベースのアプリ ( *.cs ファイル、 *.csproj ファイル、プロジェクト ディレクトリなど)。
AddContainer	ContainerResource	Docker イメージなどのコンテナー イメージ。
AddExecutable	ExecutableResource	Node.js アプリなどの実行可能ファイル。
AddParameter	ParameterResource	外部パラメーターを表現するために使用できるパラメーターリソース は、。

プロジェクト リソースは、アプリ モデルの一部である .NET プロジェクトを表します。 AppHost プロジェクトにプロジェクト参照を追加すると、 Aspire SDK によって、参照される各プロジェクトの Projects 名前空間に型が生成されます。 詳細については、「 Aspire SDK: プロジェクト参照」を参照してください。 または、 AddCSharpApp メソッドを使用して、プロジェクト参照なしで C# プロジェクトまたはファイル ベースのアプリを追加することもできます。

アプリ モデルにプロジェクトを追加するには、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 つのレプリカをアプリ モデルに追加します。 詳細については、「 Aspire ダッシュボード: リソース レプリカ」を参照してください。

C# アプリ リソースは、アプリ モデルの一部である C# プロジェクトまたはファイル ベースのアプリを表します。 プロジェクト参照が必要な AddProjectとは異なり、 AddCSharpApp メソッドでは、 *.cs ファイル、 *.csproj ファイル、またはプロジェクト ディレクトリへのパスを使用して、C# プロジェクトまたはファイル ベースのアプリを追加できます。 これは、 .NET 10 で導入されたファイル ベースのアプリを追加する場合や、AppHost へのプロジェクト参照を追加せずにプロジェクトを含める場合に便利です。

C# アプリをアプリ モデルに追加するには、 AddCSharpApp メソッドを使用します。

var builder = DistributedApplication.CreateBuilder(args);

// Adds a file-based C# app "inventoryservice" from a .cs file.
var inventoryService = builder.AddCSharpApp("inventoryservice", @"..\InventoryService.cs");

// Adds a C# project "catalogservice" from a project directory.
var catalogService = builder.AddCSharpApp("catalogservice", @"..\CatalogService");

AddCSharpApp メソッドでは、レプリカ、環境変数、リソースの依存関係など、AddProjectと同じ構成オプションがサポートされています。

手記

AddCSharpAppメソッドは試験段階としてマークされており、ファイル ベースの C# アプリのサポートには .NET 10 SDK が必要です。 ファイル ベースのアプリの詳細については、Aspire 9.5 ドキュメントの新機能を参照してください。

参照リソース

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

"webfrontend" プロジェクト リソースは、WithReference を使用して、"キャッシュ" コンテナー リソースへの依存関係を追加します。 これらの依存関係は、接続文字列またはサービス検出情報を示すことができます。 前の例では、環境変数を "webfrontend" リソースに 。 この環境変数には、webfrontend(Redisなど) を介して 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" リソースに挿入される代わりに、サービス検出をサポートする環境変数が挿入されます。

方式	環境変数
WithReference(cache)	ConnectionStrings__cache="localhost:62354"
WithReference(apiservice)	APISERVICE_HTTP="http://localhost:5455" APISERVICE_HTTPS="https://localhost:7356" services__apiservice__http__0="http://localhost:5455" services__apiservice__https__0="https://localhost:7356"

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

Aspire では、サービス参照用に 2 種類の環境変数が挿入されます。

• 簡略化された形式 (例: APISERVICE_HTTP): パターン {RESOURCENAME}_{ENDPOINTNAME} を大文字で使用します。 この形式は、よりシンプルで、.NET 以外の言語やポリグロットのシナリオに適しています。
• .NET サービス検出形式 (例: services__apiservice__http__0): パターン services__{servicename}__{endpointname}__{index} を小文字で使用します。 この形式は、 .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);

方式	環境変数
WithReference(endpoint)	MYAPP_ENDPOINT="https://localhost:9043" services__myapp__endpoint__0="https://localhost:9043"

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

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

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

あるリソースが別のリソースに依存している場合、AppHost は依存リソースに環境変数を挿入します。 これらの環境変数は、依存するリソースに接続するように依存リソースを構成します。 Aspire には、さまざまなシナリオをサポートする 2 つの環境変数形式が用意されています。

簡略化された形式 (ポリグロットに対応)

簡略化された形式では、パターン {RESOURCENAME}_{ENDPOINTNAME} を大文字で使用します。 この形式は、.NET 以外の言語から使いやすく、ポリグロットのシナリオに推奨されます。

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

APISERVICE_HTTP
APISERVICE_HTTPS

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

APISERVICE_MYENDPOINT

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

手記

環境変数の名前は、オプションの接続名パラメーターではなく、リソース名に基づいています。 WithReference(resource, "customname")を使用してカスタム接続名を指定する場合でも、生成される環境変数では、カスタム名ではなくリソースの名前 (APISERVICE_HTTP など) が引き続き使用されます。

.NET サービス検出の形式

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

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

services__apiservice__http__0
services__apiservice__https__0

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

APISERVICE_MYENDPOINT

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

WithEnvironment での特定のエンドポイントの使用

特定のエンドポイントのカスタム環境変数の名前を指定するには、WithEnvironmentと組み合わせて GetEndpoint メソッドを使用します。

var projectA = builder.AddProject<Projects.ProjectA>("projecta");
var projectB = builder.AddProject<Projects.ProjectB>("projectb")
                      .WithEnvironment("PROJECTA_URL", projectA.GetEndpoint("https"));

これにより、PROJECTA_URL サービスの HTTPS エンドポイント URL を持つ 1 つの環境変数projectaが生成されます。

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

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

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

実行コンテキスト

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

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

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

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

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

重要

Aspire には、リソース ビルダーのモダリティを制御するための一般的な API が用意されています。これにより、実行モードに基づいてリソースの動作が異なります。 fluent API の先頭には、RunAs* と PublishAs*が付いています。 RunAs* API はローカル開発 (または実行モード) の動作に影響しますが、PublishAs* API はリソースの発行に影響します。 Azure リソースでこれらの API を使用する方法の詳細については、「既存の Azure リソースを使用する」を参照してください。

参照

• でリソースを調整する Aspire
• Aspire 統合の概要
• Aspire SDK
• イベントの発生 Aspire
• Aspireにおけるサービス検出
• Aspire サービスの既定値
• 外部パラメーターを表す
• Aspire inner-loop ネットワークの概要