integração .NET AspireAzure Cosmos DB

Artigo
12/14/2024

Neste artigo, você aprenderá a usar a integração .NET AspireAzure Cosmos DB. A biblioteca Aspire.Microsoft.Azure.Cosmos é usada para registrar um CosmosClient como um singleton no contêiner de DI para conectar-se ao AzureAzure Cosmos DB. Ele também permite verificações de integridade correspondentes, registro em log e telemetria.

Começar

Para começar a usar a integração .NET AspireAzure Cosmos DB, instale o 📦Aspire. Microsoft.Azure. O Cosmos pacote NuGet no projeto que consome client, ou seja, o projeto do aplicativo que usa o Azure Cosmos DBclient.

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.Azure.Cosmos

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

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

Exemplo de uso

No arquivo Program.cs do seu projeto de consumo de client, chame a extensão AddAzureCosmosClient para registrar um Microsoft.Azure.Cosmos.CosmosClient para uso por meio do contêiner de injeção de dependência.

builder.AddAzureCosmosClient("cosmosConnectionName");

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

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

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

Uso do host do aplicativo

Para adicionar AzureAzure Cosmos DB suporte de hospedagem ao seu IDistributedApplicationBuilder, instale o pacote NuGet 📦Aspire.Hosting.Azure.CosmosDB no projeto aplicativo host. Isso é útil se você quiser que Aspire provisione uma nova conta de Azure Cosmos DB para você ou se quiser usar o emulador de Azure Cosmos DB. Se você quiser usar uma conta AzureAzure Cosmos DB que já esteja provisionada, não será necessário adicioná-la ao projeto de host do aplicativo.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

No projeto de host do aplicativo, registre a integração .NET AspireAzure Cosmos DB e consuma o serviço usando os seguintes métodos:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("myNewCosmosAccountName");
var cosmosdb = cosmos.AddDatabase("myCosmosDatabaseName");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(cosmosdb);

Dica

Para usar o emulador AzureAzure Cosmos DB, encadeia uma chamada ao método AddAzureCosmosDB.

cosmosdb.RunAsEmulator();

Iniciar o emulador de Cosmos DB pode levar algum tempo. Use WaitFor para atrasar a execução do código do projeto .NET até que o emulador esteja em funcionamento e pronto para responder a solicitações.

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(cosmosdb)
                            .WaitFor(cosmosdb);

Configuração

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

builder.AddAzureCosmosClient("cosmosConnectionName");

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

{
  "ConnectionStrings": {
    "cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
  }
}

A abordagem recomendada para conexão é utilizar um terminal de conta, que opera com a propriedade MicrosoftAzureCosmosSettings.Credential para estabelecer uma conexão. Se nenhuma credencial estiver configurada, o DefaultAzureCredential será usado:

{
    "ConnectionStrings": {
      "cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
    }
}

Como alternativa, uma cadeia de conexão AzureAzure Cosmos DB pode ser usada:

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

Usar provedores de configuração

A integração .NET AspireAzure Cosmos DB dá suporte a Microsoft.Extensions.Configuration. Ele carrega o MicrosoftAzureCosmosSettings de appsettings.json ou outros arquivos de configuração usando a chave Aspire:Microsoft:Azure:Cosmos. Exemplo appsettings.json que configura algumas das opções:

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

Usar delegados integrados

Você também pode passar o delegate Action<MicrosoftAzureCosmosSettings > para configurar algumas ou todas as opções inline, por exemplo, para desabilitar o rastreamento a partir do código:

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    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 do cabeçalho CosmosClientOptions.ApplicationName user-agent para todas as solicitações emitidas por este client:

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

Exames de saúde

Por padrão, as integrações .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 .NET AspireAzure Cosmos 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 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 AspireAzure Cosmos DB usa as seguintes categorias de log:

Azure-Operação-Cosmos-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. Saiba mais sobre o rastreamento no AzureAzure Cosmos DB.

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

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.

Compartilhar via