Compartilhar via

integração .NET AspireAzure Cosmos DB

  • Artigo

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

Azure Cosmos DB é um serviço de banco de dados NoSQL totalmente gerenciado para desenvolvimento de aplicativos modernos. A integração .NET AspireAzure Cosmos DB 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:

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

dotnet add package Aspire.Hosting.Azure.CosmosDB

Para obter mais informações, consulte dotnet adicionar pacote ou Gerenciar dependências de pacotes em .NET aplicações.

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 um dos outros recursos 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.

Provisionamento gerado com Bicep

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

@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

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: as localizações da conta Cosmos DB. O padrão é o local do grupo de recursos.

Além da conta Cosmos DB, ela também adiciona o aplicativo atual à função Data Contributor para a conta Cosmos DB. 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 personalização do Bicep gerado ao oferecer uma API fluente para configurar os recursos do Azure utilizando 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:

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. Personalização do provisionamento.

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 ao 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 GetConnectionString é uma abreviação para IConfiguration.GetSection("ConnectionStrings")[name].

Adicionar AzureAzure Cosmos DB banco de dados e recursos de contêiner

Para adicionar um recurso de banco de dados AzureAzure Cosmos DB, chame o método AddCosmosDatabase em uma instância de IResourceBuilder<AzureCosmosDBResource>:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Quando você chama AddCosmosDatabase, ele adiciona um banco de dados chamado db aos recursos de Cosmos DB e retorna o recurso de banco de dados recém-criado. 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.

Um contêiner AzureAzure Cosmos DB é onde os dados são armazenados. Ao criar um contêiner, você precisa fornecer uma chave de partição.

Para adicionar um recurso de contêiner AzureAzure Cosmos DB, chame o método AddContainer em uma instância de 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...

O contêiner é criado no banco de dados representado pela AzureCosmosDBDatabaseResource que você adicionou anteriormente.

Para obter mais informações, consulte Bancos de Dados, Contêineres e Itens no AzureAzure Cosmos DB.

Adicionar AzureAzure Cosmos DB recurso do emulador

Para adicionar um recurso do emulador AzureAzure Cosmos DB, faça uma chamada em cadeia a partir de um IResourceBuilder<AzureCosmosDBResource> para a 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 nesse 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 do contêiner.

Configurar contêiner de 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, as variáveis de ambiente, seu tempo de vida e muito mais.

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

Por padrão, o contêiner do emulador Cosmos DB, quando configurado por .NET Aspire, expõe os seguintes pontos de extremidade:

Ponto de extremidade Porta de contêiner Porta do host
https 8081 dinâmico

A porta em que ele está escutando é 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, encadeie 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 Cosmos DB existente do contêiner do emulador https para ouvir a 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 Cosmos DB contêiner do emulador com tempo de vida 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 ciclo de vida do recurso do contêiner.

Configurar contêiner de emulação 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 dentro do contêiner do emulador Cosmos DB e, quando o parâmetro name não é 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 entender por que eles são preferidos em vez de montagens de vinculação, 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.

Usar o emulador baseado em Linux(versão prévia)

A próxima geração do emulador AzureAzure Cosmos DB é totalmente baseada em Linuxe está disponível como um contêiner Docker. Ele dá suporte à execução em uma ampla variedade de processadores e sistemas operacionais.

Para usar a versão prévia do emulador de Cosmos DB, chame o método RunAsPreviewEmulator. Como esse recurso está em versão prévia, você precisa aceitar explicitamente o recurso de visualização suprimindo o diagnóstico experimental ASPIRECOSMOSDB001.

O emulador de visualização também dá suporte à exposição de um endpoint do "Data Explorer", que permite visualizar os dados armazenados no emulador Cosmos DB por meio de uma interface web. Para habilitar o Data Explorer, chame o método 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...

O código anterior configura o contêiner do emulador de visualização baseado em LinuxCosmos DB, com o ponto de extremidade do Data Explorer, para uso em tempo de execução.

Verificações de integridade da 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 integridade 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 integrar o cliente .NET AspireAzure Cosmos DB, instale o pacote NuGet 📦Aspire.Microsoft.Azure.Cosmos no projeto que consome o cliente, ou seja, o projeto do aplicativo que utiliza o cliente Cosmos DB. A integração do cliente Cosmos DB registra uma instância de CosmosClient que você pode usar para interagir com Cosmos DB.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Adicionar Cosmos DB cliente

No arquivo Program.cs do projeto que utiliza o cliente, chame o método de extensão AddAzureCosmosClient em qualquer IHostApplicationBuilder para registrar um CosmosClient para que possa ser usado por meio do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddAzureCosmosClient(connectionName: "cosmos-db");

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 cosmos-db esse mesmo nome deve ser usado ao chamar AddAzureCosmosClient. Para obter mais informações, consulte adicionar o recurso AzureAzure Cosmos DB.

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

public class ExampleService(CosmosClient client)
{
    // Use client...
}

Para obter mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Adicionar cliente com chave Cosmos DB

Pode haver situações em que você deseja registrar várias instâncias de CosmosClient com nomes de conexão diferentes. Para registrar clientes chaveados de Cosmos DB, chame o método AddKeyedAzureCosmosClient.

builder.AddKeyedAzureCosmosClient(name: "mainDb");
builder.AddKeyedAzureCosmosClient(name: "loggingDb");

Importante

Ao usar serviços com chave, espera-se que seu recurso de Cosmos DB configure dois bancos de dados nomeados, um para o mainDb e outro para o loggingDb.

Você pode então recuperar as instâncias de CosmosClient usando injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

public class ExampleService(
    [FromKeyedServices("mainDb")] CosmosClient mainDbClient,
    [FromKeyedServices("loggingDb")] CosmosClient loggingDbClient)
{
    // Use clients...
}

Para obter mais informações sobre serviços chaveados, consulte .NET injeção de dependência: serviços chaveados.

Configuração

A integração .NET AspireAzure Cosmos DB fornece várias opções para configurar a conexão 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 o método AddAzureCosmosClient:

builder.AddAzureCosmosClient("cosmos-db");

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

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

Para obter mais informações sobre como formatar essa cadeia de conexão, consulte a documentação connectionString.

Usar provedores de configuração

A integração .NET AspireAzure Cosmos DB dá suporte a Microsoft.Extensions.Configuration. Ele carrega o MicrosoftAzureCosmosSettings a partir da configuração usando a chave Aspire:Microsoft:Azure:Cosmos. O snippet a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

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

Para obter o esquema Cosmos DB de integração completa do cliente JSON, consulte Aspire.Microsoft.Azure.Cosmos/ConfigurationSchema.json.

Usar delegados em linha

Além disso, você pode passar o delegado Action<MicrosoftAzureCosmosSettings> configureSettings para configurar algumas ou todas as opções em linha, por exemplo, para desabilitar o rastreamento a partir do código:

builder.AddAzureCosmosClient(
    "cosmos-db",
    static settings => settings.DisableTracing = true);

Você também pode configurar o Microsoft.Azure.Cosmos.CosmosClientOptions usando o parâmetro Action<CosmosClientOptions> configureClientOptions opcional do método AddAzureCosmosClient. Por exemplo, para definir o sufixo de cabeçalho do agente de usuário CosmosClientOptions.ApplicationName para todas as solicitações feitas por este cliente:

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

Client verificações de saúde da integração

A integração do cliente .NET AspireCosmos DB atualmente não implementa verificações de integridade, embora isso possa mudar em versões futuras.

Observabilidade e telemetria

.NET .NET Aspire integrações automaticamente configuram Registro, Rastreamento e Métricas, que às vezes são conhecidos 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 AspireAzure Cosmos DB usa as seguintes categorias de log:

  • Azure-Cosmos-Operation-Request-Diagnostics

Além de obter diagnósticos de solicitação Azure Cosmos DB para solicitações com falha, você pode configurar limites de latência para determinar quais diagnósticos de solicitações Azure Cosmos DB bem-sucedidas serão registrados. Os valores padrão são 100 ms para operações de ponto e 500 ms para operações não pontuais.

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => {
            clientOptions.CosmosClientTelemetryOptions = new()
            {
                CosmosThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

Rastreamento

A integração .NET AspireAzure Cosmos DB emitirá as seguintes atividades de rastreamento usando OpenTelemetry:

  • Azure.Cosmos.Operation

O rastreamento AzureAzure Cosmos DB está atualmente em versão prévia, portanto, você deve ativar a opção experimental para garantir que os rastreamentos sejam gerados.

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

Para obter mais informações, consulte AzureAzure Cosmos DB observabilidade do SDK: atributos de rastreio.

Métricas

A integração .NET AspireAzure Cosmos DB atualmente não dá suporte a métricas por padrão devido a limitações com o SDK do Azure.

Consulte também