Azure Cosmos DB .NET SDK v3 for API for NoSQL: Download e notas de versão

APLICA-SE A: NoSQL

Histórico de versões

O histórico de lançamento é mantido no repositório de origem do Azure Cosmos DB .NET SDK. Para obter uma lista detalhada das versões de recursos e bugs corrigidos em cada versão, consulte a documentação do changelog do SDK

Versão recomendada

Diferentes subversões de SDKs .NET estão disponíveis na versão 3.x.x. A versão mínima recomendada é 3.47.0.

Problemas conhecidos

Para obter uma lista de problemas conhecidos com a versão mínima recomendada do SDK, consulte a seção Problemas conhecidos.

Gestão das Dependências do Newtonsoft.Json

Visão geral

O Azure Cosmos DB .NET SDK tem uma dependência para Newtonsoft.Json 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 projetos .csproj padrão

<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 alvos de compilação do SDK da base de dados Cosmos 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 UseSystemTextJsonSerializerWithOptions, pois o SDK usa internamente para tipos de sistema
• Fixa a versão explicitamente - Não confies 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

FAQ

Como vou ser notificado do SDK descontinuado?

A Microsoft dará um aviso com 12 meses de antecedência antes do fim de suporte do SDK descontinuado para permitir uma transição suave para um SDK suportado. Será notificado através de vários canais de comunicação: o portal do Azure, as atualizações do Azure e através de comunicação direta com os administradores atribuídos aos serviços.

Posso criar aplicações com um SDK do Azure Cosmos DB que vai ser descontinuado durante o período de 12 meses?

Sim, poderá criar, implementar e modificar aplicações com o SDK do Azure Cosmos DB que vai ser descontinuado durante o período de aviso de 12 meses. Recomendamos que migre para uma versão suportada mais recente do SDK do Azure Cosmos DB durante o período de aviso de 12 meses, conforme adequado.

Após a data da descontinuação, o que acontece às aplicações que utilizam o SDK do Azure Cosmos DB não suportado?

Após a data de descontinuação, o Azure Cosmos DB deixará de fazer correções de erros, adicionar funcionalidades novas e fornecer suporte às versões descontinuadas do SDK. Se preferir não atualizar, o serviço Azure Cosmos DB continua a servir os pedidos enviados das versões descontinuadas do SDK.

Que versões do SDK terão as mais recentes funcionalidades e atualizações?

As funcionalidades e atualizações novas só vão ser adicionadas à última versão menor da última grande versão do SDK. Recomendamos que utilize sempre a última versão para tirar partido das funcionalidades, das melhorias ao desempenho e das correções de erro mais recentes. Se estiver a utilizar uma versão antiga e ainda em uso do SDK, os pedidos ao Azure Cosmos DB continuarão a funcionar, mas não terá acesso a nenhuma capacidade nova.

O que devo fazer se não conseguir atualizar a minha aplicação antes da data de descontinuação?

Recomendamos que atualize para o último SDK o mais cedo possível. Quando um SDK é marcado para descontinuação, tem 12 meses para atualizar a sua aplicação. Se não conseguir atualizar até à data de descontinuação, os pedidos enviados das versões descontinuadas do SDK continuam a ser servidos pelo Azure Cosmos DB, pelo que as aplicações em execução continuam a funcionar. Contudo, o Azure Cosmos DB deixará de fazer correções de erros, adicionar funcionalidades novas e fornecer suporte às versões descontinuadas do SDK.

Se tiver um plano de suporte e precisar de suporte técnico, preencha um pedido de suporte para nos contactar.

Como posso solicitar que os recursos sejam adicionados a um SDK ou conector?

Novos recursos nem sempre são adicionados a cada SDK ou conector imediatamente. Se houver um recurso não suportado que você gostaria de adicionar, por favor, adicione comentários ao nosso fórum da comunidade.

Consulte também

Para saber mais sobre o Azure Cosmos DB, consulte a página do serviço Microsoft Azure Cosmos DB .