Partilhar via

.NET Aspire Azure Cosmos DB integração

  • Artigo

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 DI para conexão com AzureAzure Cosmos DB. Ele também permite verificações de saúde, registro e telemetria correspondentes.

Começar

Para começar com a integração .NET AspireAzure Cosmos DB, instale o 📦AspireMicrosoftAzureCosmos no pacote NuGet no projeto que consome client, ou seja, o projeto do aplicativo que utiliza o Azure Cosmos DBclient.

dotnet add package Aspire.Microsoft.Azure.Cosmos

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

Exemplo de utilização

No arquivo Program.cs do seu projeto que consome client, chame a extensão AddAzureCosmosClient para registar um Microsoft.Azure.Cosmos.CosmosClient para ser utilizado através do contendor de injeção de dependência.

builder.AddAzureCosmosClient("cosmosConnectionName");

Em seguida, você pode recuperar a instância CosmosClient usando a 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 relativos a Azure Cosmos DB no SDK do NoSQL para .NET.

Utilização do anfitrião da aplicação

Para adicionar o suporte de hospedagem AzureAzure Cosmos DB ao seu IDistributedApplicationBuilder, instale o pacote NuGet 📦Aspire.Hosting.Azure.CosmosDB no projeto de 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 de AzureAzure Cosmos DB que já esteja provisionada, não há necessidade de adicioná-la ao projeto de host do aplicativo.

dotnet add package Aspire.Hosting.Azure.CosmosDB

Em seu projeto de host de aplicativo, registre a integração de .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 de AzureAzure Cosmos DB, encadeie uma chamada para o método AddAzureCosmosDB.

cosmosdb.RunAsEmulator();

Iniciar o emulador de Cosmos DB pode levar algum tempo. Use WaitFor para atrasar a execução de código do projeto .NET até que o emulador esteja em execução e pronto para atender 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 de ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar builder.AddAzureCosmosClient:

builder.AddAzureCosmosClient("cosmosConnectionName");

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

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

O método de conexão recomendado é usar um endpoint de conta, que funciona com a propriedade MicrosoftAzureCosmosSettings.Credential para estabelecer uma conexão. Se nenhuma credencial estiver configurada, a DefaultAzureCredential será usada:

{
    "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 suporta Microsoft.Extensions.Configuration. Ele carrega o MicrosoftAzureCosmosSettings de appsettings.json ou outros ficheiros de configuração usando a chave Aspire:Microsoft:Azure:Cosmos. Exemplo de appsettings.json que configura algumas das opções:

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

Usar delegados embutidos

Você também pode passar o delegate Action<MicrosoftAzureCosmosSettings > para configurar algumas ou todas as opções embutidas, por exemplo, para desativar o rastreamento a partir de 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 CosmosClientOptions.ApplicationName sufixo de cabeçalho user-agent para todos os problemas de solicitações por esta client:

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

Controlos sanitários

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 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 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-Operação Cosmos-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.Operação

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. Saiba mais sobre o rastreamento em AzureAzure Cosmos DB.

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

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