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

Links
Notas de lançamento Notas de lançamento
Download do SDK NuGet
Documentação da API Documentação de referência da API .NET
Exemplos Exemplos de código .NET
Comece Comece com o SDK Azure Cosmos DB .NET
Melhores Práticas Boas práticas para Azure Cosmos DB .NET SDK
Tutorial do Entity Framework Core Entity Framework Core com Azure Cosmos DB Provider
Framework atualmente suportado Microsoft .NET Standard 2.0

Histórico de lançamentos

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.

Para a versão mínima recomendada Azure Cosmos DB .NET SDK, consulte a secção Versão Recomendada do registo de alterações do SDK. Use a versão recomendada ou posterior para incluir todas as correções críticas.

Problemas conhecidos

Para uma lista de problemas conhecidos com a versão mínima recomendada do SDK, consulte a secção Problemas Conhecidos do registo de alterações do SDK.

Gestão das Dependências do Newtonsoft.Json

Overview

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.

Importante

Esta dependência é necessária mesmo quando usada System.Text.Json para tipos definidos pelo utilizador via CosmosClientOptions.UseSystemTextJsonSerializerWithOptions, porque as operações internas do SDK continuam a usar Newtonsoft.Json para tipos de sistema.

Adicione Newtonsoft.Json sempre explicitamente a versão 13.0.3 ou superior como uma dependência direta ao usar o SDK Azure Cosmos DB .NET 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="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="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>

Warning

Use este bypass apenas ao construir bibliotecas onde os utilizadores finais fornecerão a dependência Newtonsoft.Json. Para aplicações, adicione sempre a referência explícita.

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 centralizada do seu pacote 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.

Versão SDK do Cosmos DB Versão Mínima Segura Recommended
3.47.0+ 13.0.3 13.0.4
3.54.0+ 13.0.4 13.0.4

Tip

Ao usar o .NET Aspire 13.0.0 ou posterior, certifique-se Newtonsoft.Json que está na versão 13.0.4 para evitar conflitos com os componentes Azure do Aspire.

Melhores práticas

  • Adicione sempre como 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
  • Necessário mesmo com System.Text.Json - Deve incluir Newtonsoft.Json mesmo ao utilizar UseSystemTextJsonSerializerWithOptions, pois o SDK o utiliza internamente para tipos de sistema
  • Fixar explicitamente a versão - Não confie na resolução transitiva de dependências
  • Monitorizar avisos - Tratar os avisos de downgrade de pacotes NuGet (NU1109) como erros em pipelines CI/CD

FAQ

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

A Microsoft fornece um aviso prévio de 12 meses antes do fim do suporte para o SDK que está a ser retirado, para o ajudar a fazer uma transição fluida para um SDK suportado. Recebe notificações através destes canais de comunicação: o portal Azure, atualizações do Azure e comunicação direta aos administradores de serviço designados.

Posso criar aplicações utilizando um SDK de Azure Cosmos DB to-bedescontinuado durante o período de 12 meses?

Sim, pode utilizar o SDK de Azure Cosmos DB to-bedescontinuado para criar, implementar e modificar aplicações durante o período de aviso prévio de 12 meses. Recomendamos que migre para uma versão mais recente suportada do Azure Cosmos DB SDK durante o período de aviso prévio de 12 meses, conforme apropriado.

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

Após a data de aposentação, o Azure Cosmos DB deixa de fazer correções de erros, não adiciona novas funcionalidades nem oferece suporte para as versões do SDK descontinuadas. Se optar por não atualizar, o Azure Cosmos DB continua a servir pedidos enviados a partir das versões desativadas do SDK.

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

Novas funcionalidades e atualizações são adicionadas apenas à versão menor mais recente da versão principal mais recente do SDK suportada. 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 usar uma versão antiga e não descontinuada do SDK, os seus pedidos para o Azure Cosmos DB continuam a funcionar, mas não tem acesso a novas funcionalidades.

O que devo fazer se não puder atualizar a minha candidatura antes de uma data limite?

Recomendamos que atualize para o último SDK o mais cedo possível. Depois de um SDK ser marcado para aposentação, tem 12 meses para atualizar a sua candidatura. Se não conseguir atualizar até à data de aposentação, o Azure Cosmos DB continua a servir pedidos enviados pelas versões desativadas do SDK, pelo que as suas aplicações em execução continuam a funcionar. Mas o Azure Cosmos DB já não faz correções de erros, adiciona novas funcionalidades nem oferece suporte para as versões do SDK desativadas.

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

Como posso pedir que funcionalidades sejam adicionadas a um SDK ou conetor?

As novas funcionalidades nem sempre são adicionadas imediatamente a cada SDK ou conetor. Se houver alguma funcionalidade que não seja suportada e que queira ser adicionada, adicione feedback ao nosso fórum comunitário.