SDK do .NET do Azure Cosmos DB v3 para a API para NoSQL: download e notas sobre a versão

APLICA-SE A: NoSQL

Histórico de versões

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

Versão recomendada

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

Problemas conhecidos

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

Gerenciando dependências newtonsoft.json

Visão geral

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

O SDK é compilado internamente no Newtonsoft.Json 10.x, que tem uma vulnerabilidade de segurança conhecida. Embora o SDK seja tecnicamente compatível com o 10.x e o uso do SDK do Newtonsoft.Json não seja suscetível ao problema de segurança relatado, ainda recomendamos usar a versão 13.0.3 ou superior para evitar possíveis problemas de segurança ou conflitos. As versões 13.x incluem alterações significativas, mas os padrões de uso do SDK são compatíveis com essas alterações.

Configuração recomendada

Sempre adicione Newtonsoft.Json explicitamente a versão 13.0.3 ou superior como uma dependência direta ao usar o SDK do .NET do Azure Cosmos DB 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 usam o Gerenciamento Central de Pacotes

Se o 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>

Solução de problemas de conflitos de versão

Referência de Newtonsoft.Json ausente

Se você encontrar um erro de build 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.

Esse erro é gerado intencionalmente pelos destinos de build do SDK do Cosmos DB para garantir que a dependência esteja configurada corretamente.

Solução para aplicativos:

Adicione uma referência explícita a Newtonsoft.Json, conforme mostrado na seção Configuração Recomendada acima.

Solução para bibliotecas:

Se você estiver criando uma biblioteca (não um aplicativo) e quiser adiar a dependência Newtonsoft.Json para os consumidores da biblioteca, poderá ignorar essa verificação definindo a propriedade MSBuild em seu .csproj:

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

Conflitos de versão do pacote

Se você encontrar erros de build 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 pacotes precisam de versões mais recentes:

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

2. Atualize sua versão centralizada do pacote para corresponder ou exceder a versão mais alta necessária:

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

3. Limpar e recompilar:

   dotnet clean
   dotnet restore
   dotnet build
   

Compatibilidade de versão

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

Práticas recomendadas

• Sempre adicione como uma dependência direta – o SDK não gerencia automaticamente essa dependência para você
• Usar a versão 13.0.3 ou superior – nunca use 10.x apesar da compatibilidade técnica, devido a vulnerabilidades de segurança conhecidas
• Obrigatório mesmo com System.Text.Json – Você deve incluir Newtonsoft.Json mesmo ao usar UseSystemTextJsonSerializerWithOptions, já que o SDK o usa internamente para tipos de sistema
• Fixar a versão explicitamente – não depender da resolução de dependência transitiva
• Monitorar avisos – Tratar avisos de downgrade do pacote NuGet (NU1109) como erros em pipelines de CI/CD

perguntas frequentes

Como serei notificado sobre a desativação do SDK?

A Microsoft enviará uma notificação com 12 meses de antecedência informando sobre o fim do suporte para o SDK a ser desativado, para facilitar uma transição suave para um SDK com suporte. Você será notificado por meio de vários canais de comunicação: o portal do Azure, as atualizações do Azure e a comunicação direta com os administradores de serviços atribuídos.

Durante o período de 12 meses, posso criar aplicativos usando um SDK do Azure Cosmos DB que será desativado?

Sim, durante o período de notificação de 12 meses, você poderá criar, implantar e modificar aplicativos usando o SDK do Azure Cosmos DB que será desativado. Recomendamos que você migre para uma versão do SDK do Azure Cosmos DB mais recente com suporte durante o período de notificação de 12 meses, conforme o necessário.

Após a data de desativação, o que acontece com os aplicativos que usam o SDK do Azure Cosmos DB sem suporte?

Após a data de desativação, o Azure Cosmos DB não fará mais correções de bug, não adicionará novos recursos nem dará suporte às versões desativadas do SDK. Se você preferir não fazer a atualização, as solicitações enviadas das versões desativadas do SDK continuarão sendo atendidas pelo serviço Azure Cosmos DB.

Quais versões do SDK terão os recursos e as atualizações mais recentes?

Os novos recursos e atualizações serão adicionados somente à última versão secundária da última versão principal do SDK com suporte. Recomendamos que você sempre use a última versão para aproveitar os novos recursos, os aprimoramentos de desempenho e as correções de bug. Se você estiver usando uma versão antiga e não desativada do SDK, suas solicitações para o Azure Cosmos DB continuarão a funcionar, mas você não terá acesso a nenhuma funcionalidade nova.

O que fazer se eu não conseguir atualizar meu aplicativo antes da data limite?

Recomendamos atualizar o mais rápido possível para o SDK mais recente. Depois que um SDK for marcado para desativação, você terá 12 meses para atualizar seu aplicativo. Se você não conseguir fazer a atualização até data de desativação, as solicitações enviadas das versões desativadas do SDK continuarão a ser atendidas pelo Azure Cosmos DB, para que os aplicativos em execução continuem a funcionar. No entanto, o Azure Cosmos DB não fará mais correções de bug, não adicionará novos recursos nem dará suporte às versões desativadas do SDK.

Se você tem um plano de suporte e precisa de suporte técnico, entre em contato conosco abrindo um tíquete de suporte.

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

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

Confira também

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