.NET Aspire Cosmos DB Entity Framework Core 整合

發行項
01/09/2025

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

寄存整合

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

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

若要存取這些型別和 API 以表示它們，請在 📦 專案中新增 AspireAzure.Hosting..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 Aspire Microsoft Entity Framework CoreCosmos DB 整合，請在使用 Microsoft Entity Framework CoreCosmos DB 客戶端的應用程式專案中，安裝 📦AspireMicrosoft.EntityFrameworkCore.Cosmos 的 NuGet 套件。

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

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

新增 Cosmos DB 內容

在客戶用專案的 Program.cs 檔案中，呼叫 AddCosmosDbContext 擴充方法來註冊 System.Data.Entity.DbContext，以便透過依賴注入容器使用。方法會採用連接名稱參數。

builder.AddCosmosDbContext<MyDbContext>("cosmosdb");

提示

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

接著，您可以使用依賴注入來擷取 DbContext 實例。例如，若要從服務中取得客戶端：

public class ExampleService(MyDbContext context)
{
    // Use context...
}

如需有關搭配的詳細資訊，請參閱適用於的 NoSQL SDK 的中的範例。

配置

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

使用連接字串

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

builder.AddCosmosDbContext<MyDbContext>("CosmosConnection");

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

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

如需詳細資訊，請參閱 ConnectionString 檔。

使用組態提供者

.NET Aspire Microsoft Entity Framework CoreCosmos DB 整合支援 Microsoft.Extensions.Configuration。它會從組態檔載入 EntityFrameworkCoreCosmosSettings，例如 appsettings.json。設定某些選項的範例 _appsettings.json：

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "Cosmos": {
          "DisableTracing": true
        }
      }
    }
  }
}

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

使用行內委派

您也可以傳遞 Action<EntityFrameworkCoreCosmosSettings> configureSettings 委派，以直接在行內設定部分或全部的 EntityFrameworkCoreCosmosSettings 選項，例如從代碼停用追蹤：

builder.AddCosmosDbContext<MyDbContext>(
    "cosmosdb",
    settings => settings.DisableTracing = true);

Client 整合健康檢查

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

.NET Aspire Microsoft Entity Framework CoreCosmos DB 整合目前不會實作健康情況檢查，不過未來版本可能會變更。

可檢視性和遙測

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

伐木

.NET Aspire Microsoft Entity Framework CoreCosmos DB 整合中使用下列記錄類別：

Azure-Cosmos-Operation-Request-Diagnostics
Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Query

追蹤

.NET Aspire Microsoft Entity Framework CoreCosmos DB 整合會使用 OpenTelemetry發出下列追蹤活動：

Azure.Cosmos.Operation
OpenTelemetry.Instrumentation.EntityFrameworkCore

指標

.NET Aspire Microsoft Entity Framework CoreCosmos DB 整合目前支援下列指標：

Microsoft.EntityFrameworkCore
- ec_Microsoft_EntityFrameworkCore_active_db_contexts
- ec_Microsoft_EntityFrameworkCore_total_queries
- ec_Microsoft_EntityFrameworkCore_queries_per_second
- ec_Microsoft_EntityFrameworkCore_total_save_changes
- ec_Microsoft_EntityFrameworkCore_save_changes_per_second
- ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
- ec_Microsoft_Entity_total_execution_strategy_operation_failures
- ec_Microsoft_E_execution_strategy_operation_failures_per_second
- ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
- ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

共用方式為