Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
| Links | |
|---|---|
| Notas de lançamento | Notas de lançamento |
| Transferência de SDK | NuGet |
| Documentação da API | Documentação de referência da API .NET |
| Amostras | Exemplos de código .NET |
| Introdução | Introdução ao SDK .NET do Azure Cosmos DB |
| Boas Práticas | Práticas recomendadas para o Azure Cosmos DB .NET SDK |
| Tutorial do Entity Framework Core | Entity Framework Core com o Azure Cosmos DB Provider |
| Framework suportado atualmente | Microsoft .NET Padrão 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
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
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.
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>
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:
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"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" />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 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
FAQ
Como vou ser notificado do SDK descontinuado?
A Microsoft fornecerá um aviso prévio de 12 meses antes do fim do suporte do SDK que está a ser retirado para facilitar uma transição suave para um SDK suportado. Notificaremos através de vários canais de comunicação: o portal Azure, atualizações do Azure e comunicação direta com os administradores de serviço atribuídos.
Posso criar candidaturas usando um SDK de Azure Cosmos DB to-bereformado durante o período de 12 meses?
Sim, poderá criar, implementar e modificar aplicações usando o SDK Azure Cosmos DB to-be- retirado 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 reforma, o que acontece às aplicações que utilizam o SDK de Azure Cosmos DB não suportado?
Após a data de reforma, o Azure Cosmos DB deixará de corrigir bugs, adicionar novas funcionalidades nem fornecer suporte às versões do SDK retiradas. Se preferir não atualizar, os pedidos enviados pelas versões desativadas do SDK continuarão a ser servidos pelo serviço Azure Cosmos DB.
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 estiveres a usar uma versão antiga e não desativada do SDK, os teus pedidos para o Azure Cosmos DB continuarão a funcionar, mas não terás acesso a novas funcionalidades.
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 reforma, os pedidos enviados das versões desativadas do SDK continuarão a ser servidos pelo Azure Cosmos DB, pelo que as suas aplicações em execução continuarão a funcionar. Mas o Azure Cosmos DB já não fará correções de bugs, adiciona novas funcionalidades nem fornece suporte às versões do SDK retiradas.
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 Azure Cosmos DB, consulte a página de serviço Microsoft Azure Cosmos DB.