.NET Aspire Azure Cosmos DB 整合

發行項
01/23/2025

Azure Cosmos DB 是完全受控的 NoSQL 資料庫服務，可用於新式應用程式開發。 .NET Aspire Azure Cosmos DB 整合可讓您連線到現有的 Cosmos DB 實例，或使用 .NET 模擬器從 Azure Cosmos DB 建立新的實例。

主機託管整合

主機整合 .NET.NET AspireAzure Cosmos DB 將各種 Cosmos DB 資源模型化為下列類型：

AzureCosmosDBResource：代表 AzureAzure Cosmos DB 資源。
AzureCosmosDBEmulatorResource：代表 AzureAzure Cosmos DB 模擬器資源。

若要存取這些型別和 API 以表達它們，請在 📦 專案中新增 AspireAzure。托管。。CosmosDB NuGet 套件。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

如需詳細資訊，請參閱 dotnet add package 或管理 .NET 應用程式中的套件相依性。

新增 AzureAzure Cosmos DB 資源

在您的應用程式主專案中，呼叫 AddAzureCosmosDB 以新增並傳回 AzureAzure Cosmos DB 資源產生器。

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");

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

當您將 AzureCosmosDBResource 新增至應用程式主機時，它會公開其他有用的 API 來新增資料庫和容器。換句話說，您必須先新增 AzureCosmosDBResource，才能添加任何其他 Cosmos DB 資源。

重要

當您呼叫 AddAzureCosmosDB時，它會隱含地呼叫 AddAzureProvisioning，這可新增在應用程式啟動期間動態產生 Azure 資源的支援。應用程式必須設定適當的訂用帳戶和位置。如需詳細資訊，請參閱本機布建：配置。

產生的配置 Bicep

如果您不熟悉 Bicep，這是一種用於定義 Azure 資源的領域專用語言。使用 .NET.NET Aspire，您不需要手動撰寫 Bicep，因為布建 API 會自動為您產生 Bicep。當您發佈應用程式時，產生的 Bicep 會與清單檔案一起輸出。當您新增 AzureAzure Cosmos DB 資源時，會產生下列 Bicep：

切換 AzureAzure Cosmos DB 二頭肌。

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

param keyVaultName string

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

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' = {
  name: take('cosmos-${uniqueString(resourceGroup().id)}', 44)
  location: location
  properties: {
    locations: [
      {
        locationName: location
        failoverPriority: 0
      }
    ]
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    databaseAccountOfferType: 'Standard'
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

resource connectionString 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  name: 'connectionString'
  properties: {
    value: 'AccountEndpoint=${cosmos.properties.documentEndpoint};AccountKey=${cosmos.listKeys().primaryMasterKey}'
  }
  parent: keyVault
}

上述 Bicep 是一個模組，其會布建具有下列預設值的 AzureAzure Cosmos DB 帳戶：

kind：Cosmos DB 帳戶的類型。預設值為 GlobalDocumentDB。
consistencyPolicy：Cosmos DB 帳戶的一致性原則。預設值為 Session。
locations：Cosmos DB 帳戶的所在地。預設值為資源群組的位置。

除了 Cosmos DB 帳戶之外，也會提供 Azure Key Vault 資源。這是用來安全地儲存 Cosmos DB 帳戶的連接字串。產生的 Bicep 是起點，可自定義以符合您的特定需求。

自訂佈署基礎結構

所有 .NET AspireAzure 資源都是 AzureProvisioningResource 類型的子類別。此類型可藉由提供 Fluent API 來設定 Azure 資源，藉此自定義產生的 Bicep，方法是使用 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API。例如，您可以設定 kind、consistencyPolicy、locations等等。下列範例示範如何自訂 AzureAzure Cosmos DB 資源：

builder.AddAzureCosmosDB("cosmos-db")
    .ConfigureInfrastructure(infra =>
    {
        var cosmosDbAccount = infra.GetProvisionableResources()
                                   .OfType<CosmosDBAccount>()
                                   .Single();

        cosmosDbAccount.Kind = CosmosDBAccountKind.MongoDB;
        cosmosDbAccount.ConsistencyPolicy = new()
        {
            DefaultConsistencyLevel = DefaultConsistencyLevel.Strong,
        };
        cosmosDbAccount.Tags.Add("ExampleKey", "Example value");
    });

上述程式代碼：

串接對 ConfigureInfrastructure API 的呼叫：
- infra 參數是 AzureResourceInfrastructure 類型的實例。
- 藉由呼叫 GetProvisionableResources() 方法來擷取可布建的資源。
- 擷取單一 CosmosDBAccount。
- CosmosDBAccount.ConsistencyPolicy 被分配給 DefaultConsistencyLevel.Strong。
- 一個標記被新增至 Cosmos DB 帳戶，該標記的索引鍵為 ExampleKey，值為 Example value。

還有更多組態選項可用來自定義 AzureAzure Cosmos DB 資源。如需詳細資訊，請參閱 Azure.Provisioning.CosmosDB。如需詳細資訊，請參閱 Azure。佈建自訂。

連接到現有的 AzureAzure Cosmos DB 帳戶

您可能有想要連線的現有 AzureAzure Cosmos DB 帳戶。您可以將連接字串加入應用程式主機，而不需要表示新的 AzureAzure Cosmos DB 資源。若要將連線新增至現有的 AzureAzure Cosmos DB 帳戶，請呼叫 AddConnectionString 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddConnectionString("cosmos-db");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(cosmos);

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

附註

連接字串可用來代表各種連線資訊，包括資料庫連接、訊息代理程式、端點 URI 和其他服務。在 .NET.NET Aspire 名詞中，「連接字串」一詞用來代表任何類型的連接資訊。

連接字串是在應用程式主機的組態中設定，通常是在 [] 區段下的 [ConnectionStrings下。應用程式主機會將此連接字串作為環境變數插入所有相依資源，例如：

{
    "ConnectionStrings": {
        "cosmos-db": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
    }
}

相依資源可以藉由呼叫 GetConnectionString 方法來存取插入的連接字串，並將連接名稱傳遞為參數，在此情況下 "cosmos-db"。 GetConnectionString API 是 IConfiguration.GetSection("ConnectionStrings")[name]的簡稱。

新增 AzureAzure Cosmos DB 資料庫資源

若要新增 AzureAzure Cosmos DB 資料庫資源，請將 IResourceBuilder<AzureCosmosDBResource> 的呼叫鏈結至 AddDatabase API：

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .AddDatabase("db");

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

當您呼叫 AddDatabase時，它會將 Cosmos DB 資源設定為具有名為 db的資料庫。資料庫將被建立在您稍早新增的 Cosmos DB 所指的 AzureCosmosDBResource 帳戶中。資料庫是集合和用戶的邏輯容器。如需詳細資訊，請參閱中的資料庫、容器和專案。

附註

使用 AddDatabase API 將資料庫新增至 AzureAzure Cosmos DB 資源時，如果您正在執行模擬器，則實際上不會在模擬器中建立資料庫。此 API 旨在將資料庫包含在布建基礎結構所產生的 Bicep 中。

新增 AzureAzure Cosmos DB 模擬器資源

若要新增 AzureAzure Cosmos DB 模擬器資源，請將 IResourceBuilder<AzureCosmosDBResource> 的呼叫鏈結至 RunAsEmulator API：

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .RunAsEmulator();

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

當您呼叫 RunAsEmulator時，它會將 Cosmos DB 資源設定為使用模擬器在本機執行。在這裡情況下，模擬器是 AzureAzure Cosmos DB 模擬器。 Azure Cosmos DB 模擬器提供免費的本地環境來測試您的 Azure Cosmos DB 應用程式，是 .NET AspireAzure 託管整合的完美配套。模擬器並非安裝，而是作為一個容器供 .NET.NET Aspire 存取。當您將容器新增至應用程式主機時，如上述範例中的 mcr.microsoft.com/cosmosdb/emulator 映射所示，它會在應用程式主機啟動時建立並啟動容器。如需詳細資訊，請參閱容器資源生命週期。

設定 Cosmos DB 模擬器容器

容器資源可以使用各種組態，例如，您可以設定容器的埠、環境變數、存留期等等。

設定 Cosmos DB 模擬器容器閘道埠

根據預設，Cosmos DB設定時，.NET Aspire 模擬器容器會公開下列端點：

端點	貨櫃港口	主機埠
`https`	8081	動態

接聽的埠預設為動態。當容器啟動時，埠會對應至主計算機上的隨機埠。若要設定端點埠，請在 RunAsEmulator 方法所提供的容器資源產生器上鏈結呼叫，如下列範例所示：

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithGatewayPort(7777);
                     });

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

此程式代碼會設定 Cosmos DB 模擬器容器的現有 https 連接點，以接聽埠 8081。 Cosmos DB 模擬器容器的埠會對應至主機埠，如下表所示：

端點名稱	連接埠對應（`container:host`）
`https`	`8081:7777`

設定具有持久化生命周期的 Cosmos DB 模擬器容器

若要使用永續性存留期設定 Cosmos DB 模擬器容器，請在 WithLifetime 模擬器容器資源上呼叫 Cosmos DB 方法，並傳遞 ContainerLifetime.Persistent：

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithLifetime(ContainerLifetime.Persistent);
                     });

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

如需詳細資訊，請參閱容器資源存留期。

使用資料卷配置 Cosmos DB 模擬器容器

若要將數據磁碟區新增至 AzureAzure Cosmos DB 模擬器資源，請在 WithDataVolumeAzure 模擬器資源上呼叫 Azure Cosmos DB 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithDataVolume();
                     });

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

數據磁碟區可用來將 Cosmos DB 模擬器數據保存在其容器生命週期之外。數據磁碟區會掛接在 /tmp/cosmos/appdata 模擬器容器中的 Cosmos DB 路徑，且未提供 name 參數時，會產生名稱。模擬器已將其 AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE 環境變數設定為 true。如需關於資料量和為何偏好於綁定掛載的詳細資訊，請參閱 Docker 文件：磁碟區。

設定 Cosmos DB 模擬器容器的分割區數量

若要設定 Cosmos DB 模擬器容器的分割區計數，請呼叫 WithPartitionCount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithPartitionCount(100); // Defaults to 25
                     });

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

上述程式代碼將 Cosmos DB 模擬器容器配置為具有 100的分割區數量。這是設定 AZURE_COSMOS_EMULATOR_PARTITION_COUNT 環境變數的速記。

託管集成健全性檢查

Azure Cosmos DB 裝載整合會自動為 Cosmos DB 資源新增健康檢查。健康檢查會確認 Cosmos DB 正在執行，且可以與其建立連線。

主機整合依賴 📦 AspNetCore.HealthChecks.CosmosDb NuGet 套件。

Client 整合

若要開始使用 .NET AspireAzure Cosmos DB 用戶端整合，請在使用 Cosmos DB 客戶端的應用程式專案中安裝 📦Aspire.Microsoft.Azure.Cosmos NuGet 套件。 Cosmos DB 用戶端整合會註冊可用來與 Cosmos DB互動的 CosmosClient 實例。

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.Azure.Cosmos

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

新增 Cosmos DB 用戶端

在用戶端取用專案的 Program.cs 檔案中，在任何 IHostApplicationBuilder 上呼叫 AddAzureCosmosClient 擴充方法，以註冊 CosmosClient，以透過相依性插入容器使用。方法會採用連接名稱參數。

builder.AddAzureCosmosClient(connectionName: "cosmos-db");

提示

connectionName 參數必須符合在應用程式主專案中新增 Cosmos DB 資源時所使用的名稱。換句話說，當您呼叫 AddAzureCosmosDB 並提供名稱 cosmos-db 時，當呼叫 AddAzureCosmosClient時應該使用相同的名稱。如需詳細資訊，請參閱新增 AzureAzure Cosmos DB 資源。

接著，您可以使用依賴注入來取得 CosmosClient 實例。例如，若要從範例服務擷取連線：

public class ExampleService(CosmosClient client)
{
    // Use client...
}

如需相依性插入的詳細資訊，請參閱 .NET 相依性插入。

新增索引鍵 Cosmos DB 用戶端

在某些情況下，您可能想要以不同的連線名稱註冊多個 CosmosClient 實例。若要註冊 Cosmos DB 用戶端，請呼叫 AddKeyedAzureCosmosClient 方法：

builder.AddKeyedAzureCosmosClient(name: "mainDb");
builder.AddKeyedAzureCosmosClient(name: "loggingDb");

重要

使用索引鍵服務時，預期您的 Cosmos DB 資源已設定兩個具名資料庫，一個用於 mainDb，另一個用於 loggingDb。

然後，您可以使用相依性插入來擷取 CosmosClient 實例。例如，若要從範例服務擷取連線：

public class ExampleService(
    [FromKeyedServices("mainDb")] CosmosClient mainDbClient,
    [FromKeyedServices("loggingDb")] CosmosClient loggingDbClient)
{
    // Use clients...
}

如需索引鍵服務的詳細資訊，請參閱 .NET 依賴注入：索引鍵服務。

配置

.NET Aspire Azure Cosmos DB 整合提供多個選項，可根據專案的需求和慣例來設定連線。

使用連接字串

從 [ConnectionStrings 組態] 區段使用連接字串時，您可以在呼叫 AddAzureCosmosClient 方法時提供連接字串的名稱：

builder.AddAzureCosmosClient("cosmos-db");

然後，從 ConnectionStrings 組態區段擷取連接字串：

{
  "ConnectionStrings": {
    "cosmos-db": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
  }
}

如需如何格式化此連接字串的詳細資訊，請參閱 ConnectionString 檔。

使用組態提供者

.NET Aspire Azure Cosmos DB 整合支援 Microsoft.Extensions.Configuration。它會使用 MicrosoftAzureCosmosSettings 鍵從組態載入 Aspire:Microsoft:Azure:Cosmos。下列代碼段是 appsettings.json 檔案的範例，可設定一些選項：

{
  "Aspire": {
    "Microsoft": {
      "Azure": {
        "Cosmos": {
          "DisableTracing": false,
        }
      }
    }
  }
}

如需完整的 Cosmos DB 用戶端整合 JSON 架構，請參閱 Aspire。Microsoft。Azure。Cosmos/ConfigurationSchema.json。

使用內聯委派

您也可以傳遞 Action<MicrosoftAzureCosmosSettings> configureSettings 委派來設定部分或所有內嵌選項，例如從程式碼中停用追蹤：

builder.AddAzureCosmosClient(
    "cosmos-db",
    static settings => settings.DisableTracing = true);

您也可以使用 Microsoft.Azure.Cosmos.CosmosClientOptions 方法的選擇性 Action<CosmosClientOptions> configureClientOptions 參數來設定 AddAzureCosmosClient。例如，針對此用戶端的所有要求問題設定 CosmosClientOptions.ApplicationName 使用者代理程式標頭後綴：

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => clientOptions.ApplicationName = "myapp");

Client 整合系統健康檢查

在預設情況下，.NET.NET Aspire 整合會為所有服務啟用健康檢查。如需詳細資訊，請參閱 .NET.NET Aspire 整合概觀。

.NET Aspire Azure Cosmos DB 整合：

當 MicrosoftAzureCosmosSettings.DisableTracing 為 false時，新增健康情況檢查，這會嘗試連線到 Cosmos DB。
與 /health HTTP 端點整合，指定所有已註冊的健康檢查都必須通過，應用程式才能被視為已準備好接受流量。

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和度量組態，有時稱為 可觀察性要素。如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。視支援服務而定，某些整合可能只支援其中一些功能。例如，某些整合支援記錄和追蹤，但不支援計量。您也可以使用組態一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire Azure Cosmos DB 整合會使用下列記錄類別：

Azure-Cosmos-Operation-Request-Diagnostics

除了取得失敗要求 Azure Cosmos DB 的診斷之外，您還可以設定延遲閾值，以決定哪些成功的 Azure Cosmos DB 診斷將被記錄。點作業的預設值為 100 毫秒，非點作業的預設值為 500 毫秒。

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => {
            clientOptions.CosmosClientTelemetryOptions = new()
            {
                CosmosThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

追蹤

.NET Aspire Azure Cosmos DB 整合將會使用 OpenTelemetry產生以下追蹤活動：

Azure.Cosmos.Operation

Azure Azure Cosmos DB 追蹤目前處於預覽狀態，因此您必須將實驗性開關設成開啟，以確保發出追蹤。

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

如需詳細資訊，請參閱 AzureAzure Cosmos DB SDK 可檢視性：追蹤屬性。

指標

.NET Aspire Azure Cosmos DB 整合目前預設不支援計量，因為 Azure SDK 的限制。

共用方式為