Azure リソースをカスタマイズする

Azureを使用してAspire ソリューションのリソースをホストしている場合は、それらのリソースをきめ細かく制御できます。 既定のプロパティがニーズに合っている場合はAspireに構成を任せることができます。または、既定値をオーバーライドしてそれらの動作を調整することもできます。 コードから Azure インフラストラクチャをカスタマイズする方法 Aspire 見てみましょう。

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

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

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

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

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

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

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

• ローカル設定:

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

• Azure.Provisioning:

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

Azure.Provisioning のカスタマイズ

すべての AspireAzure ホスティング統合は、さまざまな Azure リソースを公開し、それらはすべて AzureProvisioningResource 型のサブクラスであり、それ自体は AzureBicepResourceを継承します。 これにより、この型に対して一般的に型制限された拡張機能が有効になり、Fluent API でインフラストラクチャを好みに合わせてカスタマイズできます。 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 サービスが Aspire 統合として公開されるわけではありません。 後で提供される可能性はありますが、Azure.Provisioning.* ライブラリで使用できるサービスをプロビジョニングすることもできます。 Azure Container Registry の管理を担当するワーカーサービスがあるシナリオを想像してみてください。 ここで、AppHost プロジェクトが📦Azureに依存しているとします。Provisioning.ContainerRegistry NuGet パッケージ。

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

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統合として直接公開されていない場合でも、Aspireインフラストラクチャを AppHost プロジェクトに追加する方法を示しています。 さらに、Azure Container Registry の出力を依存プロジェクトの環境に組み込む方法を示します。

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

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

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

output registryName string = acr.name

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

インフラストラクチャ リゾルバーを使用して Azure プロビジョニング オプションをカスタマイズする

プロビジョニング Azure カスタマイズするために使用できるもう 1 つの方法は、 InfrastructureResolver を作成し、その中にコードを記述して要件を実装することです。 次に、そのクラスを AppHost の構成オプションに追加します。

カスタム インフラストラクチャ リゾルバーは、 InfrastructureResolver から継承し、その仮想メンバーの 1 つ以上をオーバーライドして目的のカスタマイズを適用できるクラスです。 この例では、 ResolveProperties メソッドをオーバーライドして Cosmos DB リソースの名前を設定しますが、ニーズに応じて他のメンバーもオーバーライドできます。

internal sealed class FixedNameInfrastructureResolver : InfrastructureResolver
{
    public override void ResolveProperties(ProvisionableConstruct construct, ProvisioningBuildOptions options)
    {
        if (construct is CosmosDBAccount account)
        {
            account.Name = "ContosoCosmosDb";
        }

        base.ResolveProperties(construct, options);
    }
}

そのクラスを作成したら、AppHost で次のようなコードを使用して構成オプションに追加します。

var builder = DistributedApplication.CreateBuilder(args);

builder.Services.Configure<AzureProvisioningOptions>(options =>
{
    options.ProvisioningBuildOptions.InfrastructureResolvers.Insert(0, new FixedNameInfrastructureResolver());
});

builder.Build().Run();

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

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

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

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

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

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

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

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 ファイルへの参照を追加します。 ファイル パスは 、AppHost プロジェクトに対する相対パスである必要があります。 この参照により、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 では、テンプレートの動作をカスタマイズするために使用できるパラメーターの受け入れがサポートされています。 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 テンプレートに渡します。

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

既知のパラメーター

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

既知のパラメーターを使用するには、パラメーター名を WithParameter メソッド (WithParameter(AzureBicepResource.KnownParameters.KeyVaultName)など) に渡します。 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 テンプレートで参照します。 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 インスタンスに接続するために使用されます。

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