.NET Aspire Azure 整合概觀

發行項
12/16/2024

Azure 是建置和部署 .NET 應用程式最受歡迎的雲端平臺。 Azure SDK 這款用於 .NET 的工具，可讓您輕鬆管理和使用 Azure 服務。 .NET Aspire 提供一組與 Azure 服務的整合。本文詳細說明 .NET Aspire 中所有 Azure 整合的一些常見層面，並旨在協助您瞭解如何使用這些整合。

新增 Azure 資源

所有 .NET AspireAzure 主機整合都會公開 Azure 資源，並依照慣例透過 AddAzure* API 來新增。當您將這些資源新增至 .NET Aspire 應用程式主機時，它們代表 Azure 服務。 AddAzure* API 會傳回 IResourceBuilder<T>，其中 T 是 Azure 資源的型別。這些 IResourceBuilder<T> （builder）介面提供流暢 API，讓您在應用程式模型內設定 Azure 基礎資源。

一般開發人員體驗

當您 .NET Aspire 應用程式主機包含 Azure 資源，並在本機執行它時（一般開發人員 F5 或 dotnet run 體驗），Azure 資源會在您的 Azure 訂用帳戶中布建。這可讓您身為開發人員，在應用程式主機的本地環境中針對它們進行偵錯。

.NET .NET Aspire 的目標是預設基本或標準庫存單位（SKU）其 Azure 整合來降低成本。雖然提供這些實用的預設設定，但您可以調整 Azure 資源以符合您的需求。此外，某些整合支援模擬器或容器，這對本機開發、測試和偵錯很有用。根據預設，當您在本機執行應用程式時，Azure 資源會使用實際的 Azure 服務。不過，您可以將它們設定為使用本機模擬器或容器，避免在本機開發期間與實際 Azure 服務相關聯的成本。

本機模擬器

有些 Azure 服務可以在模擬器中本機執行。目前，.NET Aspire 支援下列 Azure 模擬器：

主機整合	描述
Azure Cosmos DB	在上呼叫，將資源設定為與 NoSQL API模擬。
Azure Event Hubs	在 `IResourceBuilder<AzureEventHubsResource>` 上呼叫 AzureEventHubsExtensions.RunAsEmulator，將事件中樞資源設定為模擬。
Azure 記憶體	在上撥打，配置儲存資源以使用 Azurite模擬。

若要讓 Azure 資源使用本機模擬器，請在 Azure 資源產生器上鏈結 RunAsEmulator 方法。此方法會將 Azure 資源設定為使用本機模擬器，而不是實際的 Azure 服務。

重要

在 Azure 資源產生器上呼叫任何可用的 RunAsEmulator API 不會影響發佈指令清單。當您發佈應用程式時，產生的 Bicep 檔案反映實際的 Azure 服務，而不是本機模擬器。

本機容器

某些 Azure 服務可以在容器中本機執行。若要在本機容器中執行 Azure 服務，請將呼叫鏈結至 Azure 資源產生器上的 RunAsContainer 方法。此方法會將 Azure 資源設定為在容器中本機執行，而不是實際的 Azure 服務。

目前，.NET Aspire 支援下列 Azure 服務作為容器：

主機整合	詳細資訊
Azure Cache for Redis	在 `IResourceBuilder<AzureRedisCacheResource>` 上呼叫 AzureRedisExtensions.RunAsContainer，根據 `docker.io/library/redis` 映像檔將其配置為在容器中本地執行。
Azure PostgreSQL 彈性 Server	在 `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，您可能會想知道呼叫 AddAzureRedis("redis").RunAsContainer() 來取得本機 docker.io/library/redis 容器與 AddRedis("redis")的方式有何異同，因為它們最終都會產生相同的本機容器。

答案是，在本機執行時沒有任何差異。當它們發佈時，您會獲得各種不同的資源：

應用程式介面	執行模式	發佈模式
AddAzureRedis("redis").RunAsContainer()	本機 Redis 容器	Azure Cache for Redis
AddRedis（“redis”）	本地 Redis 容器	Azure 容器應用程式使用 Redis 映像

SQL 和 PostgreSQL 服務也是如此：

應用程式介面	執行模式	發佈模式
AddAzurePostgresFlexibleServer("postgres").RunAsContainer()	本機 PostgreSQL 容器	Azure PostgreSQL 彈性 Server
AddPostgres（“postgres”）	本機 PostgreSQL 容器	使用 PostgreSQL 映像的 Azure 容器應用程式
AddAzureSqlServer("sql").RunAsContainer()	本地 SQL Server 容器	Azure SQL Server
AddSqlServer（“sql”）	本機 SQL Server 容器	Azure 容器應用程式，使用 SQL Server 映像

如需執行和發佈模式差異的詳細資訊，請參閱 .NET.NET Aspire 應用程式主機：執行內容。

基礎結構即程序代碼

Azure .NET SDK 提供 📦Azure。佈建 NuGet 套件和一組服務專用的 Azure 佈建套件。這些 Azure 布建連結庫可讓您輕鬆地在 .NET中以原生方式指定 Azure 基礎結構。其 API 可讓您在 C# 中撰寫面向對象的基礎結構，進而產生 Bicep。 Bicep 是一種領域專用語言（DSL），用於以宣告方式部署 Azure 資源。

雖然您可以手動布建 Azure 資源，.NET Aspire 提供一組 API 來表達 Azure 資源，藉此簡化程式。這些 API 作為 .NET AspireAzure 托管庫中的擴充方法提供，用於擴充 IDistributedApplicationBuilder 介面。當您將 Azure 資源新增至應用程式主機時，它們會隱含地新增適當的布建功能。換句話說，您不需要直接呼叫任何布建 API。

由於 .NET Aspire 在 Azure 主機整合中建模 Azure 資源，因此會使用 Azure SDK 來布建這些資源。系統會產生 Bicep 檔案來定義您所需的 Azure 資源。當您發佈應用程式時，產生的 Bicep 檔案會連同指令清單檔案一起輸出。

有數種方式可以影響產生的 Bicep 檔案：

Azure：配置客製化：
- 設定基礎結構：自定義 Azure 資源基礎結構。
- 新增 Azure 基礎結構：手動將 Azure 基礎結構新增至您的應用程式主機。
使用自訂 Bicep 範本：
- 參考 Bicep 檔案：新增磁碟上 Bicep 檔案的參考。
- 參考 Bicep 內嵌：新增內嵌 Bicep 範本。

本機布建和 `Azure.Provisioning`

為了避免將術語混淆，並協助釐清「布建」，請務必瞭解 本機布建 與 Azure 布建之間的差異：

本機布建：

根據預設，當您呼叫任何 Azure 裝載整合 API 以新增 Azure 資源時，會隱式呼叫 AddAzureProvisioning(IDistributedApplicationBuilder) API。此 API 會在相依性插入（DI）容器中註冊服務，以在應用程式主機啟動時用來布建 Azure 資源。這個概念稱為 本機佈建。如需詳細資訊，請參閱本機 Azure 佈署。
Azure.Provisioning：

Azure.Provisioning 是指 NuGet 套件，是一組程式庫，可讓您使用 C# 來產生 Bicep。 .NET Aspire 中的 Azure 主機整合會在幕後使用這些函式庫來產生 Bicep 檔案，以定義所需的 Azure 資源。如需詳細資訊，請參閱 Azure.Provisioning 自訂。

自訂 `Azure.Provisioning`

所有 .NET AspireAzure 的裝載整合都公開了各種 Azure 資源，這些資源都是 AzureProvisioningResource 類型的子類別，而 AzureProvisioningResource 類型本身繼承自 AzureBicepResource。這可讓一般類型受限於此類型的擴充功能，讓 Fluent API 能夠自定義您喜歡的基礎結構。雖然 .NET.NET Aspire 提供預設值，但您可以使用這些 API 來影響所生成的「Bicep」。

設定基礎結構

不論您正在使用的 Azure 資源為何，若要配置其基礎結構，您需要串聯呼叫 ConfigureInfrastructure 擴充方法。此方法可讓您透過傳遞一個 Action<AzureResourceInfrastructure>類型的 configure 委派，來自訂 Azure 資源的基礎結構。 AzureResourceInfrastructure 類型是 Azure.Provisioning.Infrastructure的子類別。此類型會公開大量 API 介面區，以設定 Azure 資源的基礎結構。

請考慮下列範例：

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的參數。
使用名為 storageAddAzureStorage API 新增 Azure 記憶體。
將呼叫連結至 ConfigureInfrastructure，以自訂 Azure 儲存基礎架構：
- 取得可布建的資源。
- 篩選至單一 StorageAccount。
- 將 storage-sku 參數指派給 StorageAccount.Sku 屬性：
  - StorageSku 的新實例會將其 Name 屬性指派自 AsProvisioningParameter API 的結果。

這可示範將外部參數流至 Azure 記憶體基礎結構，進而產生反映所需設定的 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。
提供 configureInfrastructure 委派函式來自訂 Azure 容器註冊表基礎結構：
- 以名稱 acr 和標準 SKU 實例化 ContainerRegistryService。
- 將 Azure Container Registry 服務新增至 infra 變數。
- 實作名稱為 registryName的 ProvisioningOutput，其類型為 string，且其值對應於 Azure 容器註冊表的名稱。
- 將輸出加入至 infra 變數。
將名為 worker 的專案新增至產生器。
將呼叫鏈結至 WithEnvironment，將專案中 ACR_REGISTRY_NAME 環境變數設定為 registryName 輸出的值。

此功能示範如何將 Azure 基礎結構新增至應用程式主機專案，即使 Azure 服務未直接公開為 .NET Aspire 整合也一樣。它進一步示範如何將 Azure 容器註冊表的輸出流至相依項目的環境。

請參考生成的 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 Container Registry 的期望組態，如 AddAzureInfrastructure API 所定義。

使用自訂 Bicep 範本

當您以 Azure 作為所需雲端提供者的目標時，您可以使用 Bicep 將基礎結構定義為程式代碼。其目標是使用更簡潔的語法大幅簡化撰寫體驗，並更好地支援模組化和重複使用程序代碼。

雖然 .NET.NET Aspire 提供一組預先建置的 Bicep 範本，但有時候您可能想要自定義範本或建立自己的範本。本節內容說明可用於自訂 Bicep 模板的相關概念與對應的 API。

重要

本節不打算教您 Bicep，而是提供如何建立自定義 Bicep 範本以搭配 .NET.NET Aspire使用的指引。

作為部署案例的一部分，（）可讓您瞭解專案，以及將它部署至的能力。 azd CLI 會使用 Bicep 樣本將應用程式部署至 Azure。

安裝 `Aspire.Hosting.Azure` 套件

當您想要參考 Bicep 檔案時，您可能未使用任何 Azure 主控整合功能。在此情況下，您仍然可以藉由安裝 Aspire.Hosting.Azure 套件來參考 Bicep 檔案。此套件提供必要的 API 以參考 Bicep 檔案並自訂 Azure 資源。

提示

如果您在使用任何 Azure 託管整合，就不需要安裝 Aspire.Hosting.Azure 套件，因為它是傳遞性相依性。

若要使用這項功能，必須安裝 📦Aspire.Hosting.Azure NuGet 套件：

.NET 命令行介面
PackageReference

dotnet add package Aspire.Hosting.Azure

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

如需詳細資訊，請參閱 dotnet add package 或管理 .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 的檔案中有 Bicep 模板，可以布建 Azure 儲存體帳戶：

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 範本，請呼叫 AddBicepTemplateString 方法並將 Bicep 範本設為 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	Log Analytics 工作區的資源識別碼。	`"logAnalyticsWorkspaceId"`
AzureBicepResource.KnownParameters.PrincipalId	目前使用者或受控識別的主體標識碼。	`"principalId"`
AzureBicepResource.KnownParameters.PrincipalName	當前使用者或受控識別的主要名稱。	`"principalName"`
AzureBicepResource.KnownParameters.PrincipalType	目前使用者或受控識別的主體類型。 `User` 或 `ServicePrincipal`。	`"principalType"`

若要使用已知的參數，請將參數名稱傳遞至 WithParameter 方法，例如 WithParameter(AzureBicepResource.KnownParameters.KeyVaultName)。您不需要傳遞已知參數的值，因為 .NET.NET Aspire 會自動為您解析這些參數。

請考慮您想要設定 Azure 事件方格 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 需要角色指派。如需詳細資訊，請參閱事件方格數據傳送者角色指派。

從 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 範本取得輸出，請在 IResourceBuilder<AzureBicepResource> 實例上呼叫 GetOutput 方法，如下列 C# 代碼段所示：

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 範本，以協助示範如何保護秘密輸出：

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 資源，並將一個名為 connectionString 的秘密隱藏至 Azure Key Vault，這個秘密代表 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 實例。

部署此資源時，基礎部署機制會自動來自 Azure Key Vault的參考秘密。為了保證秘密隔離，.NET.NET Aspire 會為每個來源建立 Key Vault。

注意

本機佈建 模式中，秘密會從 Key Vault 提取，並將其設定為環境變數。如需詳細資訊，請參閱本機 Azure 設置。

出版

當您發佈應用程式時，Azure Developer CLI 會使用 Azure 布建產生的 Bicep 來建立 Azure 訂用帳戶中的 Azure 資源。 .NET .NET Aspire 輸出發佈清單，這也是發佈過程中的重要環節。 Azure Developer CLI 是命令行工具，提供一組命令來管理 Azure 資源。

若要了解發佈和部署的詳細資訊，請參閱 Azure Developer CLI（詳細指導）以使用部署 .NET Aspire 專案到 Azure Container Apps。

共用方式為

.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` 套件