.NET Aspire Cosmos DB Entity Framework Core 集成

项目
03/08/2025

包括： 托管集成和 Client 集成

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 模拟器资源。

通过在 📦 项目中添加 AspireAzure.Hosting..CosmosDB NuGet 包，以访问这些类型及其用于表示的 API。

.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 脚本：

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

param principalType string

param principalId string

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'
    disableLocalAuth: true
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

resource cosmos_roleDefinition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2024-08-15' existing = {
  name: '00000000-0000-0000-0000-000000000002'
  parent: cosmos
}

resource cosmos_roleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-08-15' = {
  name: guid(principalId, cosmos_roleDefinition.id, cosmos.id)
  properties: {
    principalId: principalId
    roleDefinitionId: cosmos_roleDefinition.id
    scope: cosmos.id
  }
  parent: cosmos
}

output connectionString string = cosmos.properties.documentEndpoint

前面的 Bicep 是一个模块，它预配具有以下默认值的 AzureAzure Cosmos DB 帐户：

kind：Cosmos DB 帐户的类型。默认值为 GlobalDocumentDB。
consistencyPolicy：Cosmos DB 帐户的一致性策略。默认值为 Session。
locations：Cosmos DB 帐户的位置。默认值为资源组的位置。

除了 Cosmos DB 帐户，它还将当前应用程序添加到 Data Contributor 帐户的 Cosmos DB 角色中。生成的 Bicep 作为起点，受 C# 中资源配置基础设施更改的影响。直接对 Bicep 文件的自定义项所做的更改将被覆盖，因此请通过 C# 预配 API 进行更改，以确保它们反映在生成的文件中。

自定义预配基础结构

所有 .NET AspireAzure 资源都是 AzureProvisioningResource 类型的子类。此类型能够通过 Azure API 提供的流畅 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 数据库资源，请在 AddCosmosDatabase 实例上调用 IResourceBuilder<AzureCosmosDBResource> 方法：

var builder = DistributedApplication.CreateBuilder(args);

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

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

调用 AddCosmosDatabase时，它将名为 db 的数据库添加到 Cosmos DB 资源，并返回新创建的数据库资源。数据库是在您之前添加的由 Cosmos DB 表示的 AzureCosmosDBResource 帐户中创建的。数据库是集合和用户的逻辑容器。

存储数据的 AzureAzure Cosmos DB 容器。创建容器时，需要提供分区键。

若要添加 AzureAzure Cosmos DB 容器资源，请在 AddContainer 实例上调用 IResourceBuilder<AzureCosmosDBDatabaseResource> 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");
db.AddContainer("entries", "/id");

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

容器是在前面添加的 AzureCosmosDBDatabaseResource 所表示的数据库中创建的。

有关详细信息，请参阅AzureAzure Cosmos DB数据库、容器和项。

添加 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 的简写。

使用基于 Linux的模拟器（预览版）

下一代 AzureAzure Cosmos DB 模拟器完全基于 Linux，并可用作 Docker 容器。它支持在各种处理器和操作系统上运行。

若要使用 Cosmos DB 模拟器的预览版本，请调用 RunAsPreviewEmulator 方法。由于此功能处于预览状态，因此需要通过取消 ASPIRECOSMOSDB001 实验性诊断来显式选择预览功能。

预览模拟器还支持公开“数据资源管理器”终结点，该终结点允许通过 Web UI 查看存储在 Cosmos DB 模拟器中的数据。若要启用数据资源管理器，请调用 WithDataExplorer 方法。

#pragma warning disable ASPIRECOSMOSDB001

var builder = DistributedApplication.CreateBuilder(args);

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

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

前面的代码配置了基于 Linux 的预览版 Cosmos DB 模拟器容器，使其在运行时使用数据资源管理器端点。

托管集成运行状况检查

Azure Cosmos DB 托管集成会自动为 Cosmos DB 资源添加运行状况检查。健康检查会验证Cosmos DB是否在运行，并检查是否可以与Cosmos DB建立连接。

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

Client 集成

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

提示

connectionName 参数必须与在应用主机项目中添加 Cosmos DB 资源时使用的名称匹配。换句话说，当你调用 AddAzureCosmosDB 并提供 cosmosdb 的名称时，再次调用 AddCosmosDbContext 时应使用相同的名称。有关详细信息，请参阅添加 AzureAzure Cosmos DB 资源。

然后，可以使用依赖项注入检索 DbContext 实例。例如，若要从服务检索客户端：

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

有关将Entity Framework Core与Azure Cosmos DB一起使用的更多信息，请参阅为NoSQL SDK的Azure Cosmos DB提供的.NET示例。

配置

.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 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

通过