Partilhar via

.NET Aspire Azure Cosmos DB integração

  • Artigo

Inclui:integração de Hosting 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 a partir de .NET com o emulador de Azure Cosmos DB.

Integração de hospedagem

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

Para aceder a esses tipos e APIs para os expressar, 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 add package ou Gerir dependências de pacotes em aplicações .NET.

Adicionar AzureAzure Cosmos DB recurso

No seu projeto de host de aplicativo, chame AddAzureCosmosDB para adicionar e retornar um gerador 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—que adiciona suporte para gerar recursos de 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 Bicep

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


Alterne AzureAzure Cosmos DB Bíceps. 

@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 coerê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, ele também provisiona um recurso Azure Key Vault. Isso é usado para armazenar a cadeia de conexão da conta Cosmos DB de forma segura. O Bíceps gerado é um ponto de partida e pode ser personalizado para atender às suas necessidades específicas.

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 fornecendo uma API fluente para configurar os recursos 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 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 de provisionamento.

Conectar-se a uma conta 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 AzureAzure Cosmos DB, você pode adicionar uma cadeia de conexão ao host do aplicativo. Para adicionar uma conexão a uma conta de 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...

Observação

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. Na nomenclatura .NET.NET Aspire, 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 parâmetro, neste caso "cosmos-db". A API GetConnectionString é uma abreviação de IConfiguration.GetSection("ConnectionStrings")[name].

Adicionar AzureAzure Cosmos DB recurso de banco de dados

Para adicionar um recurso de banco de dados AzureAzure Cosmos DB, encadeie 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 pelo 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.

Observação

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. Essa API destina-se a incluir um banco de dados no Bicep gerado pela infraestrutura de provisionamento.

Adicionar AzureAzure Cosmos DB recurso do emulador

Para adicionar um recurso de emulador de AzureAzure Cosmos DB, encadeie uma chamada num IResourceBuilder<AzureCosmosDBResource> na 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 AzureAzure Cosmos DB Emulator. O Azure Cosmos DB Emulator fornece um ambiente local gratuito para testar seus aplicativos Azure Cosmos DB e é um companheiro 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, como 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 de contêiner.

Configurar container 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 do contêiner do emulador Cosmos DB

Por predefinição, quando configurado pelo Cosmos DB, o contentor do emulador .NET Aspire expõe os seguintes pontos de extremidade:

Ponto final Porto de contentores Porta do host
https 8081 dinâmico

A porta em que ele está a escutar é dinâmica por padrão. Quando o contêiner é iniciado, a porta é mapeada para uma porta aleatória na máquina 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 de Cosmos DB existente do contêiner do emulador de https para escutar na porta 8081. A porta do contêiner do emulador de Cosmos DB é mapeada para a porta do host, conforme mostrado na tabela a seguir:

Nome do ponto final Cartografia de portos (container:host)
https 8081:7777
Configurar contentor do emulador Cosmos DB com duração persistente

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

Configurar o contentor do emulador Cosmos DB com volume de dados

Para adicionar um volume de dados ao recurso do emulador de 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 manter os dados do emulador de Cosmos DB fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /tmp/cosmos/appdata no contentor do emulador Cosmos DB e, quando não é fornecido um parâmetro name, o nome é gerado. O emulador tem sua variável de ambiente AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE definida como true. Para 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 Docker: Volumes.

Configurar a contagem de partições do contentor do emulador Cosmos DB

Para configurar a contagem de partições do contêiner do emulador de 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 de Cosmos DB para ter uma contagem de partições de 100. Esta é uma abreviatura para definir a variável de ambiente AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

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 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 📦 AspNetCore.HealthChecks.CosmosDb pacote NuGet.

Client integração

Para começar com a integração do cliente .NET AspireAzure Cosmos DB, instale o pacote NuGet 📦Aspire.Microsoft.Azure.Cosmos no projeto que consome o cliente, ou seja, o projeto para a aplicação que usa o cliente Cosmos DB. A integração do cliente Cosmos DB registra uma instância CosmosClient que você pode usar para interagir com Cosmos DB.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Adicionar Cosmos DB cliente

No arquivo de Program.cs do seu projeto cliente-consumidor, chame o método de extensão AddAzureCosmosClient em qualquer IHostApplicationBuilder para registrar um CosmosClient 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.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 AzureAzure Cosmos DB recurso.

Em seguida, você pode recuperar a instância CosmosClient usando a 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 a injeção de dependência, consulte .NET injeção de dependência.

Adicionar cliente Cosmos DB com chave

Pode haver situações em que você queira registrar várias instâncias de CosmosClient com nomes de conexão diferentes. Para registrar clientes Cosmos DB chaveados, 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 Cosmos DB configure dois bancos de dados nomeados, um para o mainDb e outro para o loggingDb.

Em seguida, você pode recuperar as instâncias CosmosClient usando a 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 com chave, consulte .NET injeção de dependência: Serviços com chave.

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 de 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 suporta Microsoft.Extensions.Configuration. Ele carrega o MicrosoftAzureCosmosSettings da configuração usando a chave Aspire:Microsoft:Azure:Cosmos. O trecho a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

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

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

Usar delegados embutidos

Além disso, podes passar o delegado Action<MicrosoftAzureCosmosSettings> configureSettings para configurar algumas ou todas as opções diretamente, por exemplo, para desativar 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 CosmosClientOptions.ApplicationName do cabeçalho user-agent para todas as solicitações feitas por este cliente:

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

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

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

A integração .NET AspireAzure Cosmos DB:

  • Adiciona a verificação de integridade quando MicrosoftAzureCosmosSettings.DisableTracing é false, que tenta se conectar ao Cosmos DB.
  • Integra-se com o ponto final HTTP /health, que especifica que todas as verificações de integridade registadas devem ser aprovadas para que a aplicação seja considerada pronta para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente o registo, a rastreabilidade e as métricas, que são por vezes conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na secção Configuração.

Registo

A integração .NET AspireAzure Cosmos DB usa as seguintes categorias de log:

  • Azure-Cosmos-Operation-Request-Diagnostics

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

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

Rastreio

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

  • Azure.Cosmos.Operation

Azure Azure Cosmos DB rastreamento está atualmente em pré-visualização, portanto, terá de definir o interruptor experimental para garantir que os traces sejam emitidos.

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

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

Métricas

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

Ver também