.NET Aspire Azure Cosmos DB 集成

项目
2025-05-15

包含： - Client 集成

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

如果您正在寻找 Entity Framework Core 集成，请参阅 .NET AspireCosmos DBEntity Framework Core 集成。

托管集成

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

AzureCosmosDBResource：表示 AzureAzure Cosmos DB 资源。
AzureCosmosDBContainerResource：表示 AzureAzure Cosmos DB 容器资源。
AzureCosmosDBDatabaseResource：表示 AzureAzure Cosmos DB 数据库资源。
AzureCosmosDBEmulatorResource：表示 AzureAzure Cosmos DB 模拟器资源。

若要访问这些类型和 API 来表达它们，请在 📦 项目中添加 .AspireAzure.Hosting..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：

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

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'
  }
}

output connectionString string = cosmos.properties.documentEndpoint

output name string = cosmos.name

上述的 Bicep 模块用于预配一个帐户资源 AzureAzure Cosmos DB 。此外，在单独的模块中为 Azure 资源创建角色分配：

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

param cosmos_outputs_name string

param principalId string

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' existing = {
  name: cosmos_outputs_name
}

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
}

生成的 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 数据库和容器资源

.NET Aspire 对 Azure Cosmos DB 资源之间的父子关系进行建模。例如， AzureAzure Cosmos DB 帐户（AzureCosmosDBResource）可以有多个数据库（AzureCosmosDBDatabaseResource），每个数据库可以有多个容器（AzureCosmosDBContainerResource）。添加数据库或容器资源时，请对父资源执行此作。

若要添加 AzureAzure Cosmos DB 数据库资源，请在 AddCosmosDatabase 实例上调用 IResourceBuilder<AzureCosmosDBResource> 方法：

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var 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");
var container = db.AddContainer("entries", "/id");

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

容器是在前面添加的 AzureCosmosDBDatabaseResource 所表示的数据库中创建的。有关详细信息，请参阅AzureAzure Cosmos DB数据库、容器和项。

父子资源关系示例

若要更好地了解资源之间的 Azure Cosmos DB 父子关系，请考虑以下示例，该示例演示如何添加 Azure Cosmos DB 资源以及数据库和容器：

var builder = DistributedApplication.CreateBuilder(args);

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

var customers = cosmos.AddCosmosDatabase("customers");
var profiles = customers.AddContainer("profiles", "/id");

var orders = cosmos.AddCosmosDatabase("orders");
var details = orders.AddContainer("details", "/id");
var history = orders.AddContainer("history", "/id");

builder.AddProject<Projects.Api>("api")
       .WithReference(profiles)
       .WithReference(details)
       .WithReference(history);

builder.Build().Run();

前面的代码添加一个名为Azure的资源，其中包含两个数据库：Azure Cosmos DB 和 cosmos。数据库customers具有一个名为profiles的容器，而orders数据库有两个容器：details和history。每个容器的分区键为 /id.

下图说明了资源之间的 AzureAzure Cosmos DB 父子关系：

当应用主机代码表示父子关系时，客户端可以按名称深入链接到这些资源。例如，客户端项目可以通过名称引用 customers 数据库，并注册一个连接到 Database 数据库的 customers 实例。这同样适用于命名容器。以客户端项目为例，可以通过名称引用 details 容器，注册 Container 实例以连接到 details 容器。

添加 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 资源配置为使用模拟器在本地运行。在本例中，模拟器是模拟器。 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 是否正在运行，并确保可以成功建立与其的连接。

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

Client 集成

若要开始 .NET AspireAzure Cosmos DB 客户端集成，请在使用 📦 客户端的应用程序项目中安装 Aspire NuGet 包。 Cosmos DB 客户端集成会注册一个 CosmosClient 实例，可以用来与 Cosmos DB交互。

.NET 命令行界面
包引用

dotnet add package Aspire.Microsoft.Azure.Cosmos

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

添加 Cosmos DB 客户端

在客户端使用项目的 Program.cs 文件中，对任何 AddAzureCosmosClient 调用 IHostApplicationBuilder 扩展方法，以注册 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 依赖关系注入：密钥服务。

添加 AzureAzure Cosmos DB 数据库

在应用主机中，可以将数据库资源（AzureCosmosDBDatabaseResource）作为子资源添加到父 AzureCosmosDBResource级。在客户端消费项目中，可以按名称深层链接到数据库资源，注册用于依赖注入的 Database 实例。例如，请考虑以下代码，在AddAzureCosmosDatabase实例上调用IHostApplicationBuilder：

builder.AddAzureCosmosDatabase(connectionName: "customers");

API AddAzureCosmosDatabase 返回一个实例，该实例可用于在同一 CosmosDatabaseBuilder 数据库连接下附加多个容器。所有子容器共享相同的 CosmosClient 数据库连接和 CosmosClient 实例。当将相同的 CosmosClientOptions 关联到多个容器时，此策略非常有用。

调用 AddAzureCosmosDatabase后，可以使用依赖项注入检索 Database 实例。例如，若要从调用中的 MapGet 委托检索数据库，请考虑以下代码：

app.MapGet("/api/customers", async (Database database) =>
{
    // Query data from database...
});

添加带键的数据库AzureAzure Cosmos DB

还有一个 AddKeyedAzureCosmosDatabase API 提供了一个 CosmosDatabaseBuilder 示例，可用于在同一数据库连接下附加多个容器。方法允许使用不同的连接名称注册多个数据库。例如，请考虑以下代码，在AddKeyedAzureCosmosDatabase实例上调用IHostApplicationBuilder：

var builder = WebApplication.CreateBuilder(args);

builder.AddKeyedAzureCosmosDatabase("customers");
builder.AddKeyedAzureCosmosDatabase("orders");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("customers")] Database database) =>
{
    // Get container from database and query data
});

app.MapPost("/api/orders", async (
    [FromKeyedServices("orders")] Database database,
    [FromBody] OrderRequest order) =>
{
    // Get container from database and query data
});

app.Run();

前面的示例代码演示了如何注册两个数据库 details 和 customers。每个命名数据库都可用于获取相应的容器来查询数据。

添加 AzureAzure Cosmos DB 容器

在应用主机项目中添加 Cosmos DB 资源时，还可以添加 Azure Cosmos DB 容器资源。容器资源被视为父 AzureCosmosDBDatabaseResource级的子资源。在客户端使用的项目中，可以按名称深度链接到容器资源，并注册一个供依赖项注入使用的 Container 实例。例如，请考虑以下代码，在AddAzureCosmosContainer实例上调用IHostApplicationBuilder：

builder.AddAzureCosmosContainer(connectionName: "details");

然后，可以使用依赖项注入检索 Container 实例。例如，要在 MapGet 调用中从委托检索容器，可以考虑以下代码：

app.MapGet("/api/orders/{id:guid}", async (
    Container container, 
    [FromRoute] Guid id) =>
{
    // Query data from container...
});

添加带键 AzureAzure Cosmos DB 容器

还有一种方法 AddKeyedAzureCosmosContainer 允许使用不同的连接名称注册多个容器。例如，请考虑以下代码，在AddKeyedAzureCosmosContainer实例上调用IHostApplicationBuilder：

var builder = WebApplication.CreateBuilder(args);

builder.AddKeyedAzureCosmosContainer("customers");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("customers")] Container container) =>
{
    // Query data from container...
});

app.Run();

如果同一数据库连接下有多个容器，则可以使用 AddAzureCosmosDatabase API 在同一数据库连接下附加多个容器。所有子容器共享相同的 CosmosClient 和数据库连接。当将相同的 CosmosClientOptions 关联到多个容器时，此策略非常有用。请考虑以下备用代码，以在同一数据库连接下注册多个容器：

var builder = WebApplication.CreateBuilder(args);

builder.AddAzureCosmosDatabase("customers", configureClientOptions: options =>
    {
        options.SerializerOptions = new CosmosSerializationOptions()
        {
            PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
        };
    })
    .AddKeyedContainer(name: "profiles");

builder.AddAzureCosmosDatabase(connectionName: "orders")
       .AddKeyedContainer(name: "details")
       .AddKeyedContainer(name: "history");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("profiles")] Container container) =>
{
    // Query data from container
});

app.MapGet("/api/orders", async (
    [FromKeyedServices("details")] Container container,
    [FromKeyedServices("history")] Container container) =>
{
    // Query data from container
});

app.Run();

前面的示例代码演示如何注册两个数据库， customers 以及 orders每个数据库都有自己的容器。数据库 customers 具有一个名为 profiles的容器，而 orders 数据库具有两个命名 details 的容器和 history。可以使用其各自的密钥单独查询每个容器。

配置

.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 Aspire Cosmos DB 客户端集成当前不实现运行状况检查，但这可能会在未来版本中更改。

可观测性和遥测

.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 集成默认情况下目前不支持指标。

通过