.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 类型的子类。此类型通过 Azure API 提供的 fluent API 来配置 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) 资源，从而实现对生成的 Bicep 的自定义。例如，可以配置 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 是否正在运行，并可以建立与该 Cosmos DB 的连接。

托管集成依赖于 📦 AspNetCore.HealthChecks.CosmosDb NuGet 包。

Client 集成

若要开始 .NET Aspire Microsoft Entity Framework CoreCosmos DB 集成，请在使用 Microsoft Entity Framework CoreCosmos DB 客户端的应用程序的项目中安装 📦Aspire.Microsoft.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 for 的示例。

配置

.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

通过