.NET Aspire Azure Cosmos DB 集成

项目
01/09/2025

Azure Cosmos DB 是一项完全托管的 NoSQL 数据库服务，用于新式应用开发。通过 .NET AspireAzure Cosmos DB 集成，可以使用 Azure Cosmos DB 模拟器连接到现有 Cosmos DB 实例或从 .NET 创建新实例。

托管集成

托管集成 .NET.NET AspireAzure Cosmos DB 将各种 Cosmos DB 资源建模为以下类型：

AzureCosmosDBResource：表示 AzureAzure Cosmos DB 资源。
AzureCosmosDBEmulatorResource：表示 AzureAzure Cosmos DB 模拟器资源。

若要访问这些类型和 API 来表示它们，请在应用主机项目中添加 📦Aspire.Hosting.Azure.CosmosDB NuGet 包。

.NET 命令行界面
包引用

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 类型的子类。此类型允许通过使用 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API 提供的 fluent API 来配置 Azure 资源，从而自定义生成的 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的数据库。数据库是在您之前添加的由 AzureCosmosDBResource 表示的 Cosmos DB 帐户中创建的。数据库是集合和用户的逻辑容器。有关详细信息，请参阅 AzureAzure Cosmos DB中的数据库、容器和项。

注意

使用 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 模拟器容器网关端口

默认情况下，通过 .NET Aspire配置的 Cosmos DB 模拟器容器会公开以下接口：

端点	集装箱港口	主机端口
`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 模拟器容器，请在 Cosmos DB 模拟器容器资源上调用 WithLifetime 方法并传递 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 模拟器资源，请在 AzureAzure Cosmos DB 模拟器资源上调用 WithDataVolume 方法：

var builder = DistributedApplication.CreateBuilder(args);

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

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

数据卷用于在其容器生命周期之外保留 Cosmos DB 模拟器数据。数据卷装载在 Cosmos DB 模拟器容器中的 /tmp/cosmos/appdata 路径上，如果未提供 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 DBclient 集成，请在使用 Cosmos DBclient的应用程序的项目中安装 📦Aspire.Microsoft.AzureCosmos NuGet 包，即所谓的 client消耗项目。 Cosmos DB client 整合将注册一个 CosmosClient 实例，你可以用来与 Cosmos DB交互。

.NET 命令行界面
包引用

dotnet add package Aspire.Microsoft.Azure.Cosmos

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

添加 Cosmos DBclient

在 client消耗项目的 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 DBclient

在某些情况下，可能需要使用不同的连接名称注册多个 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。它使用 Aspire:Microsoft:Azure:Cosmos 键从配置加载 MicrosoftAzureCosmosSettings。以下代码片段是一个 appsettings.json 文件的示例，用于配置某些选项：

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

有关完整的 Cosmos DBclient 集成 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发出的请求设置 client 用户代理标头后缀：

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 SDK 的限制，Azure Cosmos DBAzure 集成目前目前不支持指标。

通过