интеграция .NET AspireAzure Cosmos DB

Статья
02/26/2025

Включает: интеграция с хостингом и Client интеграция

Azure Cosmos DB — это полностью управляемая служба базы данных NoSQL для современной разработки приложений. Интеграция .NET AspireAzure Cosmos DB позволяет подключаться к существующим экземплярам Cosmos DB или создавать новые экземпляры из .NET с помощью эмулятора Azure Cosmos DB.

Интеграция хостинга

Интеграция хостинга .NET.NET AspireAzure Cosmos DB моделирует различные ресурсы Cosmos DB как следующие типы:

AzureCosmosDBResource: представляет ресурс AzureAzure Cosmos DB.
AzureCosmosDBEmulatorResource: представляет ресурс эмулятора AzureAzure Cosmos DB.

Чтобы получить доступ к этим типам и API для их выражения, добавьте пакет NuGet 📦Aspire.Хостинг.Azure.CosmosDB в проект хоста приложения .

.NET интерфейс командной строки
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, будут перезаписаны, поэтому внесите изменения через API C# для управления, чтобы убедиться, что они отражаются в генерируемых файлах.

Настройка инфраструктуры подготовки

Все .NET AspireAzure ресурсы — это подклассы типа AzureProvisioningResource. Этот тип позволяет настроить созданный Bicep, предоставляя удобный API для конфигурации ресурсов Azure с помощью API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Например, можно настроить 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");
    });

Предыдущий код:

Цепочка вызова к API ConfigureInfrastructure:
- Параметр 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". API GetConnectionString является сокращением для 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> в API RunAsEmulator.

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, вызовите метод WithDataVolume в ресурсе эмулятора AzureAzure 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: Volumes.

Настройка количества секций контейнеров эмулятора 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.

Эмулятор предварительной версии также поддерживает предоставление конечной точки Data Explorer, которая позволяет просматривать данные, хранящиеся в эмуляторе 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 запущен и к нему можно подключиться.

Интеграция хостинга зависит от пакета NuGet 📦 AspNetCore.HealthChecks.CosmosDb.

интеграция Client

Чтобы приступить к интеграции с клиентом .NET AspireAzure Cosmos DB, установите пакет NuGet 📦Aspire.Microsoft.Azure.Cosmos в проект, который использует клиент, то есть в проект приложения, использующего клиент Cosmos DB. Интеграция Cosmos DB клиента регистрирует экземпляр CosmosClient, который можно использовать для взаимодействия с Cosmos DB.

.NET интерфейс командной строки
PackageReference

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 внедрение зависимостей: ключевые службы.

Конфигурация

Интеграция .NET AspireAzure 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 AspireAzure 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. Например, чтобы задать суффикс заголовка User-Agent CosmosClientOptions.ApplicationName для всех запросов, исходящих от этого клиента:

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => clientOptions.ApplicationName = "myapp");

Client проверки состояния интеграции

В настоящее время интеграция клиентской системы .NET AspireCosmos DB не реализует мониторинг работоспособности, хотя это может измениться в будущих релизах.

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают конфигурации ведения журналов, трассировки и измерений, которые иногда называются столпами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция .NET AspireAzure 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 AspireAzure Cosmos DB будет генерировать следующие активности трассировки с помощью OpenTelemetry:

Azure.Cosmos.Operation

Azure Azure Cosmos DB трассировка в настоящее время находится в предварительной версии, поэтому необходимо включить экспериментальную функцию, чтобы гарантировать регистрацию трассировок.

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

Дополнительные сведения см. в разделе о наблюдаемости пакета SDK AzureAzure Cosmos DB: атрибуты трассировки.

Метрика

Интеграция .NET AspireAzure Cosmos DB в настоящее время не поддерживает метрики по умолчанию из-за ограничений пакета SDK Azure.

См. также

Azure Cosmos DB
.NET Aspire Cosmos DB Entity Framework Core интеграция
Обзор интеграции
Обзор интеграции
.NET Aspire GitHub репозиторий

Поделиться через