Sugestões de desempenho para o Azure Cosmos DB e .NET

O Azure Cosmos DB é um banco de dados distribuído rápido e flexível que pode ser dimensionado perfeitamente com níveis garantidos de latência e taxa de transferência. Você não precisa fazer grandes alterações na arquitetura ou escrever código complexo para dimensionar seu banco de dados com o Azure Cosmos DB. Escalar para cima e para baixo é tão fácil quanto fazer uma única chamada de API. Para saber mais, consulte a taxa de transferência de contêiner provisionada ou a taxa de transferência de banco de dados provisionada.

Como o Azure Cosmos DB é acessado por meio de chamadas de rede, você pode fazer otimizações do lado do cliente para atingir o desempenho máximo ao usar o SDK do SQL .NET.

Se você estiver tentando melhorar o desempenho do banco de dados, considere as opções apresentadas nas seções a seguir.

Recomendações de hospedagem

Ativar a coleta de lixo do lado do servidor

Reduzir a frequência da coleta de lixo pode ajudar em alguns casos. No .NET, defina gcServer como true.

Dimensione a carga de trabalho do cliente

Se estiver a testar com níveis elevados de taxa de transferência, ou a taxas superiores a 50.000 Unidades de Pedido por segundo (RU/s), a aplicação cliente poderá tornar-se um gargalo para a carga de trabalho, porque a máquina poderá atingir o limite na utilização do CPU ou da rede. Se você chegar a esse ponto, poderá continuar a expandir a conta do Azure Cosmos DB ao distribuir seus aplicativos cliente por vários servidores.

Operações de metadados

Não verifique se um banco de dados ou contêiner existe chamando Create...IfNotExistsAsync ou Read...Async no caminho ativo ou antes de fazer uma operação de item. A validação só deve ser feita na inicialização do aplicativo quando for necessário, se você espera que eles sejam excluídos (caso contrário, não é necessário). Essas operações de metadados geram latência extra de ponta a ponta, não têm SLA e têm suas próprias limitações separadas que não são dimensionadas como operações de dados.

Registo e rastreio

Alguns ambientes têm o .NET DefaultTraceListener habilitado. O DefaultTraceListener apresenta problemas de desempenho em ambientes de produção, causando altos gargalos de CPU e E/S. Verifique e certifique-se de que o DefaultTraceListener está desativado para seu aplicativo removendo-o do TraceListeners em ambientes de produção.

As versões do SDK maiores que 3.23.0 o removem automaticamente quando detetado. Com versões mais antigas, você pode removê-lo usando os seguintes comandos:

if (!Debugger.IsAttached)
{
    Type defaultTrace = Type.GetType("Microsoft.Azure.Cosmos.Core.Trace.DefaultTrace,Microsoft.Azure.Cosmos.Direct");
    TraceSource traceSource = (TraceSource)defaultTrace.GetProperty("TraceSource").GetValue(null);
    traceSource.Listeners.Remove("Default");
    // Add your own trace listeners
}

<configuration>
  <system.diagnostics>
    <sources>
      <source name="DocDBTrace" switchName="SourceSwitch" switchType="System.Diagnostics.SourceSwitch" >
        <listeners>
          <remove name="Default" />
          <!--Add your own trace listeners-->
          <add name="myListener" ... />
        </listeners>
      </source>
    </sources>
  </system.diagnostics>
<configuration>

Alta disponibilidade

Para obter orientações gerais sobre como configurar a alta disponibilidade no Azure Cosmos DB, consulte Alta disponibilidade no Azure Cosmos DB.

Além de uma boa configuração fundamental na plataforma de banco de dados, existem técnicas específicas que podem ser implementadas no próprio SDK do .NET, o que pode ajudar em cenários de paralisação. Duas estratégias notáveis são a estratégia de disponibilidade baseada em limites e o disjuntor de nível de partição.

Estratégia de disponibilidade baseada em limites

A estratégia de disponibilidade baseada em limites pode melhorar a latência e a disponibilidade finais enviando solicitações de leitura paralelas para regiões secundárias (conforme definido em ApplicationPreferredRegions) e aceitando a resposta mais rápida. Essa abordagem pode reduzir drasticamente o efeito de interrupções regionais ou condições de alta latência no desempenho do aplicativo.

Exemplo de configuração:

A configuração pode ser feita usando CosmosClientBuilder:

CosmosClient client = new CosmosClientBuilder("connection string")
    .WithApplicationPreferredRegions(
        new List<string> { "East US", "East US 2", "West US" } )
    .WithAvailabilityStrategy(
        AvailabilityStrategy.CrossRegionHedgingStrategy(
        threshold: TimeSpan.FromMilliseconds(500),
        thresholdStep: TimeSpan.FromMilliseconds(100)
     ))
    .Build();

Ou configurando opções e adicionando-as a CosmosClient:

CosmosClientOptions options = new CosmosClientOptions()
{
    AvailabilityStrategy
     = AvailabilityStrategy.CrossRegionHedgingStrategy(
        threshold: TimeSpan.FromMilliseconds(500),
        thresholdStep: TimeSpan.FromMilliseconds(100)
     )
      ApplicationPreferredRegions = new List<string>() { "East US", "East US 2", "West US"},
};

CosmosClient client = new CosmosClient(
    accountEndpoint: "account endpoint",
    authKeyOrResourceToken: "auth key or resource token",
    clientOptions: options);

Como funciona:

1. Pedido inicial: No momento T1, uma solicitação de leitura é feita para a região primária (por exemplo, Leste dos EUA). O SDK aguarda uma resposta por até 500 milissegundos (o threshold valor).

2. Segundo pedido: Se não houver resposta da região primária dentro de 500 milissegundos, uma solicitação paralela será enviada para a próxima região preferida (por exemplo, Leste dos EUA 2).

3. Terceiro pedido: Se nem a região primária nem a secundária responderem dentro de 600 milissegundos (500 ms + 100 ms, o thresholdStep valor), o SDK enviará outra solicitação paralela para a terceira região preferida (por exemplo, Oeste dos EUA).

4. A resposta mais rápida vence: Seja qual for a região que responder primeiro, essa resposta é aceita e as outras solicitações paralelas são ignoradas.

Disjuntor de nível de partição

O disjuntor de nível de partição (PPCB) é um recurso do SDK do .NET que aprimora a disponibilidade e a latência rastreando partições físicas não íntegras. Quando ativado, ele ajuda a rotear solicitações para regiões mais saudáveis, evitando falhas em cascata devido a problemas regionais ou específicos de partição. O recurso é independente do failover acionado por back-end e é controlado por meio de variáveis de ambiente.

Esse recurso é desabilitado por padrão, mas é habilitado automaticamente quando o failover no nível de partição está habilitado.

Como funciona

1. Deteção de falhas: Quando erros específicos como 503 Service Unavailable, 408 Request Timeoutou tokens de cancelamento são observados, o SDK conta falhas consecutivas para uma partição.
2. Acionando failover: Quando um limite configurado de falhas consecutivas é atingido, o SDK redireciona as solicitações para esse intervalo de chaves de partição para a próxima região preferida usando GlobalPartitionEndpointManagerCore.TryMarkEndpointUnavailableForPartitionKeyRangeo .
3. Recuperação em segundo plano: Uma tarefa em segundo plano é iniciada durante o failover para reavaliar periodicamente a integridade da partição com falha tentando se conectar a todas as quatro réplicas. Assim que estiver saudável, o SDK remove a substituição e regressa à região primária.

Comportamento por tipo de conta

• Escrita de região única (mestre único): Somente solicitações de leitura participam da lógica de failover do PPCB.
• Escrita multi-região (multi master): As solicitações de leitura e gravação usam a lógica de failover do PPCB.

Opções de configuração

Use as seguintes variáveis de ambiente para configurar o PPCB:

Comparando otimizações de disponibilidade

• Estratégia de disponibilidade baseada em limites:

  • Benefício: Reduz a latência final enviando solicitações de leitura paralelas para regiões secundárias e melhora a disponibilidade antecipando solicitações que resultam em tempos limite de rede.
  • Compensação: Incorre em custos extras de Unidades de Solicitação (RUs) em comparação com o disjuntor, devido a solicitações paralelas adicionais entre regiões (embora apenas durante períodos em que os limites são violados).
  • Caso de uso: ideal para cargas de trabalho de leitura pesada em que a redução da latência é crítica e algum custo extra (tanto em termos de carga de RU quanto de pressão da CPU do cliente) é aceitável. As operações de gravação também podem beneficiar-se, se optarem pela política de tentativa de reescrita não idempotente e a conta permitir escritas em múltiplas regiões.

• Disjuntor de nível de partição:

  • Benefício: Melhora a disponibilidade e a latência, evitando partições não íntegras e garantindo que as solicitações sejam encaminhadas para regiões mais saudáveis.
  • Compensação: Não incorre em mais custos de RU, mas ainda pode permitir alguma perda inicial de disponibilidade para solicitações que resultam em timeouts de rede.
  • Caso de uso: Ideal para cargas de trabalho intensivas em escrita ou mistas onde o desempenho consistente é essencial, especialmente ao lidar com partições que podem tornar-se intermitentemente não saudáveis.

Ambas as estratégias podem ser usadas juntas para melhorar a disponibilidade de leitura e gravação e reduzir a latência final. O disjuntor de nível de partição pode lidar com vários cenários de falha transitória, incluindo aqueles que podem resultar em réplicas de desempenho lento, sem a necessidade de executar solicitações paralelas. Além disso, a adição de uma estratégia de disponibilidade baseada em limites minimiza ainda mais a latência final e elimina a perda de disponibilidade, se o custo extra de RU for aceitável.

Ao implementar essas estratégias, os desenvolvedores podem garantir que seus aplicativos permaneçam resilientes, mantenham o alto desempenho e forneçam uma melhor experiência ao usuário, mesmo durante interrupções regionais ou condições de alta latência.

Regiões excluídas

O recurso de regiões excluídas permite um controle refinado sobre o roteamento de solicitações, permitindo que você exclua regiões específicas de seus locais preferidos por solicitação. Esse recurso está disponível no Azure Cosmos DB .NET SDK versão 3.37.0 e superior.

Principais benefícios:

• Limite de taxa de manipulação: ao encontrar 429 respostas (muitas solicitações), encaminhe automaticamente as solicitações para regiões alternativas com taxa de transferência disponível
• Roteamento direcionado: garanta que as solicitações sejam atendidas de regiões específicas, excluindo todas as outras
• Ignorar ordem preferencial: substitua a lista de regiões preferenciais padrão para solicitações individuais sem criar clientes separados

Configuration:

As regiões excluídas podem ser configuradas no nível da solicitação usando a ExcludeRegions propriedade:

CosmosClientOptions clientOptions = new CosmosClientOptions()
{
    ApplicationPreferredRegions = new List<string> {"West US", "Central US", "East US"}
};

CosmosClient client = new CosmosClient(connectionString, clientOptions);

Database db = client.GetDatabase("myDb");
Container container = db.GetContainer("myContainer");

//Request will be served out of the West US region
await container.ReadItemAsync<dynamic>("item", new PartitionKey("pk"));

//By using ExcludeRegions, we are able to bypass the ApplicationPreferredRegions list
// and route a request directly to the East US region
await container.ReadItemAsync<dynamic>(
  "item", 
  new PartitionKey("pk"),
  new ItemRequestOptions()
  {
    ExcludeRegions = new List<string>() { "West US", "Central US" }
  });

Exemplo de caso de uso - limitação da taxa de manipulação:

ItemResponse<CosmosItem> item;
item = await container.ReadItemAsync<CosmosItem>("id", partitionKey);

if (item.StatusCode == HttpStatusCode.TooManyRequests)
{
    ItemRequestOptions requestOptions = new ItemRequestOptions()
    {
        ExcludeRegions = new List<string>() { "East US" }
    };

    item = await container.ReadItemAsync<CosmosItem>("id", partitionKey, requestOptions);
}

O recurso também funciona com consultas e outras operações:

QueryRequestOptions queryRequestOptions = new QueryRequestOptions()
{
    ExcludeRegions = new List<string>() { "East US" }
};

using (FeedIterator<CosmosItem> queryFeedIterator = container.GetItemQueryIterator<CosmosItem>(
    queryDefinition, 
    requestOptions: queryRequestOptions))
{
    while(queryFeedIterator.HasMoreResults)
    {
        var item = await queryFeedIterator.ReadNextAsync();
    }
}

Ajuste preciso de consistência vs disponibilidade

O recurso de regiões excluídas fornece um mecanismo adicional para equilibrar compensações de consistência e disponibilidade em seu aplicativo. Esta capacidade é particularmente valiosa em cenários dinâmicos em que os requisitos podem mudar com base nas condições operacionais:

Tratamento dinâmico de interrupções: quando uma região primária sofre uma interrupção e os limites do disjuntor no nível da partição se mostram insuficientes, as regiões excluídas permitem failover imediato sem alterações de código ou reinicializações de aplicativos. Isso fornece uma resposta mais rápida a problemas regionais em comparação com a espera pela ativação automática do disjuntor.

Preferências de consistência condicional: os aplicativos podem implementar diferentes estratégias de consistência com base no estado operacional:

• Estado estacionário: priorize leituras consistentes excluindo todas as regiões, exceto a principal, garantindo a consistência dos dados ao custo potencial de disponibilidade
• Cenários de paralisação: favoreça a disponibilidade em detrimento da consistência estrita, permitindo o roteamento entre regiões, aceitando possíveis atrasos de dados em troca de disponibilidade contínua do serviço

Essa abordagem permite que mecanismos externos (como gerenciadores de tráfego ou balanceadores de carga) orquestram decisões de failover enquanto o aplicativo mantém o controle sobre os requisitos de consistência por meio de padrões de exclusão de região.

Quando todas as regiões forem excluídas, as solicitações serão encaminhadas para a região principal/central. Esse recurso funciona com todos os tipos de solicitação, incluindo consultas, e é particularmente útil para manter instâncias de cliente singleton enquanto alcança um comportamento de roteamento flexível.

Rede

Política de conexão: usar o modo de conexão direta

O modo de conexão padrão do SDK do .NET V3 é direto com o protocolo TCP. Você configura o modo de conexão ao criar a CosmosClient instância no CosmosClientOptions. Para saber mais sobre as diferentes opções de conectividade, consulte o artigo Modos de conectividade.

CosmosClient client = new CosmosClient(
  "<nosql-account-endpoint>",
  tokenCredential
  new CosmosClientOptions
  {
      ConnectionMode = ConnectionMode.Gateway // ConnectionMode.Direct is the default
  }
);

Exaustão de portas efémeras

Caso veja um alto volume de conexão ou um uso elevado de portas nas suas instâncias, primeiramente, confirme se as instâncias do cliente são singletons. Em outras palavras, as instâncias do cliente devem ser exclusivas durante o tempo de vida do aplicativo.

Quando está sendo executado no protocolo TCP, o cliente otimiza a latência usando as conexões de longa duração. Isso contrasta com o protocolo HTTPS, que encerra as conexões após dois minutos de inatividade.

Em cenários em que você tem acesso esparso e se notar uma contagem de conexões maior quando comparado ao acesso no modo Gateway, você pode:

• Configure a propriedade CosmosClientOptions.PortReuseMode para PrivatePortPool (eficaz com versões 4.6.1 e posteriores do framework e versões 2.0 e posteriores do .NET Core). Esta propriedade permite que o kit de desenvolvimento de software (SDK) use um pequeno grupo de portas efémeras para vários endpoints de destino do Azure Cosmos DB.
• Configure a propriedade CosmosClientOptions.IdleTcpConnectionTimeout para ser maior ou igual a 10 minutos. Os valores recomendados são de 20 minutos a 24 horas.

Para desempenho, coloque clientes na mesma região do Azure

Quando possível, coloque todos os aplicativos que chamam o Azure Cosmos DB na mesma região que o banco de dados do Azure Cosmos DB. Aqui está uma comparação aproximada: as chamadas para o Azure Cosmos DB dentro da mesma região terminam dentro de 1 milissegundo (ms) a 2 ms, mas a latência entre a costa oeste e leste dos EUA é superior a 50 ms. Essa latência pode variar de solicitação para solicitação, dependendo da rota tomada pela solicitação à medida que ela passa do cliente para o limite do datacenter do Azure.

Você pode obter a menor latência possível garantindo que o aplicativo de chamada esteja localizado na mesma região do Azure que o ponto de extremidade provisionado do Azure Cosmos DB. Para obter uma lista de regiões disponíveis, consulte Regiões do Azure.

Aumentar o número de threads/tarefas

Como as chamadas para o Azure Cosmos DB são feitas pela rede, talvez seja necessário variar o grau de simultaneidade de suas solicitações para que o aplicativo cliente passe o mínimo de tempo esperando entre as solicitações. Por exemplo, se estiveres a usar a Biblioteca Paralela de Tarefas do .NET, cria na ordem de cem tarefas que leem ou escrevem no Azure Cosmos DB.

Habilite a rede acelerada para reduzir a latência e os desvios da CPU

É recomendável que você siga as instruções para habilitar a Rede Acelerada em sua VM do Azure Windows ou Linux para maximizar o desempenho.

Sem rede acelerada, a E/S que transita entre sua VM do Azure e outros recursos do Azure pode ser roteada desnecessariamente por meio de um host e comutador virtual situado entre a VM e sua placa de rede. Ter o host e o comutador virtual embutidos no caminho de dados não só aumenta a latência e os desvios no canal de comunicação, como também rouba ciclos de CPU da VM. Com rede acelerada, a VM interage diretamente com a NIC sem intermediários; todos os detalhes da política de rede que foram manipulados pelo host e pelo comutador virtual agora são tratados no hardware da NIC; O host e o comutador virtual são ignorados. Geralmente, você pode esperar menor latência e maior taxa de transferência, bem como latência mais consistente e menor utilização da CPU quando você habilita a rede acelerada.

Limitações: a rede acelerada deve ser suportada no sistema operacional da VM e só pode ser habilitada quando a VM é interrompida e deslocalizada. A VM não pode ser implantada com o Azure Resource Manager. App Service não tem rede acelerada ativada.

Para obter mais detalhes, consulte as instruções para Windows e Linux .

Utilização do SDK

Instalar o SDK mais recente

Os SDKs do Azure Cosmos DB estão sendo constantemente aprimorados para fornecer o melhor desempenho. Para determinar o SDK mais recente e revisar as melhorias, consulte SDK do Azure Cosmos DB.

Usar APIs de fluxo

O .NET SDK V3 contém APIs de fluxo que podem receber e retornar dados sem serialização.

Os aplicativos de camada intermediária que não consomem respostas diretamente do SDK, mas as retransmitem para outras camadas de aplicativo, podem se beneficiar das APIs de fluxo. Para obter exemplos de manipulação de fluxo, consulte os exemplos de gerenciamento de itens.

Use um cliente singleton do Azure Cosmos DB durante o tempo de vida da sua aplicação

Cada instância CosmosClient é segura para threads e executa um gerenciamento de conexão eficiente e armazenamento em cache de endereços quando está a operar no modo direto. Para permitir um gerenciamento de conexão eficiente e um melhor desempenho do cliente SDK, recomendamos que você use uma única instância por AppDomain durante o tempo de vida do aplicativo para cada conta com a qual seu aplicativo interage.

Para aplicativos multilocatários que lidam com várias contas, consulte as práticas recomendadas relacionadas.

Quando você estiver trabalhando no Azure Functions, as instâncias também devem seguir as diretrizes existentes e manter uma única instância.

Evite bloquear chamadas

O SDK do Azure Cosmos DB deve ser projetado para processar muitas solicitações simultaneamente. As APIs assíncronas permitem que um pequeno pool de threads lide com milhares de solicitações simultâneas, sem precisar esperar por chamadas bloqueantes. Em vez de aguardar a conclusão de uma tarefa síncrona de longa duração, o thread pode trabalhar em outra solicitação.

Um problema de desempenho comum em aplicativos que usam o SDK do Azure Cosmos DB é bloquear chamadas que podem ser assíncronas. Muitas chamadas de bloqueio síncronas levam ao esgotamento do pool de threads e a uma degradação dos tempos de resposta.

Não:

• Bloqueie a execução assíncrona chamando Task.Wait ou Task.Result.
• Use Task.Run para tornar uma API síncrona em assíncrona.
• Obtenha bloqueios em caminhos de código comuns. O Azure Cosmos DB .NET SDK tem mais desempenho quando arquitetado para executar código em paralelo.
• Chame Task.Run e aguarde imediatamente. ASP.NET Core já executa o código do aplicativo em threads normais do Pool de Threads, portanto, chamar Task.Run resulta apenas em agendamento extra desnecessário do pool de threads. Mesmo que o código agendado bloqueie um thread, Task.Run não impede isso.
• Não use ToList() no Container.GetItemLinqQueryable<T>(), que usa o bloqueio de chamadas para drenar a consulta de forma síncrona. Use ToFeedIterator() para esvaziar a consulta de forma assíncrona.

Fazer:

• Chame assincronamente as APIs .NET do Azure Cosmos DB.
• Toda a stack de chamadas é assíncrona para se beneficiar dos padrões async/await.

Um criador de perfil, como PerfView, pode ser usado para localizar threads frequentemente adicionados ao pool de threads. O evento Microsoft-Windows-DotNETRuntime/ThreadPoolWorkerThread/Start indica um thread adicionado ao pool de threads.

Desativar a resposta de conteúdo em operações de gravação

Para cargas de trabalho com cargas de criação pesadas, defina a EnableContentResponseOnWrite opção de solicitação como false. O serviço não retorna mais o recurso criado ou atualizado para o SDK. Normalmente, como o aplicativo tem o objeto que está sendo criado, ele não precisa do serviço para retorná-lo. Os valores de cabeçalho ainda estão acessíveis, como o valor de uma taxa de solicitação. Desabilitar a resposta de conteúdo pode ajudar a melhorar o desempenho, porque o SDK não precisa mais alocar memória ou serializar o corpo da resposta. Ele também reduz o uso da largura de banda da rede para ajudar ainda mais o desempenho.

ItemRequestOptions requestOptions = new ItemRequestOptions() { EnableContentResponseOnWrite = false };
ItemResponse<Book> itemResponse = await this.container.CreateItemAsync<Book>(book, new PartitionKey(book.pk), requestOptions);
// Resource will be null
itemResponse.Resource

Habilite o Bulk para otimizar a taxa de transferência em vez da latência

Habilite o Bulk para cenários em que a carga de trabalho requer uma grande quantidade de taxa de transferência e a latência não é tão importante. Para obter mais informações sobre como ativar o recurso Bulk e saber para quais cenários ele deve ser usado, consulte Introdução ao suporte Bulk.

Aumente System.Net MaxConnections por host ao usar o modo Gateway

As solicitações do Azure Cosmos DB são feitas por HTTPS/REST quando você usa o modo Gateway. Eles estão sujeitos ao limite de conexão padrão por nome de host ou endereço IP. Talvez seja necessário definir MaxConnections como um valor mais alto (de 100 a 1.000) para que a biblioteca de cliente possa usar várias conexões simultâneas com o Azure Cosmos DB. No .NET SDK 1.8.0 e posterior, o valor padrão para ServicePointManager.DefaultConnectionLimit é 50. Para alterar o valor, você pode definir Documents.Client.ConnectionPolicy.MaxConnectionLimit como um valor mais alto.

Aumentar o número de threads/tarefas

Consulte Aumentar o número de threads/tarefas na secção Rede deste artigo.

Gestão das Dependências do Newtonsoft.Json

Visão geral

O Azure Cosmos DB .NET SDK tem uma dependência de Newtonsoft.Json para operações de serialização JSON. Esta dependência não é gerida automaticamente – deve adicionar Newtonsoft.Json explicitamente como uma dependência direta no seu projeto.

O SDK compila-se internamente contra o Newtonsoft.Json 10.x, que tem uma vulnerabilidade de segurança conhecida. Embora o SDK seja tecnicamente compatível com a 10.x, e a utilização do Newtonsoft.Json pelo SDK não seja suscetível ao problema de segurança reportado, recomendamos ainda assim a utilização da versão 13.0.3 ou superior para evitar potenciais problemas ou conflitos de segurança. As versões 13.x incluem alterações irregulares, mas os padrões de utilização do SDK são compatíveis com essas alterações.

Configuração Recomendada

Adicione Newtonsoft.Json sempre explicitamente a versão 13.0.3 ou superior como dependência direta ao usar o Azure Cosmos DB DB .NET SDK v3. Não use a versão 10.x devido a vulnerabilidades de segurança conhecidas.

Para os projetos padrão .csproj

<ItemGroup>
  <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
  <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>

Para projetos que utilizam gestão central de pacotes

Se o seu projeto usar Directory.Packages.props:

<Project>
  <ItemGroup>
    <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
  </ItemGroup>
</Project>

Resolução de Conflitos de Versões

Referência Newtonsoft.Json em falta

Se encontrares um erro de construção como:

The Newtonsoft.Json package must be explicitly referenced with version >= 10.0.2. Please add a reference to Newtonsoft.Json or set the 'AzureCosmosDisableNewtonsoftJsonCheck' property to 'true' to bypass this check.

Este erro é intencionalmente gerado pelos objetivos de compilação do Cosmos DB SDK para garantir que a dependência está devidamente configurada.

Solução para Aplicações:

Adicione uma referência explícita ao Newtonsoft.Json como mostrado na secção de Configuração Recomendada acima.

Solução para Bibliotecas:

Se estiver a construir uma biblioteca (não uma aplicação) e quiser adiar a dependência do Newtonsoft.Json para os consumidores da sua biblioteca, pode contornar esta verificação definindo a propriedade MSBuild no seu .csproj:

<PropertyGroup>
  <AzureCosmosDisableNewtonsoftJsonCheck>true</AzureCosmosDisableNewtonsoftJsonCheck>
</PropertyGroup>

Conflitos de Versões de Pacotes

Se encontrares erros de construção como:

error NU1109: Detected package downgrade: Newtonsoft.Json from 13.0.4 to centrally defined 13.0.3

Solution:

1. Identifique a versão necessária verificando quais os pacotes que necessitam de versões mais recentes:

   dotnet list package --include-transitive | Select-String "Newtonsoft.Json"
   

2. Atualize a versão do seu pacote centralizado para corresponder ou exceder a versão mais alta exigida:

   <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
   

3. Limpar e reconstruir:

   dotnet clean
   dotnet restore
   dotnet build
   

Compatibilidade de versões

A tabela seguinte mostra as versões seguras mínimas recomendadas do Newtonsoft.Json para cada versão do SDK do Cosmos DB. Embora o SDK possa tecnicamente funcionar com a versão 10.x, estas versões nunca devem ser usadas devido a vulnerabilidades de segurança.

Melhores práticas

• Adicione sempre como uma dependência direta – O SDK não gere automaticamente esta dependência por si
• Use a versão 13.0.3 ou superior - Nunca use a 10.x apesar da compatibilidade técnica, devido a vulnerabilidades de segurança conhecidas
• Exigido mesmo com System.Text.Json - Deve incluir Newtonsoft.Json mesmo ao usar , pois o SDK o usa internamente para tipos de sistema
• Define a versão explicitamente - Não confie na resolução de dependências transitivas
• Avisos de monitorização - Tratar os avisos de downgrade de pacotes NuGet (NU1109) como erros em pipelines CI/CD

Operações de consulta

Para operações de consulta, consulte as dicas de desempenho para consultas.

Política de indexação

Excluir os caminhos não utilizados da indexação para assegurar escritas mais rápidas

A política de indexação do Azure Cosmos DB também permite especificar quais caminhos de documentos devem ser incluídos ou excluídos da indexação, utilizando os caminhos de indexação IndexingPolicy.IncludedPaths e IndexingPolicy.ExcludedPaths.

A indexação apenas dos caminhos necessários pode melhorar o desempenho de gravação, reduzir as cobranças de RU em operações de gravação e reduzir o armazenamento de índice para cenários nos quais os padrões de consulta são conhecidos de antemão. Isso ocorre porque os custos de indexação se correlacionam diretamente com o número de caminhos exclusivos indexados. Por exemplo, o código a seguir mostra como excluir uma seção inteira dos documentos (uma subárvore) da indexação usando o curinga * :

var containerProperties = new ContainerProperties(id: "excludedPathCollection", partitionKeyPath: "/pk" );
containerProperties.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
containerProperties.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/nonIndexedContent/*");
Container container = await this.cosmosDatabase.CreateContainerAsync(containerProperties);

Para obter mais informações, consulte Políticas de indexação do Azure Cosmos DB.

Capacidade de processamento

Medida e afinação para menor utilização de RU/s

O Azure Cosmos DB oferece um conjunto avançado de operações de banco de dados. Essas operações incluem consultas relacionais e hierárquicas com funções definidas pelo usuário (UDFs), procedimentos armazenados e gatilhos, todos operando nos documentos dentro de uma coleção de banco de dados.

Os custos associados a cada uma dessas operações variam dependendo da CPU, E/S e memória necessárias para concluir a operação. Em vez de pensar e gerenciar recursos de hardware, você pode pensar em uma Unidade de Solicitação como uma única medida para os recursos necessários para executar várias operações de banco de dados e atender a uma solicitação de aplicativo.

A taxa de transferência é provisionada com base no número de Unidades de Solicitação definidas para cada contêiner. O consumo de RU é avaliado como uma taxa de unidades por segundo. Os aplicativos que excedem a taxa de RU provisionada para seu contêiner são limitados até que a taxa caia abaixo do nível provisionado para o contêiner. Se seu aplicativo exigir um nível mais alto de taxa de transferência, você poderá aumentar sua taxa de transferência provisionando mais RUs.

A complexidade de uma consulta afeta quantos RUs são consumidos para uma operação. O número de predicados, a natureza dos predicados, o número de arquivos UDF e o tamanho do conjunto de dados de origem influenciam o custo das operações de consulta.

Para medir a sobrecarga de qualquer operação (criar, atualizar ou excluir), inspecione o cabeçalho x-ms-request-charge (ou a propriedade equivalente RequestCharge no ResourceResponse<T>FeedResponse<T> SDK do .NET) para medir o número de RUs consumidas pelas operações:

// Measure the performance (Request Units) of writes
ItemResponse<Book> response = await container.CreateItemAsync<Book>(myBook, new PartitionKey(myBook.PkValue));
Console.WriteLine("Insert of item consumed {0} request units", response.RequestCharge);
// Measure the performance (Request Units) of queries
FeedIterator<Book> queryable = container.GetItemQueryIterator<ToDoActivity>(queryString);
while (queryable.HasMoreResults)
    {
        FeedResponse<Book> queryResponse = await queryable.ExecuteNextAsync<Book>();
        Console.WriteLine("Query batch consumed {0} request units", queryResponse.RequestCharge);
    }

A cobrança de solicitação retornada neste cabeçalho é uma fração da taxa de transferência provisionada (ou seja, 2.000 RU/s). Por exemplo, se a consulta anterior retornar 1.000 documentos de 1 KB, o custo da operação será 1.000. Assim, dentro de um segundo, o servidor atende apenas duas dessas solicitações antes de limitar as solicitações posteriores. Para obter mais informações, consulte Unidades de Solicitação e a Calculadora de Unidades de Solicitação.

Lidar com limitação de taxa / taxa de solicitação muito grande

Quando um cliente tenta exceder a taxa de transferência reservada para uma conta, não há degradação de desempenho no servidor e nenhum uso da capacidade de taxa de transferência além do nível reservado. O servidor termina preventivamente a solicitação com RequestRateTooLarge (código de status HTTP 429). Ele retorna um cabeçalho x-ms-retry-after-ms que indica a quantidade de tempo, em milissegundos, que o usuário deve aguardar antes de tentar a solicitação novamente.

    HTTP Status 429,
    Status Line: RequestRateTooLarge
    x-ms-retry-after-ms :100

Todos os SDKs capturam implicitamente essa resposta, respeitam o cabeçalho retry-after especificado pelo servidor e tentam novamente a solicitação. A menos que sua conta esteja sendo acessada simultaneamente por vários clientes, a próxima tentativa será bem-sucedida.

Se você tiver mais de um cliente operando cumulativamente acima da taxa de solicitação, a contagem de tentativas padrão definida atualmente como 9 internamente pelo cliente pode não ser suficiente. Nesse caso, o cliente lança um CosmosException com o código de status 429 para o aplicativo.

Você pode alterar a contagem de repetições padrão definindo o RetryOptions na instância de CosmosClientOptions. Por padrão, o CosmosException com o código de status 429 é retornado após um tempo de espera cumulativo de 30 segundos se a solicitação continuar a operar acima da taxa de solicitação. Esse erro é retornado mesmo quando a contagem de tentativas atual é menor do que a contagem máxima de tentativas, quer o valor atual seja o padrão de 9 ou um valor definido pelo usuário.

O comportamento de repetição automatizada ajuda a melhorar a resiliência e a usabilidade para a maioria dos aplicativos. Mas pode não ser o melhor comportamento quando você está fazendo benchmarks de desempenho, especialmente quando você está medindo a latência. A latência observada pelo cliente aumentará se o experimento atingir o limite do servidor e fizer com que o SDK do cliente tente novamente de forma silenciosa. Para evitar picos de latência durante experimentos de desempenho, meça a carga retornada por cada operação e verifique se as solicitações estão operando abaixo da taxa de solicitação reservada.

Para obter mais informações, consulte Unidades de Pedido.

Para maior taxa de transferência, projete para documentos menores

A taxa de solicitação (ou seja, o custo de processamento da solicitação) de uma operação especificada está diretamente correlacionada ao tamanho do documento. As operações em documentos grandes custam mais do que as operações em documentos pequenos.

Próximos passos

• Meça o desempenho do Azure Cosmos DB para NoSQL com uma estrutura de benchmarking
• Criação de partições e dimensionamento horizontal no Azure Cosmos DB