.NET Aspire Azure 統合の概要

[アーティクル]
02/27/2025

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

Azure リソースを追加する

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

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

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

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

ローカルエミュレーター

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

ホスティング統合	説明
Azure Cosmos DB	上のリソースをNoSQL APIでエミュレートするように構成するために、を呼び出します。
Azure Event Hubs	AzureEventHubsExtensions.RunAsEmulator で `IResourceBuilder<AzureEventHubsResource>` を呼び出して、Event Hubs リソースをに構成し、エミュレートされるようにします。
Azure Service Bus	`IResourceBuilder<AzureServiceBusResource>` の AzureServiceBusExtensions.RunAsEmulator を呼び出して、Service Bus エミュレーターでエミュレートされた Service Bus リソースを構成します。
Azure SignalR Service	`IResourceBuilder<AzureSignalRResource>` で AzureSignalRExtensions.RunAsEmulator を呼び出し、AzureSignalR エミュレーターを使用して SignalR リソースをエミュレートするように構成します。
Azure ストレージ	でを呼び出し、Azuriteでエミュレートされるストレージリソースを構成します。

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

大事な

RunAsEmulator リソースビルダーで使用可能な Azure API を呼び出しても、発行マニフェストには影響しません。アプリを発行すると、ローカルエミュレーターではなく、実際のサービスが反映されるように、生成された Bicep ファイル Azure が調整されます。

ローカルコンテナー

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

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

ホスティング統合	細部
Azure Cache for Redis	AzureRedisExtensions.RunAsContainer の `IResourceBuilder<AzureRedisCacheResource>` を呼び出して、`docker.io/library/redis` イメージに基づいてコンテナー内でローカルに実行するように構成します。
柔軟な AzurePostgreSQLServer	AzurePostgresExtensions.RunAsContainer の `IResourceBuilder<AzurePostgresFlexibleServerResource>` を呼び出して、`docker.io/library/postgres` イメージに基づいてコンテナー内でローカルに実行するように構成します。
Azure SQL Server	AzureSqlExtensions.RunAsContainer の `IResourceBuilder<AzureSqlServerResource>` を呼び出して、`mcr.microsoft.com/mssql/server` イメージに基づいてコンテナー内でローカルに実行するように構成します。

手記

エミュレーターと同様に、RunAsContainer リソースビルダーで Azure を呼び出しても、発行マニフェストには影響しません。アプリを発行すると、生成された Bicep ファイルには、ローカルコンテナーではなく、実際の Azure サービスが反映されます。

Azure 統合 API を理解する

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

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

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

API	実行モード	発行モード
AddAzureRedis("redis"). RunAsContainer()	ローカル Redis コンテナ	Azure Cache for Redis
AddRedis("redis") をする	ローカル Redis コンテナ	Azure イメージを使用したコンテナーアプリの Redis

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

API	実行モード	発行モード
addAzurePostgresFlexibleServer("postgres") をします。RunAsContainer()	ローカル PostgreSQL コンテナ	柔軟な AzurePostgreSQLServer
addPostgres("postgres")	ローカル PostgreSQL コンテナ	Azure イメージを使用したコンテナーアプリの PostgreSQL
AddAzureSqlServer("sql").RunAsContainer()	ローカル SQL Server コンテナ	Azure SQL Server
AddSqlServer("sql")	ローカル SQL Server コンテナ	Azure イメージを使用したコンテナーアプリの SQL Server

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

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

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

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

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

操作	API	説明
公開する	`PublishAsConnectionString`	マニフェストで接続文字列参照として発行されるリソースを変更します。
公開する	`PublishAsExisting`	アプリケーションをデプロイするときに、新しいリソースを作成するのではなく、既存の Azure リソースを使用します。
走る	`RunAsContainer`	ローカルで実行するように同等のコンテナーを構成します。詳細については、ローカルコンテナーを参照してください。
走る	`RunAsEmulator`	エミュレートする Azure リソースを構成します。詳細については、「ローカルエミュレーターの」を参照してください。
走る	`RunAsExisting`	新しいリソースを作成する代わりに、アプリケーションの実行中に既存のリソースを使用します。
公開して実行	`AsExisting`	操作に関係なく、既存のリソースを使用します。

手記

すべての Azure リソースですべての API を使用できるわけではありません。たとえば、一部の Azure リソースはコンテナー化またはエミュレートできますが、他のリソースはコンテナー化またはエミュレートできません。

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

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

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

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

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

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

これらの API で参照されている既存のリソースは、ロールの割り当てや、コード機能として .NET.NET 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 という名前のパラメーターを追加します。
ビルダーに messaging という名前の Azure Service Bus リソースを追加します。
serviceBus リソースビルダーで RunAsExisting メソッドを呼び出し、existingServiceBusName パラメーターを渡します。または、string パラメーターオーバーロードを使用することもできます。
serviceBus リソースに queue という名前のキューを追加します。

既定では、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 という名前のパラメーターを追加します。
ビルダーに messaging という名前の Azure Service Bus リソースを追加します。
serviceBus リソースビルダーで PublishAsExisting メソッドを呼び出し、existingServiceBusName パラメーターを渡します。または、string パラメーターオーバーロードを使用することもできます。
serviceBus リソースに queue という名前のキューを追加します。

アプリホストが発行モードで実行されると、生成されたマニフェストファイルに 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}"
}

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

さらに、生成された Bicep テンプレートには、既存の Azure リソースを参照するために使用できる existingResourceName パラメーターが含まれています。次の生成された 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 テンプレートの詳細については、「コードとしてのインフラストラクチャ」を参照してください。

警告

認証を必要とする既存のリソースとやり取りする場合は、.NET.NET Aspire アプリケーションモデルで構成する認証戦略が、既存のリソースで許可されている認証戦略と一致していることを確認します。たとえば、マネージド ID を許可するように構成されていない既存の AzurePostgreSQL リソースに対してマネージド ID を使用することはできません。同様に、既存の AzureRedis リソースがアクセスキーを無効にした場合、アクセスキー認証を使用することはできません。

すべてのモードで既存の 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 という名前のパラメーターを追加します。
ビルダーに messaging という名前の Azure Service Bus リソースを追加します。
serviceBus リソースビルダーで AsExisting メソッドを呼び出し、existingServiceBusName パラメーターを渡します。
serviceBus リソースに queue という名前のキューを追加します。

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

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

手記

接続文字列は、データベース接続、メッセージブローカー、エンドポイント URI、その他のサービスなど、さまざまな接続情報を表すために使用されます。 .NET .NET Aspire 命名法では、"接続文字列" という用語は、あらゆる種類の接続情報を表すために使用されます。

次の例を考えてみましょう。発行モードでは 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 インスタンスを作成します。
"発行" モードで storage という名前の Azure Storage リソースを追加します。
"実行" モードの Azure という名前の既存の storage Storage に接続文字列を追加します。
api という名前のプロジェクトをビルダーに追加します。
api プロジェクトは、モードに関係なく、storage リソースを参照します。

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

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

コードとしてのインフラストラクチャ

Azure SDK for .NET は、📦Azureを提供します。また、の NuGet パッケージをプロビジョニングし、一連のサービス固有の Azure プロビジョニングパッケージをします。これらの Azure プロビジョニングライブラリを使用すると、Azureで .NET インフラストラクチャをネイティブに宣言的に指定することが容易になります。それらの API を使用すると、C# でオブジェクト指向インフラストラクチャを記述し、Bicep を作成できます。です。

Azure リソースを手動でプロビジョニングすることは可能ですが、.NET Aspire は、Azure リソースを表現するための一連の API を提供することでプロセスを簡略化します。これらの API は、.NET AspireAzure ホスティングライブラリの拡張メソッドとして使用でき、IDistributedApplicationBuilder インターフェイスを拡張します。 Azure リソースをアプリホストに追加すると、適切なプロビジョニング機能が暗黙的に追加されます。つまり、プロビジョニング API を直接呼び出す必要はありません。

.NET Aspire モデルが Azure ホスティング統合内の Azure リソースをモデル化しているため、Azure SDK を使用してこれらのリソースをプロビジョニングします。必要な Azure リソースを定義する Bicep ファイルが生成されます。アプリを発行すると、生成された Bicep ファイルがマニフェストファイルと共に出力されます。

生成された Bicep ファイルに影響を与える方法はいくつかあります。

Azure.プロビジョニングカスタマイズ:
- インフラストラクチャを構成: リソースインフラストラクチャ Azure をカスタマイズします。
- Azure インフラストラクチャを追加する: Azure インフラストラクチャをアプリホストに手動で追加します。
カスタム Bicep テンプレートを使用:
- 参照 Bicep ファイル: ディスク上の Bicep ファイルへの参照を追加します。
- リファレンス Bicep インライン: インライン Bicep テンプレートを追加してください。

ローカルプロビジョニングと `Azure.Provisioning`

用語を混同しないようにして「プロビジョニング」を明確にするために、ローカルプロビジョニング と Azure プロビジョニングの違いを理解することが重要です。

ローカルプロビジョニング:

既定では、Azure ホスティング統合 API のいずれかを呼び出して Azure リソースを追加すると、AddAzureProvisioning(IDistributedApplicationBuilder) API が暗黙的に呼び出されます。この API は、アプリホストの起動時に Azure リソースのプロビジョニングに使用される依存関係挿入 (DI) コンテナーにサービスを登録します。この概念は、ローカルプロビジョニングと呼ばれます。詳細については、「ローカル Azure プロビジョニング」を参照してください。
Azure.Provisioning:

Azure.Provisioning は NuGet パッケージを参照し、C# を使用して Bicep を生成できる一連のライブラリです。 Azure の .NET Aspire ホスティング統合では、これらのライブラリを内部で使用して、必要な Azure リソースを定義する Bicep ファイルを生成します。詳細については、Azure.Provisioning のカスタマイズをご覧ください。

`Azure.Provisioning` のカスタマイズ

すべての .NET AspireAzure ホスティング統合は、さまざまな Azure リソースを公開し、それらはすべて AzureProvisioningResource 型のサブクラスであり、それ自体は AzureBicepResourceを継承します。これにより、この型に対して一般的に型制限された拡張機能が有効になり、Fluent API でインフラストラクチャを好みに合わせてカスタマイズできます。 .NET .NET Aspire では既定値が提供されますが、これらの API を使用して生成された Bicep に自由に影響を与えます。

インフラストラクチャの構成

使用している Azure リソースに関係なく、基になるインフラストラクチャを構成するには、ConfigureInfrastructure 拡張メソッドの呼び出しをチェーンします。このメソッドを使用すると、Azure型の configure デリゲートを渡すことによって、Action<AzureResourceInfrastructure> リソースのインフラストラクチャをカスタマイズできます。 AzureResourceInfrastructure 型は、Azure.Provisioning.Infrastructureのサブクラスです。この型は、Azure リソースの基になるインフラストラクチャを構成するための大規模な API サーフェス領域を公開します。

次の例を考えてみましょう。

var sku = builder.AddParameter("storage-sku");

var storage = builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources();

        var storageAccount = resources.OfType<StorageAccount>().Single();

        storageAccount.Sku = new StorageSku
        {
            Name = sku.AsProvisioningParameter(infra)
        };
    });

上記のコード:

storage-skuという名前のパラメーターを追加します。
Azureという名前の AddAzureStorage API を使用して、storage Storage を追加します。
ConfigureInfrastructure Storage インフラストラクチャをカスタマイズするために、Azure への呼び出しをチェーンします。
- プロビジョニング可能なリソースを取得します。
- 一つの StorageAccountに絞り込みます。
- storage-sku プロパティに StorageAccount.Sku パラメーターを割り当てます。
  - StorageSku の新しいインスタンスには、Name API の結果から AsProvisioningParameter プロパティが割り当てられます。

これは、外部パラメーターを Azure Storage インフラストラクチャに流し込み、その結果、生成された Bicep ファイルに目的の構成を反映させます。

Azure インフラストラクチャを追加する

すべての Azure サービスが .NET Aspire 統合として公開されるわけではありません。後で提供される可能性はありますが、Azure.Provisioning.* ライブラリで使用できるサービスをプロビジョニングすることもできます。 Azure Container Registry の管理を担当するワーカーサービスがあるシナリオを想像してみてください。ここで、アプリホストプロジェクトが 📦Azureに依存しているとします。Provisioning.ContainerRegistry NuGet パッケージ。

AddAzureInfrastructure API を使用して、Azure Container Registry インフラストラクチャをアプリホストに追加できます。

var acr = builder.AddAzureInfrastructure("acr", infra =>
{
    var registry = new ContainerRegistryService("acr")
    {
        Sku = new()
        {
            Name = ContainerRegistrySkuName.Standard
        },
    };
    infra.Add(registry);

    var output = new ProvisioningOutput("registryName", typeof(string))
    {
        Value = registry.Name
    };
    infra.Add(output);
});

builder.AddProject<Projects.WorkerService>("worker")
       .WithEnvironment(
            "ACR_REGISTRY_NAME",
            new BicepOutputReference("registryName", acr.Resource));

上記のコード:

AddAzureInfrastructureの名前で acr を呼び出します。
configureInfrastructure Container Registry インフラストラクチャをカスタマイズするための Azure デリゲートを提供します。
- ContainerRegistryService をacr 名を付け標準 SKU を使用してインスタンス化します。
- Azure Container Registry サービスを infra 変数に追加します。
- 名前 ProvisioningOutput、registryNameの種類、および string コンテナーレジストリの名前に対応する値を使用して Azure をインスタンス化します。
- infra 変数に出力を追加します。
worker という名前のプロジェクトをビルダーに追加します。
WithEnvironment の呼び出しをチェーンして、プロジェクト内の ACR_REGISTRY_NAME 環境変数を registryName 出力の値に設定します。

この機能は、Azure サービスが Azure 統合として直接公開されていない場合でも、.NET Aspire インフラストラクチャをアプリホストプロジェクトに追加する方法を示しています。さらに、Azure Container Registry の出力を依存プロジェクトの環境に組み込む方法を示します。

結果の Bicep ファイルを考えてみましょう。

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

resource acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
  name: take('acr${uniqueString(resourceGroup().id)}', 50)
  location: location
  sku: {
    name: 'Standard'
  }
}

output registryName string = acr.name

Bicep ファイルには、Azure API で定義されている AddAzureInfrastructure コンテナーレジストリの必要な構成が反映されます。

カスタム Bicep テンプレートを使用する

目的のクラウドプロバイダーとして Azure をターゲットにしている場合は、Bicep を使用してインフラストラクチャをコードとして定義できます。これは、よりクリーンな構文を使用して作成エクスペリエンスを大幅に簡素化し、モジュール性とコードの再利用をより適切にサポートすることを目的としています。

.NET .NET Aspire には一連の事前構築済みの Bicep テンプレートが用意されていますが、テンプレートをカスタマイズしたり、独自のテンプレートを作成したりする場合があります。このセクションでは、Bicep テンプレートのカスタマイズに使用できる概念と対応する API について説明します。

大事な

このセクションでは、Bicep について説明するのではなく、.NET.NET Aspireで使用するカスタム Bicep テンプレートを作成する方法に関するガイダンスを提供します。

の展開ストーリーの一部として、 () は、プロジェクトとそれをにデプロイする機能を理解します。 azd CLI では、Bicep テンプレートを使用してアプリケーションを Azureにデプロイします。

パッケージ `Aspire.Hosting.Azure` インストールする

Bicep ファイルを参照する場合は、Azure ホスティング統合を使用していない可能性があります。この場合でも、Aspire.Hosting.Azure パッケージをインストールすることで、Bicep ファイルを参照できます。このパッケージには、Bicep ファイルを参照し、Azure リソースをカスタマイズするために必要な API が用意されています。

ヒント (if referring to a piece of advice), or チップ (if referring to gratuity).

Azure ホスティング統合のいずれかを使用している場合は、推移的な依存関係であるため、Aspire.Hosting.Azure パッケージをインストールする必要はありません。

この機能のいずれかを使用するには、📦Aspire。ホスティング。nuGet パッケージAzure インストールする必要があります。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure

<PackageReference Include="Aspire.Hosting.Azure"
                  Version="*" />

詳細については、「dotnet パッケージの追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

例から期待される内容

このセクションのすべての例では、Aspire.Hosting.Azure 名前空間を使用していることを前提としています。さらに、次の例では、IDistributedApplicationBuilder インスタンスがあることを前提としています。

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

// Examples go here...

builder.Build().Run();

既定では、Bicep 関連の API のいずれかを呼び出すと、アプリケーションの起動時に動的に AddAzureProvisioning リソースを生成するためのサポートを追加する Azure も呼び出されます。詳細については、「ローカルプロビジョニングと Azure.Provisioning」を参照してください。

Bicep ファイルを参照する

storage.bicep ストレージアカウントをプロビジョニングする Azure という名前のファイルに Bicep テンプレートがあるとします。

param location string = resourceGroup().location
param storageAccountName string = 'toylaunch${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

ディスク上の Bicep ファイルへの参照を追加するには、AddBicepTemplate メソッドを呼び出します。次の例を考えてみましょう。

builder.AddBicepTemplate(
    name: "storage",
    bicepFile: "../infra/storage.bicep");

上記のコードは、../infra/storage.bicepにある Bicep ファイルへの参照を追加します。ファイルパスは、アプリホスト プロジェクトに対する相対パスである必要があります。この参照により、AzureBicepResource 名を持つ "storage" がアプリケーションのリソースコレクションに追加され、API はリソースをさらにカスタマイズするために使用できる IResourceBuilder<AzureBicepResource> インスタンスを返します。

Bicep インライン参照

ディスクに Bicep ファイルを配置することが最も一般的なシナリオですが、Bicep テンプレートをインラインで追加することもできます。インラインテンプレートは、コードでテンプレートを定義する場合や、テンプレートを動的に生成する場合に便利です。インライン Bicep テンプレートを追加するには、Bicep テンプレートを AddBicepTemplateStringとして使用して string メソッドを呼び出します。次の例を考えてみましょう。

builder.AddBicepTemplateString(
        name: "ai",
        bicepContent: """
        @description('That name is the name of our application.')
        param cognitiveServiceName string = 'CognitiveService-${uniqueString(resourceGroup().id)}'

        @description('Location for all resources.')
        param location string = resourceGroup().location

        @allowed([
          'S0'
        ])
        param sku string = 'S0'

        resource cognitiveService 'Microsoft.CognitiveServices/accounts@2021-10-01' = {
          name: cognitiveServiceName
          location: location
          sku: {
            name: sku
          }
          kind: 'CognitiveServices'
          properties: {
            apiProperties: {
              statisticsEnabled: false
            }
          }
        }
        """
    );

この例では、Bicep テンプレートはインライン string として定義され、"ai"という名前でアプリケーションのリソースコレクションに追加されます。この例では、Azure AI リソースをプロビジョニングします。

Bicep テンプレートにパラメーターを渡す

Bicep では、テンプレートの動作をカスタマイズするために使用できるパラメーターの受け入れがサポートされています。 .NET .NET Aspireから Bicep テンプレートにパラメーターを渡すには、次の例に示すように、WithParameter メソッドの呼び出しをチェーンします。

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

builder.AddBicepTemplate("storage", "../infra/storage.bicep")
       .WithParameter("region", region)
       .WithParameter("storageName", "app-storage")
       .WithParameter("tags", ["latest","dev"]);

上記のコード:

"region" インスタンスに builder という名前のパラメーターを追加します。
../infra/storage.bicepにある Bicep ファイルへの参照を追加します。
"region" パラメーターを Bicep テンプレートに渡します。これは、標準のパラメーター解決を使用して解決されます。
"storageName" 値を使用して、パラメーターを Bicep テンプレートに渡します。
文字列の配列を使用して、"tags" パラメーターを Bicep テンプレートに渡します。

詳細については、「外部パラメーターを参照してください。

既知のパラメーター

.NET .NET Aspire は、Bicep テンプレートに渡すことができる一連の既知のパラメーターを提供します。これらのパラメーターは、アプリケーションと環境に関する情報を Bicep テンプレートに提供するために使用されます。次の既知のパラメーターを使用できます。

フィールド	説明	価値
AzureBicepResource.KnownParameters.KeyVaultName	シークレット出力の格納に使用されるキーコンテナーリソースの名前。	`"keyVaultName"`
AzureBicepResource.KnownParameters.Location	リソースの場所。これは、すべてのリソースに必要です。	`"location"`
AzureBicepResource.KnownParameters.LogAnalyticsWorkspaceId	ログ分析ワークスペースのリソース ID。	`"logAnalyticsWorkspaceId"`
AzureBicepResource.KnownParameters.PrincipalId	現在のユーザーまたはマネージド ID のプリンシパル ID。	`"principalId"`
AzureBicepResource.KnownParameters.PrincipalName	現在のユーザーまたはマネージド ID のプリンシパル名。	`"principalName"`
AzureBicepResource.KnownParameters.PrincipalType	現在のユーザーまたは管理対象 ID のプリンシパルの種類。 `User` または `ServicePrincipal`。	`"principalType"`

既知のパラメーターを使用するには、パラメーター名を WithParameter メソッド (WithParameter(AzureBicepResource.KnownParameters.KeyVaultName)など) に渡します。既知のパラメーターの値は、.NET.NET Aspire がユーザーに代わって解決するため渡す必要がありません。

Azure Event Grid Webhook を設定する例を考えてみましょう。 Bicep テンプレートは次のように定義できます。

param topicName string
param webHookEndpoint string
param principalId string
param principalType string
param location string = resourceGroup().location

// The topic name must be unique because it's represented by a DNS entry. 
// must be between 3-50 characters and contain only values a-z, A-Z, 0-9, and "-".

resource topic 'Microsoft.EventGrid/topics@2023-12-15-preview' = {
  name: toLower(take('${topicName}${uniqueString(resourceGroup().id)}', 50))
  location: location

  resource eventSubscription 'eventSubscriptions' = {
    name: 'customSub'
    properties: {
      destination: {
        endpointType: 'WebHook'
        properties: {
          endpointUrl: webHookEndpoint
        }
      }
    }
  }
}

resource EventGridRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(topic.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7'))
  scope: topic
  properties: {
    principalId: principalId
    principalType: principalType
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7')
  }
}

output endpoint string = topic.properties.endpoint

この Bicep テンプレートでは、topicName、webHookEndpoint、principalId、principalType、省略可能な locationなど、いくつかのパラメーターを定義します。これらのパラメーターを Bicep テンプレートに渡すには、次のコードスニペットを使用できます。

var webHookApi = builder.AddProject<Projects.WebHook_Api>("webhook-api");

var webHookEndpointExpression = ReferenceExpression.Create(
        $"{webHookApi.GetEndpoint("https")}/hook");

builder.AddBicepTemplate("event-grid-webhook", "../infra/event-grid-webhook.bicep")
       .WithParameter("topicName", "events")
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalId)
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalType)
       .WithParameter("webHookEndpoint", () => webHookEndpointExpression);

webHookApi プロジェクトは、builderへの参照として追加されます。
topicName パラメーターには、ハードコーディングされた名前の値が渡されます。
webHookEndpoint パラメーターは、api プロジェクト参照の「https」エンドポイントから、/hook ルートに基づいて URL に解決される式として渡されます。
principalId パラメーターと principalType パラメーターは、既知のパラメーターとして渡されます。

既知のパラメーターは規則ベースであり、WithParameter API を使用して渡されるときに、対応する値を伴うべきではありません。前の例に示すように、Bicep テンプレートに追加すると、ロールの割り当てなどの一般的な機能が、既知のパラメーターによって簡略化されます。 Event Grid Webhook が指定したエンドポイントにイベントを送信するには、ロールの割り当てが必要です。詳細については、「Event Grid Data Sender ロールの割り当て」を参照してください。

Bicep リファレンスから出力を取得する

Bicep テンプレートにパラメーターを渡すだけでなく、Bicep テンプレートから出力を取得することもできます。次の Bicep テンプレートについて考えてみましょう。これは、outputという名前の endpoint を定義しているものです。

param storageName string
param location string = resourceGroup().location

resource myStorageAccount 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: storageName
  location: location
  kind: 'StorageV2'
  sku:{
    name:'Standard_LRS'
    tier: 'Standard'
  }
  properties: {
    accessTier: 'Hot'
  }
}

output endpoint string = myStorageAccount.properties.primaryEndpoints.blob

Bicep は、endpointという名前の出力を定義します。 Bicep テンプレートから出力を取得するには、次の C# コードスニペットに示すように、GetOutput インスタンスで IResourceBuilder<AzureBicepResource> メソッドを呼び出します。

var storage = builder.AddBicepTemplate(
        name: "storage",
        bicepFile: "../infra/storage.bicep"
    );

var endpoint = storage.GetOutput("endpoint");

この例では、Bicep テンプレートからの出力が取得され、endpoint 変数に格納されます。通常、この出力は環境変数として、それに依存する別のリソースに渡します。たとえば、このエンドポイントに依存する ASP.NET Core Minimal API プロジェクトがある場合は、次のコードスニペットを使用して、出力を環境変数としてプロジェクトに渡すことができます。

var storage = builder.AddBicepTemplate(
                name: "storage",
                bicepFile: "../infra/storage.bicep"
            );

var endpoint = storage.GetOutput("endpoint");

var apiService = builder.AddProject<Projects.AspireSample_ApiService>(
        name: "apiservice"
    )
    .WithEnvironment("STORAGE_ENDPOINT", endpoint);

詳細については、Bicep 出力を参照してください。

Bicep 参照からシークレット出力を取得する

Bicep を使用するときは、シークレットの出力を回避することが重要です。出力が シークレットと見なされる場合は、ログやその他の場所で公開しないでください。そのように扱うことができます。これを実現するには、シークレットを Azure Key Vault に格納し、Bicep テンプレートで参照します。 .NET Aspireの Azure 統合は、リソースが keyVaultName パラメーターを使用してシークレットを Azure Key Vaultに格納できるようにするために、Bicep テンプレートからの出力を安全に格納するためのパターンを提供します。

シークレット出力をセキュリティで保護するこの概念を示すのに役立つ例として、次の Bicep テンプレートを考えてみましょう。

param databaseAccountName string
param keyVaultName string

param databases array = []

@description('Tags that will be applied to all resources')
param tags object = {}

param location string = resourceGroup().location

var resourceToken = uniqueString(resourceGroup().id)

resource cosmosDb 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
    name: replace('${databaseAccountName}-${resourceToken}', '-', '')
    location: location
    kind: 'GlobalDocumentDB'
    tags: tags
    properties: {
        consistencyPolicy: { defaultConsistencyLevel: 'Session' }
        locations: [
            {
                locationName: location
                failoverPriority: 0
            }
        ]
        databaseAccountOfferType: 'Standard'
    }

    resource db 'sqlDatabases@2023-04-15' = [for name in databases: {
        name: '${name}'
        location: location
        tags: tags
        properties: {
            resource: {
                id: '${name}'
            }
        }
    }]
}

var primaryMasterKey = cosmosDb.listKeys(cosmosDb.apiVersion).primaryMasterKey

resource vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
    name: keyVaultName

    resource secret 'secrets@2023-07-01' = {
        name: 'connectionString'
        properties: {
            value: 'AccountEndpoint=${cosmosDb.properties.documentEndpoint};AccountKey=${primaryMasterKey}'
        }
    }
}

上記の Bicep テンプレートでは、他のいくつかのパラメーターの中でも、keyVaultName パラメーターが必要です。次に、Azure Cosmos DB リソースを定義し、Azure Key Vault インスタンスへの完全修飾接続文字列を表す connectionString という名前の Cosmos DBにシークレットを隠します。このシークレット接続文字列の値にアクセスするには、次のコードスニペットを使用できます。

var cosmos = builder.AddBicepTemplate("cosmos", "../infra/cosmosdb.bicep")
    .WithParameter("databaseAccountName", "fallout-db")
    .WithParameter(AzureBicepResource.KnownParameters.KeyVaultName)
    .WithParameter("databases", ["vault-33", "vault-111"]);

var connectionString =
    cosmos.GetSecretOutput("connectionString");

builder.AddProject<Projects.WebHook_Api>("api")
    .WithEnvironment(
        "ConnectionStrings__cosmos",
        connectionString);

前のコードスニペットでは、cosmos Bicep テンプレートが builderへの参照として追加されています。 connectionString シークレット出力は Bicep テンプレートから取得され、変数に格納されます。その後、シークレット出力は環境変数 (ConnectionStrings__cosmos) として api プロジェクトに渡されます。この環境変数は、Cosmos DB インスタンスに接続するために使用されます。

このリソースがデプロイされると、基になるデプロイメカニズムによって、からシークレットが自動的にされて参照されます。シークレットの分離を保証するために、.NET.NET Aspire はソースごとに Key Vault を作成します。

手記

ローカルプロビジョニング モードでは、シークレットが Key Vault から抽出され、環境変数に設定されます。詳細については、「ローカル Azure プロビジョニング」を参照してください。

出版

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

詳細な発行と展開に関する情報は、「 (詳細ガイド)」を使用してにプロジェクトを展開するを参照してください。

次の方法で共有

.NET Aspire Azure 統合の概要

Azure リソースを追加する

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

ローカルエミュレーター

ローカルコンテナー

Azure 統合 API を理解する

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

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

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

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

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

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

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

コードとしてのインフラストラクチャ

ローカルプロビジョニングと `Azure.Provisioning`

`Azure.Provisioning` のカスタマイズ

インフラストラクチャの構成

Azure インフラストラクチャを追加する

カスタム Bicep テンプレートを使用する

パッケージ `Aspire.Hosting.Azure` インストールする

例から期待される内容

Bicep ファイルを参照する

Bicep インライン参照

Bicep テンプレートにパラメーターを渡す

既知のパラメーター

Bicep リファレンスから出力を取得する

Bicep 参照からシークレット出力を取得する

出版

その他のリソース

次の方法で共有

.NET Aspire Azure 統合の概要

Azure リソースを追加する

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

ローカル エミュレーター

ローカル コンテナー

Azure 統合 API を理解する

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

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

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

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

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

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

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

コードとしてのインフラストラクチャ

ローカルプロビジョニングと Azure.Provisioning

Azure.Provisioning のカスタマイズ

インフラストラクチャの構成

Azure インフラストラクチャを追加する

カスタム Bicep テンプレートを使用する

パッケージ Aspire.Hosting.Azure インストールする

例から期待される内容

Bicep ファイルを参照する

Bicep インライン参照

Bicep テンプレートにパラメーターを渡す

既知のパラメーター

Bicep リファレンスから出力を取得する

Bicep 参照からシークレット出力を取得する

出版

その他のリソース

ローカルエミュレーター

ローカルコンテナー

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

ローカルプロビジョニングと `Azure.Provisioning`

`Azure.Provisioning` のカスタマイズ

パッケージ `Aspire.Hosting.Azure` インストールする