Aspire Azure 統合の概要

Azure は、.NET アプリケーションを構築してデプロイするための最も一般的なクラウド プラットフォーム。 用の SDK を使用すると、 サービスを簡単に管理および使用できます。 Aspire では、Azure サービスとの一連の統合が提供されます。新しいリソースを追加したり、既存のリソースに接続したりできます。 この記事では、Azure のすべての Aspire 統合の一般的な側面について詳しく説明し、それらを使用する方法を理解することを目的としています。

Azure リソースを追加する

すべての AspireAzure ホスティング統合は、Azure リソースを公開し、規則によって AddAzure* API を使用して追加されます。 これらのリソースを Aspire AppHost に追加すると、 Azure サービスを表します。 AddAzure* API は、IResourceBuilder<T> が T リソースの種類である Azure を返します。 これらの IResourceBuilder<T> (ビルダー) インターフェイスは、Azure内で基になる リソースを構成できる fluent API を提供します。 新しい Azure リソースを追加し、リソースを既存のリソースとしてマークし、さまざまな実行コンテキストでリソースがどのように動作するかを構成するための API があります。

一般的な開発者エクスペリエンス

Aspire AppHost にAzureリソースが含まれており、ローカルで実行する場合 (一般的な開発者 F5 または dotnet run エクスペリエンス)、Azure リソースはAzure サブスクリプションにプロビジョニングされます。 これにより、開発者は、AppHost のコンテキストでローカルでそれらに対してデバッグできます。

Aspireは、統合のために Basic または StandardAzure に既定で設定することで、コストを最小限に抑えるようにすることを目的としています。 これらの適切な既定値が提供されていますが、リソースをニーズに合わせてカスタマイズAzureすることができます。 さらに、一部の統合では、ローカルの開発、テスト、デバッグに役立つ エミュレーター または コンテナーがサポートされています。 既定では、アプリをローカルで実行すると、Azure リソースは実際の Azure サービスを使用します。 ただし、ローカル エミュレーターまたはコンテナーを使用するように構成できるため、ローカル開発時に実際の Azure サービスに関連するコストを回避できます。

ローカル エミュレーター

一部の Azure サービスは、ローカルで実行するためにエミュレートできます。 現在、Aspire では次の Azure エミュレーターがサポートされています。

Azure リソースでローカル エミュレーターを使用するには、RunAsEmulator リソース ビルダーで Azure メソッドの呼び出しをチェーンします。 このメソッドは、実際の Azure サービスではなくローカル エミュレーターを使用するように Azure リソースを構成します。

ローカル コンテナー

一部の Azure リソースは、オープンソースまたはオンプレミスのコンテナーを使用してローカルで置き換えることができます。 コンテナー内の Azure リソースをローカルに置き換えるために、RunAsContainer リソース ビルダーで Azure メソッドの呼び出しをチェーンします。 このメソッドは、実際の Azure サービスではなく、ローカルの開発とテストにコンテナー化されたバージョンのサービスを使用するように Azure リソースを構成します。

現在、Aspire では、コンテナーとして次の Azure サービスがサポートされています。

Azure 統合 API を理解する

Aspireの強みは、素晴らしい開発者の内部ループを提供する能力にあります。 Azure 統合も変わりありません。 これらは、すべての Azure リソース間で共有される一連の一般的な API とパターンを提供します。 これらの API とパターンは、一貫した方法で Azure リソースを簡単に操作できるように設計されています。

前のコンテナー セクションでは、Azure サービスをコンテナー内でローカルで実行する方法を確認しました。 Aspireに慣れている場合は、ローカル AddAzureRedis("redis").RunAsContainer() コンテナーを取得するためにdocker.io/library/redisを呼び出すと、どちらも同じローカル コンテナーになるので、AddRedis("redis")とどのように異なるのか疑問に思うかもしれません。

答えは、ローカルで実行しても違いはないということです。 ただし、公開されると、さまざまなリソースが取得されます。

SQL サービスと PostgreSQL サービスについても同様です。

実行モードと発行モードの違いの詳細については、「 Aspire AppHost: 実行コンテキスト」を参照してください。

さまざまなモードで Azure リソースを表現するための API

AppHost の一部である分散アプリケーション ビルダーは、ビルダー パターンを使用して、AddAzure*にします。 開発者はこれらのリソースを構成し、さまざまな実行コンテキストで動作を定義できます。 ホスティング統合 Azure、これらのリソースを "発行" および "実行" する方法を指定する API が提供されます。

AppHost が実行されると、 実行コンテキスト を使用して、AppHost が Run モードか Publish モードかを判断します。 これらの API の名前付け規則は、リソースの意図されたアクションを示します。

次の表は、Azure リソースを表すために使用される名前付け規則をまとめたものです。

実行モードの詳細については、「実行コンテキストの」を参照してください。

一般的な実行モード API のユース ケース

実行時に既存のリソースと動的に対話する必要がある場合は、デプロイや更新を行わずに、RunAsExisting を使用します。 デプロイ構成の一部として既存のリソースを宣言する場合は、PublishAsExisting を使用して、適切なスコープとアクセス許可が適用されていることを確認します。 最後に、両方の構成で既存のリソースを宣言するときに AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) を使用し、参照をパラメーター化する必要があります。

リソースが既存のリソースとしてマークされているかどうかを照会するには、IsExisting(IResource)で IResource 拡張メソッドを呼び出します。 詳細については、「既存の Azure リソース使用する」を参照してください。

既存の Azure リソースを使用する

Aspire は、既存の Azure リソースを参照するためのサポートを提供します。 既存のリソースは、PublishAsExisting、RunAsExisting、および AsExisting API を使用してマークします。 これらの API を使用すると、開発者は既にデプロイされている Azure リソースを参照し、構成し、Bicep テンプレートを使用して適切な配置マニフェストを生成できます。

これらの API で参照されている既存のリソースは、ロールの割り当てや、Aspireのインフラストラクチャで使用できるその他のカスタマイズを使用して拡張できます。 これらの API は、Bicep テンプレートを使用してデプロイできる Azure リソースに限定されます。

実行モード用に既存の Azure リソースを構成する

RunAsExisting メソッドは、分散アプリケーションが "実行" モードで実行されている場合に使用されます。 このモードでは、参照される Azure リソースが既に存在し、実行中にリソースをプロビジョニングせずに統合されていることを前提としています。 Azure リソースを既存のリソースとしてマークするには、リソース ビルダーで RunAsExisting メソッドを呼び出します。 次の例を考えてみましょう。

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

上記のコード:

• 新しい builder インスタンスを作成します。
• ビルダーに existingServiceBusName という名前のパラメーターを追加します。
• ビルダーに Azure Service Bus という名前の messaging リソースを追加します。
• RunAsExisting リソース ビルダーで serviceBus メソッドを呼び出し、existingServiceBusName パラメーターを渡します。または、string パラメーター オーバーロードを使用することもできます。
• queue リソースに serviceBus という名前のキューを追加します。

既定では、Service Bus パラメーター参照は同じ Azure リソース グループ内にあると見なされます。 ただし、別のリソース グループ内にある場合は、リソース グループをパラメーターとして明示的に渡して、適切なリソース グループを正しく指定できます。

発行モード用に既存の Azure リソースを構成する

PublishAsExisting メソッドは、発行モード中に既に存在する Azure リソースを宣言して参照することを意図している場合に、"発行" モードで使用されます。 この API により、Bicep 内の既存のリソースにマップされるリソース定義を含むマニフェストとテンプレートの作成が容易になります。

Azure リソースを "発行" モードの既存のリソースとしてマークするには、リソース ビルダーで PublishAsExisting メソッドを呼び出します。 次の例を考えてみましょう。

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .PublishAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

上記のコード:

• 新しい builder インスタンスを作成します。
• ビルダーに existingServiceBusName という名前のパラメーターを追加します。
• ビルダーに Azure Service Bus という名前の messaging リソースを追加します。
• PublishAsExisting リソース ビルダーで serviceBus メソッドを呼び出し、existingServiceBusName パラメーターを渡します。または、string パラメーター オーバーロードを使用することもできます。
• queue リソースに serviceBus という名前のキューを追加します。

AppHost が発行モードで実行されると、生成されたマニフェスト ファイルに existingResourceName パラメーターが含まれ、これを使用して既存の Azure リソースを参照できます。 マニフェスト ファイルの次の生成された部分スニペットについて考えてみましょう。

"messaging": {
  "type": "azure.bicep.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}",
  "path": "messaging.module.bicep",
  "params": {
    "existingServiceBusName": "{existingServiceBusName.value}",
    "principalType": "",
    "principalId": ""
  }
},
"queue": {
  "type": "value.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}"
}

マニフェスト ファイルの詳細については、配置ツール ビルダーのマニフェスト形式Aspire参照してください。

さらに、生成された Bicep テンプレートには、既存の existingResourceName リソースを参照するために使用できる Azure パラメーターが含まれています。 次の生成された Bicep テンプレートについて考えてみましょう。

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

param existingServiceBusName string

param principalType string

param principalId string

resource messaging 'Microsoft.ServiceBus/namespaces@2024-01-01' existing = {
  name: existingServiceBusName
}

resource messaging_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(messaging.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: messaging
}

resource queue 'Microsoft.ServiceBus/namespaces/queues@2024-01-01' = {
  name: 'queue'
  parent: messaging
}

output serviceBusEndpoint string = messaging.properties.serviceBusEndpoint

生成された Bicep テンプレートの詳細については、「Azure リソースのカスタマイズ」を参照し、他の発行 API を検討してください。

すべてのモードで既存の Azure リソースを構成する

AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) メソッドは、分散アプリケーションが "実行" モードまたは "発行" モードで実行されている場合に使用されます。 AsExisting メソッドは両方のシナリオで動作するため、リソース名またはリソース グループ名へのパラメーター化された参照のみがサポートされます。 この方法は、テスト環境と運用環境の両方で同じリソースを使用できないようにするのに役立ちます。

Azure リソースを既存のリソースとしてマークするには、リソース ビルダーで AsExisting メソッドを呼び出します。 次の例を考えてみましょう。

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

上記のコード:

• 新しい builder インスタンスを作成します。
• ビルダーに existingServiceBusName という名前のパラメーターを追加します。
• ビルダーに Azure Service Bus という名前の messaging リソースを追加します。
• AsExisting リソース ビルダーで serviceBus メソッドを呼び出し、existingServiceBusName パラメーターを渡します。
• queue リソースに serviceBus という名前のキューを追加します。

接続文字列を使用して既存の Azure リソースを追加する

Aspireは、 リソースを含むAzureする機能を提供します。 接続文字列の表現は、Azure アプリで使用する既存の Aspire リソースがある場合に便利です。 AddConnectionString API は、AppHost の実行コンテキストと共に使用され、アプリ モデルに接続文字列を条件付きで追加します。

次の例を考えてみましょう。発行 モードでは Azure Storage リソースを追加し、実行 モードでは既存の Azure Storage に接続文字列を追加します。

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureStorage("storage")
    : builder.AddConnectionString("storage");

builder.AddProject<Projects.Api>("api")
       .WithReference(storage);

// After adding all resources, run the app...

上記のコード:

• 新しい builder インスタンスを作成します。
• "発行" モードで Azure という名前の storage Storage リソースを追加します。
• "実行" モードの Azure という名前の既存の storage Storage に接続文字列を追加します。
• api という名前のプロジェクトをビルダーに追加します。
• api プロジェクトは、モードに関係なく、storage リソースを参照します。

使用している API プロジェクトでは、AppHost が構成した方法を知らなく、接続文字列情報が使用されます。 "発行" モードでは、コードによって新しい Azure Storage リソースが追加されます。これは、それに応じて 配置マニフェスト に反映されます。 "実行" モードの場合、接続文字列は AppHost に表示される構成値に対応します。 ターゲット リソースのすべてのロールの割り当てが構成されていることを前提としています。 つまり、接続文字列を格納するように環境変数またはユーザー シークレットを構成する可能性があります。 構成は、ConnectionStrings__storage (または ConnectionStrings:storage) 構成キーから解決されます。 これらの構成値は、アプリの実行時に表示できます。 詳細については、「リソースの詳細 」を参照してください。

最上位クラスの AsExisting API モデル化された既存のリソースとは異なり、接続文字列としてモデル化された既存のリソースは、追加のロールの割り当てやインフラストラクチャのカスタマイズでは強化できません。

Azure コンテナ アプリケーションとして発行

Aspire では、インフラストラクチャ管理を削減するサーバーレス プラットフォームである Azure Container Apps としてプリミティブ リソースを発行できます。 サポートされているリソースの種類は以下のとおりです。

• ContainerResource: 指定されたコンテナーを表します。
• ExecutableResource: 指定された実行可能プロセスを表します。
• ProjectResource: 指定した .NET プロジェクトを表します。

これらのリソースを発行するには、次の API を使用します。

• AzureContainerAppContainerExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppProjectExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)

これらの API は、 Azure Container App として公開されるようにリソースを構成し、 AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder) を暗黙的に呼び出して、必要なインフラストラクチャと Bicep ファイルを AppHost に追加します。 例として、次のコードを考えてみましょう。

var builder = DistributedApplication.CreateBuilder();

var env = builder.AddParameter("env");

var api = builder.AddProject<Projects.AspireApi>("api")
                 .PublishAsAzureContainerApp<Projects.AspireApi>((infra, app) =>
                 {
                     app.Template.Containers[0].Value!.Env.Add(new ContainerAppEnvironmentVariable
                     {
                         Name = "Hello",
                         Value = env.AsProvisioningParameter(infra)
                     });
                 });

上記のコード:

• 新しい builder インスタンスを作成します。
• ビルダーに env という名前のパラメーターを追加します。
• api という名前のプロジェクトをビルダーに追加します。
• PublishAsAzureContainerApp リソース ビルダーで api メソッドを呼び出し、Azure Container App インフラストラクチャを構成するラムダ式を渡します。ここで、infra は AzureResourceInfrastructure、app は ContainerAppです。
  • Hello パラメーターを使用して、env という名前の環境変数をコンテナー アプリに追加します。
  • AsProvisioningParameter メソッドは、env をインフラストラクチャの新しい ProvisioningParameter として扱うために使用されます。同じ名前の bicep パラメーターが既に存在する場合は、既存の bicep パラメーターを再利用します。

Azure Container App 環境を構成するには、「Azure Container Apps環境の構成」を参照してください。 リソースをAzureコンテナーアプリジョブとして発行する方法については、「コンテナーアプリジョブAzure」を参照してください。 詳細については、「ContainerApp と AsProvisioningParameter」を参照してください。

Publishing

アプリを発行すると、Azure で生成されたプロビジョニング Bicep が Azure Developer CLI によって使用され、Azure サブスクリプション内に Azure リソースが作成されます。 Aspire は 発行マニフェストを出力します。これは、発行プロセスの重要な部分でもあります。 Azure Developer CLI は、Azure リソースを管理するための一連のコマンドを提供するコマンド ライン ツールです。

発行と配置の詳細については、Azure Developer CLIを使用してAspireプロジェクトをAzure Container Appsにデプロイする（詳細ガイド）を参照してください。