integração .NET AspireCosmos DBEntity Framework Core

Artigo
01/09/2025

Inclui:integração de hospedagem e integração Client

Azure Cosmos DB é um serviço de banco de dados NoSQL totalmente gerenciado para desenvolvimento de aplicativos modernos. A integração .NET AspireCosmos DBEntity Framework Core permite que você se conecte a instâncias Cosmos DB existentes ou crie novas instâncias de .NET com o emulador Azure Cosmos DB.

Integração de hospedagem

O .NET.NET AspireAzure Cosmos DB de integração de hospedagem modela os vários recursos Cosmos DB como os seguintes tipos:

AzureCosmosDBResource: representa um recurso de AzureAzure Cosmos DB.
AzureCosmosDBEmulatorResource: representa um recurso do emulador AzureAzure Cosmos DB.

Para acessar esses tipos e APIs para expressá-los, adicione o pacote NuGet 📦Aspire.Hosting.Azure.CosmosDB no projeto de host do aplicativo .

.NET Interface de Linha de Comando
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

<PackageReference Include="Aspire.Hosting.Azure.CosmosDB"
                  Version="*" />

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em aplicativos .NET.

Adicionar AzureAzure Cosmos DB recurso

No projeto de host do aplicativo, chame AddAzureCosmosDB para adicionar e retornar um construtor de recursos AzureAzure Cosmos DB.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Quando você adiciona um AzureCosmosDBResource ao host do aplicativo, ele expõe outras APIs úteis para adicionar bancos de dados e contêineres. Em outras palavras, você deve adicionar um AzureCosmosDBResource antes de adicionar qualquer outro recurso Cosmos DB.

Importante

Quando você chama AddAzureCosmosDB, ele chama implicitamente AddAzureProvisioning— o que adiciona suporte para gerar recursos Azure dinamicamente durante a inicialização do aplicativo. O aplicativo deve configurar a assinatura e o local apropriados. Para obter mais informações, consulte Provisionamento local: Configuração.

Bicep de provisionamento gerado

Se você é novo em Bicep, é uma linguagem específica do domínio para definir Azure recursos. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente; as APIs de provisionamento geram Bicep para você. Quando você publica seu aplicativo, o Bicep gerado é exibido junto com o arquivo de manifesto. Quando você adiciona um recurso AzureAzure Cosmos DB, o seguinte Bicep é gerado:

Alternar AzureAzure Cosmos DB Bicep.

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

O Bicep anterior é um módulo que provisiona uma conta AzureAzure Cosmos DB com os seguintes padrões:

kind: o tipo de conta Cosmos DB. O padrão é GlobalDocumentDB.
consistencyPolicy: a política de consistência da conta Cosmos DB. O padrão é Session.
locations: Os locais da conta Cosmos DB. O padrão é o local do grupo de recursos.

Além da conta Cosmos DB, ela também provisiona um recurso Azure Key Vault. Isso é usado para armazenar a cadeia de conexão da conta Cosmos DB com segurança. O Bicep gerado é um ponto de partida e pode ser personalizado para atender aos seus requisitos específicos.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Esse tipo permite a customização do Bicep gerado ao fornecer uma API fluente para configurar os recursos de Azure usando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por exemplo, você pode configurar o kind, consistencyPolicy, locationse muito mais. O exemplo a seguir demonstra como personalizar o recurso de 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");
    });

O código anterior:

Encadeia uma chamada à API de ConfigureInfrastructure:
- O parâmetro infra é uma instância do tipo AzureResourceInfrastructure.
- Os recursos provisionáveis são recuperados chamando o método GetProvisionableResources().
- O único CosmosDBAccount é recuperado.
- O CosmosDBAccount.ConsistencyPolicy é atribuído a um DefaultConsistencyLevel.Strong.
- Uma etiqueta é adicionada à conta Cosmos DB com uma chave de ExampleKey e um valor de Example value.

Há muito mais opções de configuração disponíveis para personalizar o recurso AzureAzure Cosmos DB. Para obter mais informações, consulte Azure.Provisioning.CosmosDB. Para obter mais informações, consulte Azure. Provisionamento de personalização.

Conectar-se a uma conta de AzureAzure Cosmos DB existente

Você pode ter uma conta de AzureAzure Cosmos DB existente à qual deseja se conectar. Em vez de representar um novo recurso de AzureAzure Cosmos DB, você pode adicionar uma string de conexão no host do aplicativo. Para adicionar uma conexão a uma conta AzureAzure Cosmos DB existente, chame o método 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...

Nota

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Em .NET.NET Aspire nomenclatura, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

A cadeia de conexão é configurada na configuração do host do aplicativo, normalmente em Segredos do Usuário, na seção ConnectionStrings. O host do aplicativo injeta essa cadeia de conexão como uma variável de ambiente em todos os recursos dependentes, por exemplo:

{
    "ConnectionStrings": {
        "cosmos-db": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
    }
}

O recurso dependente pode acessar a cadeia de conexão injetada chamando o método GetConnectionString e passando o nome da conexão como o parâmetro, nesse caso "cosmos-db". A API de GetConnectionString é abreviada para IConfiguration.GetSection("ConnectionStrings")[name].

Adicionar AzureAzure Cosmos DB recurso de banco de dados

Para adicionar um recurso de banco de dados AzureAzure Cosmos DB, encadeia uma chamada em um IResourceBuilder<AzureCosmosDBResource> à API AddDatabase:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Quando você chama AddDatabase, ele configura seus recursos de Cosmos DB para ter um banco de dados chamado db. O banco de dados é criado na conta Cosmos DB representada pela AzureCosmosDBResource que você adicionou anteriormente. O banco de dados é um contêiner lógico para coleções e usuários. Para obter mais informações, consulte Bancos de Dados, contêineres e itens no AzureAzure Cosmos DB.

Nota

Ao usar a API AddDatabase para adicionar um banco de dados a um recurso AzureAzure Cosmos DB, se você estiver executando o emulador, o banco de dados não será realmente criado no emulador. Esta API é projetada para incluir um banco de dados no Bicep gerado pela infraestrutura de provisionamento.

Adicionar AzureAzure Cosmos DB recurso do emulador

Para adicionar um recurso do emulador AzureAzure Cosmos DB, encadeia uma chamada em um IResourceBuilder<AzureCosmosDBResource> à API RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Quando você chama RunAsEmulator, ele configura seus recursos de Cosmos DB para serem executados localmente usando um emulador. O emulador neste caso é o Emulador AzureAzure Cosmos DB. O Azure Cosmos DB Emulador fornece um ambiente local gratuito para testar seus aplicativos Azure Cosmos DB e é um complemento perfeito para a integração de hospedagem .NET AspireAzure. O emulador não está instalado, em vez disso, é acessível para .NET.NET Aspire como um contêiner. Quando você adiciona um contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem mcr.microsoft.com/cosmosdb/emulator, ele cria e inicia o contêiner quando o host do aplicativo é iniciado. Para obter mais informações, consulte ciclo de vida do recurso contêiner.

Configurar contêiner do emulador Cosmos DB

Há várias configurações disponíveis para recursos de contêiner, por exemplo, você pode configurar as portas do contêiner, variáveis de ambiente, é tempo de vidae muito mais.

Configurar a porta do gateway de emulador do contêiner Cosmos DB

O contêiner do emulador Cosmos DB, por padrão, quando configurado por .NET Aspire, expõe os seguintes endpoints:

Endpoint	Porta de contêiner	Porta do host
`https`	8081	dinâmico

A porta que está sendo utilizada para escuta é dinâmica por padrão. Quando o contêiner é iniciado, a porta é mapeada para uma porta aleatória no computador host. Para configurar a porta do ponto de extremidade, encadeia chamadas no construtor de recursos de contêiner fornecido pelo método RunAsEmulator, conforme mostrado no exemplo a seguir:

var builder = DistributedApplication.CreateBuilder(args);

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

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

O código anterior configura o ponto de extremidade existente de https do contêiner do emulador Cosmos DB para escutar na porta 8081. A porta do contêiner do emulador Cosmos DB é mapeada para a porta de host, conforme mostrado na tabela a seguir:

Nome do ponto de extremidade	Mapeamento de porta (`container:host`)
`https`	`8081:7777`

Configurar o contêiner Cosmos DB do emulador com vida útil persistente

Para configurar o contêiner do emulador Cosmos DB com um tempo de vida persistente, chame o método WithLifetime no recurso de contêiner do emulador Cosmos DB e passe 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...

Para obter mais informações, consulte tempo de vida do recurso do contêiner .

Configurar o contêiner do emulador Cosmos DB com volume de dados

Para adicionar um volume de dados ao recurso do emulador AzureAzure Cosmos DB, chame o método WithDataVolume no recurso do emulador 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...

O volume de dados é usado para persistir os dados do emulador Cosmos DB fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /tmp/cosmos/appdata no contêiner do emulador de Cosmos DB e, caso o parâmetro name não seja fornecido, o nome é gerado. O emulador tem sua variável de ambiente AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE definida como true. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos em vez de bind mounts, consulte a documentação em Docker: Volumes.

Configurar a contagem de partições do contêiner do emulador Cosmos DB

Para configurar a contagem de partições do contêiner do emulador Cosmos DB, chame o método 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...

O código anterior configura o contêiner do emulador Cosmos DB para ter uma contagem de partição de 100. Essa é uma abreviação para definir a variável de ambiente AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

Verificações de integridade de integração de hospedagem

A integração de hospedagem Azure Cosmos DB adiciona automaticamente uma verificação de integridade para o recurso de Cosmos DB. A verificação de saúde verifica se o Cosmos DB está em execução e se uma conexão pode ser estabelecida com ele.

A integração de hospedagem depende do pacote NuGet 📦 AspNetCore.HealthChecks.CosmosDb.

integração Client

Para começar a usar a integração .NET Aspire Microsoft Entity Framework CoreCosmos DB, instale o pacote NuGet 📦Aspire.Microsoft.EntityFrameworkCore.Cosmos no projeto consumidor client, ou seja, o projeto do aplicativo que utiliza o Microsoft Entity Framework CoreCosmos DBclient.

.NET Interface de Linha de Comando
PackageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

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

Adicionar Cosmos DB contexto

No arquivo Program.cs do seu projeto consumidor de client, chame o método de extensão AddCosmosDbContext para registrar um System.Data.Entity.DbContext para uso através do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

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

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso Cosmos DB no projeto de host do aplicativo. Em outras palavras, quando você chama AddAzureCosmosDB e fornece um nome de cosmosdb esse mesmo nome deve ser usado ao chamar AddCosmosDbContext. Para obter mais informações, consulte Adicionar AzureAzure Cosmos DBde recursos.

Em seguida, você pode recuperar a instância de DbContext usando a injeção de dependência. Por exemplo, para recuperar o client de um serviço:

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

Para obter mais informações sobre como usar Entity Framework Core com Azure Cosmos DB, consulte os exemplos de para Azure Cosmos DB do SDK do NoSQL para .NET.

Configuração

A .NET Aspire integração da Microsoft Entity Framework CoreCosmos DB fornece várias opções para configurar a conexão Azure Cosmos DB com base nos requisitos e convenções do seu projeto.

Usar uma cadeia de conexão

Ao usar uma cadeia de conexão da seção de configuração ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar builder.AddCosmosDbContext:

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

Em seguida, a cadeia de conexão será recuperada da seção de configuração do ConnectionStrings:

{
  "ConnectionStrings": {
    "CosmosConnection": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
  }
}

Para obter mais informações, consulte a documentação ConnectionString.

Usar provedores de configuração

A integração .NET Aspire Microsoft Entity Framework CoreCosmos DB dá suporte a Microsoft.Extensions.Configuration. Ele carrega o EntityFrameworkCoreCosmosSettings de arquivos de configuração, como appsettings.json. Exemplo _appsettings.json que configura algumas das opções:

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "Cosmos": {
          "DisableTracing": true
        }
      }
    }
  }
}

Para conferir o esquema completo de integração Cosmos DBclientJSON, consulte Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json.

Usar delegados em linha

Você também pode passar o delegado Action<EntityFrameworkCoreCosmosSettings> configureSettings para configurar algumas ou todas as opções EntityFrameworkCoreCosmosSettings diretamente, por exemplo, para desabilitar o rastreamento no código:

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

Client verificações de integridade de integração

Por padrão, as integrações de .NET.NET Aspire habilitam verificações de saúde para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral de integrações.

A integração do .NET Aspire Microsoft Entity Framework CoreCosmos DB atualmente não implementa verificações de estado, embora isso possa mudar em versões futuras.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro

A integração .NET Aspire Microsoft Entity Framework CoreCosmos DB usa as seguintes categorias de log:

Azure-Cosmos-Operation-Request-Diagnostics
Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Query

Rastreamento

A integração .NET Aspire Microsoft Entity Framework CoreCosmos DB emitirá as seguintes atividades de rastreamento usando OpenTelemetry:

Azure.Cosmos.Operation
OpenTelemetry.Instrumentation.EntityFrameworkCore

Métricas

A integração .NET Aspire Microsoft Entity Framework CoreCosmos DB atualmente dá suporte às seguintes métricas:

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

Compartilhar via