.NET Aspire Azure 統合の概要

[アーティクル]
12/16/2024

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

Azure リソースを追加する

すべての .NET AspireAzure ホスティング統合は、Azure リソースを公開し、規則によって AddAzure* API を使用して追加されます。これらのリソースを .NET Aspire アプリホストに追加すると、Azure サービスを表します。 AddAzure* API は、T が Azure リソースの種類である IResourceBuilder<T> を返します。これらの IResourceBuilder<T> (ビルダー) インターフェイスは、アプリモデル内で基になる Azure リソースを構成できる fluent API を提供します。

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

.NET Aspire アプリホストに Azure リソースが含まれており、ローカルで実行する場合 (一般的な開発者 F5 または dotnet run エクスペリエンス)、Azure リソースは 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	`IResourceBuilder<AzureEventHubsResource>` で AzureEventHubsExtensions.RunAsEmulator を呼び出して、Event Hubs リソースをに構成し、エミュレートされるようにします。
Azure ストレージ	でを呼び出し、Azuriteでエミュレートされるストレージリソースを構成します。

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

大事な

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

ローカルコンテナー

一部の Azure サービスは、コンテナー内でローカルに実行できます。コンテナー内で Azure サービスをローカルで実行するには、Azure リソースビルダーで RunAsContainer メソッドの呼び出しをチェーンします。このメソッドは、実際の Azure サービスではなく、コンテナー内でローカルに実行するように Azure リソースを構成します。

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

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

手記

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

Azure 統合 API を理解する

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

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

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

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

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

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

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

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

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

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 を生成できる一連のライブラリです。 .NET Aspire の Azure ホスティング統合では、これらのライブラリを内部で使用して、必要な Azure リソースを定義する Bicep ファイルを生成します。詳細については、Azure.Provisioning のカスタマイズをご覧ください。

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

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

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

使用している Azure リソースに関係なく、基になるインフラストラクチャを構成するには、ConfigureInfrastructure 拡張メソッドの呼び出しをチェーンします。このメソッドを使用すると、Action<AzureResourceInfrastructure>型の configure デリゲートを渡すことによって、Azure リソースのインフラストラクチャをカスタマイズできます。 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という名前のパラメーターを追加します。
storageという名前の AddAzureStorage API を使用して、Azure Storage を追加します。
Azure Storage インフラストラクチャをカスタマイズするために、ConfigureInfrastructure への呼び出しをチェーンします。
- プロビジョニング可能なリソースを取得します。
- 一つの StorageAccountに絞り込みます。
- StorageAccount.Sku プロパティに storage-sku パラメーターを割り当てます。
  - StorageSku の新しいインスタンスには、AsProvisioningParameter API の結果から Name プロパティが割り当てられます。

これは、外部パラメーターを 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));

上記のコード:

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

この機能は、Azure サービスが .NET Aspire 統合として直接公開されていない場合でも、Azure インフラストラクチャをアプリホストプロジェクトに追加する方法を示しています。さらに、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 ファイルには、AddAzureInfrastructure API で定義されている Azure コンテナーレジストリの必要な構成が反映されます。

カスタム 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 のいずれかを呼び出すと、アプリケーションの起動時に動的に Azure リソースを生成するためのサポートを追加する AddAzureProvisioning も呼び出されます。詳細については、「ローカルプロビジョニングと Azure.Provisioning」を参照してください。

Bicep ファイルを参照する

Azure ストレージアカウントをプロビジョニングする storage.bicep という名前のファイルに 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 ファイルへの参照を追加します。ファイルパスは、アプリホスト プロジェクトに対する相対パスである必要があります。この参照により、"storage" 名を持つ AzureBicepResource がアプリケーションのリソースコレクションに追加され、API はリソースをさらにカスタマイズするために使用できる IResourceBuilder<AzureBicepResource> インスタンスを返します。

Bicep インライン参照

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

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

上記のコード:

builder インスタンスに "region" という名前のパラメーターを追加します。
../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 テンプレートについて考えてみましょう。これは、endpointという名前の output を定義しているものです。

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# コードスニペットに示すように、IResourceBuilder<AzureBicepResource> インスタンスで GetOutput メソッドを呼び出します。

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 リソースを定義し、Cosmos DB インスタンスへの完全修飾接続文字列を表す connectionString という名前の Azure Key Vaultにシークレットを隠します。このシークレット接続文字列の値にアクセスするには、次のコードスニペットを使用できます。

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.Provisioning`

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

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

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

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

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

例から期待される内容

Bicep ファイルを参照する

Bicep インライン参照

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

既知のパラメーター

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

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

出版

その他のリソース

次の方法で共有

.NET Aspire Azure 統合の概要

Azure リソースを追加する

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

ローカル エミュレーター

ローカル コンテナー

Azure 統合 API を理解する

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

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

Azure.Provisioning のカスタマイズ

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

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

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

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

例から期待される内容

Bicep ファイルを参照する

Bicep インライン参照

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

既知のパラメーター

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

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

出版

その他のリソース

ローカルエミュレーター

ローカルコンテナー

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

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

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