Интеграция .NET AspireCosmos DBEntity Framework Core

2025-06-18

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

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

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

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

AzureCosmosDBResource: представляет ресурс AzureAzure Cosmos DB.
AzureCosmosDBContainerResource: представляет AzureAzure Cosmos DB ресурс контейнера.
AzureCosmosDBDatabaseResource: представляет собой ресурс базы данных AzureAzure Cosmos DB.
AzureCosmosDBEmulatorResource: представляет ресурс эмулятора AzureAzure Cosmos DB.

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

.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 будут перезаписаны, поэтому вносите изменения через 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, к которой требуется подключиться. Вы можете создать цепочку вызовов, чтобы указать, что AzureCosmosDBResource является существующим ресурсом:

var builder = DistributedApplication.CreateBuilder(args);

var existingCosmosName = builder.AddParameter("existingCosmosName");
var existingCosmosResourceGroup = builder.AddParameter("existingCosmosResourceGroup");

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .AsExisting(existingCosmosName, existingCosmosResourceGroup);

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(cosmos);

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

Дополнительные сведения о том, как использовать AzureAzure Cosmos DB существующие ресурсы, см. в разделе "Использование существующих Azure ресурсов".

Заметка

Кроме того, вместо представления ресурса AzureAzure Cosmos DB можно добавить строку подключения к узлу приложения. Этот подход слабо типизированный и не работает с назначениями ролей или настройками инфраструктуры. Дополнительные сведения см. в статье Добавление существующих ресурсов Azure со строками подключения.

Добавьте ресурсы базы данных и контейнеров 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 вместе с базой данных и контейнером.

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();

Предыдущий AzureAzure Cosmos DB код добавляет ресурс с именем cosmos, содержащий две базы данных: customers и orders. База customers данных имеет один контейнер с именем profiles, в то время как orders база данных имеет два контейнера: details и history. Ключ раздела для каждого контейнера — /id.

На следующей схеме показано отношение родитель-ребенок между ресурсами AzureAzure Cosmos DB.

Когда код узла вашего приложения выражает отношения родитель-потомок, клиент может глубоко ссылаться на эти ресурсы по имени. Например, в клиентском проекте можно упоминать customers базу данных по имени, при этом регистрируя экземпляр Database, который подключается к базе данных customers. То же самое относится к именованным контейнерам. Например, контейнер details может быть упомянут по имени в клиентском проекте, при этом регистрируется экземпляр Container, который подключается к контейнеру details.

Добавьте ресурс эмулятора 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. Дополнительные сведения о томах данных и о том, почему они предпочтительнее монтирований с привязкой, см. в документации: Тома.

Настройка количества секций контейнеров эмулятора 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 Aspire МайкрософтEntity Framework CoreCosmos DB, установите файл📦Aspire . Пакет NuGet Microsoft.EntityFrameworkCore.Cosmos в проекте, использующего клиент, т. е. проект для приложения, использующего клиент МайкрософтEntity Framework CoreCosmos DB.

.NET интерфейс командной строки
СсылкаНаПакет

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");

Кроме того, имя базы данных можно вывести из подключения, если в строке подключения есть одна база данных. В этом случае можно опустить параметр имени базы данных:

builder.AddCosmosDbContext<MyDbContext>("cosmosdb");

Совет

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса Cosmos DB в проект узла приложения. Другими словами, при вызове AddAzureCosmosDB и указании имени cosmosdb то же имя следует использовать при вызове AddCosmosDbContext. Дополнительные сведения см. в разделе "Добавление AzureAzure Cosmos DB ресурса".

Затем можно получить экземпляр DbContext с помощью инъекции зависимости. Например, чтобы извлечь клиента из службы.

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

Дополнительные сведения об использовании Entity Framework Core с Azure Cosmos DB, см. в разделе "Примеры для Azure Cosmos DB NoSQL SDK для .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, см. раздел JSONAspire.

Использование встроенных делегатов

Вы также можете передать делегат для настройки некоторых или всех параметров в строке, например, чтобы отключить трассировку из кода:

builder.AddCosmosDbContext<MyDbContext>(
    "cosmosdb",
    settings => settings.DisableTracing = true);

Client диагностика интеграции

Интеграция .NET Aspire Microsoft Entity Framework CoreCosmos DB в настоящее время не реализует проверки состояния системы, хотя это может измениться в будущих версиях.

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

.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