Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
APPLIES TO: 
NoSQL
| Links | |
|---|---|
| Release notes | Release notes |
| SDK download | NuGet |
| API documentation | .NET API reference documentation |
| Samples | .NET code samples |
| Get started | Get started with the Azure Cosmos DB .NET SDK |
| Best Practices | Best Practices for Azure Cosmos DB .NET SDK |
| Entity Framework Core tutorial | Entity Framework Core with Azure Cosmos DB Provider |
| Current supported framework | Microsoft .NET Standard 2.0 |
Release history
Release history is maintained in the Azure Cosmos DB .NET SDK source repo. For a detailed list of feature releases and bugs fixed in each release, see the SDK changelog documentation
Recommended version
Different sub versions of .NET SDKs are available under the 3.x.x version. The minimum recommended version is 3.47.0.
Known issues
For a list of known issues with the recommended minimum version of the SDK, see known issues section.
Managing Newtonsoft.Json Dependencies
Overview
The Azure Cosmos DB .NET SDK has a dependency on Newtonsoft.Json for JSON serialization operations. This dependency is not managed automatically - you must explicitly add Newtonsoft.Json as a direct dependency in your project.
The SDK compiles against Newtonsoft.Json 10.x internally, which has a known security vulnerability. While the SDK is technically compatible with 10.x, and the SDK's usage of Newtonsoft.Json is not susceptible to the reported security issue, we still recommend using version 13.0.3 or higher to avoid potential security issues or conflicts. The 13.x versions include breaking changes, but the SDK's usage patterns are compatible with these changes.
Important
This dependency is required even when using System.Text.Json for user-defined types via CosmosClientOptions.UseSystemTextJsonSerializerWithOptions, because the SDK's internal operations still use Newtonsoft.Json for system types.
Recommended Configuration
Always explicitly add Newtonsoft.Json version 13.0.3 or higher as a direct dependency when using the Azure Cosmos DB .NET SDK v3. Do not use version 10.x due to known security vulnerabilities.
For Standard .csproj Projects
<ItemGroup>
<PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
<PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>
For Projects Using Central Package Management
If your project uses Directory.Packages.props:
<Project>
<ItemGroup>
<PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
<PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>
</Project>
Troubleshooting Version Conflicts
Missing Newtonsoft.Json Reference
If you encounter a build error like:
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.
This error is intentionally generated by the Cosmos DB SDK's build targets to ensure the dependency is properly configured.
Solution for Applications:
Add an explicit reference to Newtonsoft.Json as shown in the Recommended Configuration section above.
Solution for Libraries:
If you're building a library (not an application) and want to defer the Newtonsoft.Json dependency to your library's consumers, you can bypass this check by setting the MSBuild property in your .csproj:
<PropertyGroup>
<AzureCosmosDisableNewtonsoftJsonCheck>true</AzureCosmosDisableNewtonsoftJsonCheck>
</PropertyGroup>
Warning
Only use this bypass when building libraries where end users will provide the Newtonsoft.Json dependency. For applications, always add the explicit reference.
Package Version Conflicts
If you encounter build errors like:
error NU1109: Detected package downgrade: Newtonsoft.Json from 13.0.4 to centrally defined 13.0.3
Solution:
Identify the required version by checking which packages need newer versions:
dotnet list package --include-transitive | Select-String "Newtonsoft.Json"Update your centralized package version to match or exceed the highest required version:
<PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />Clean and rebuild:
dotnet clean dotnet restore dotnet build
Version Compatibility
The following table shows the minimum recommended secure versions of Newtonsoft.Json for each Cosmos DB SDK version. While the SDK can technically work with 10.x, these versions should never be used due to security vulnerabilities.
| Cosmos DB SDK Version | Minimum Secure Version | Recommended |
|---|---|---|
| 3.47.0+ | 13.0.3 | 13.0.4 |
| 3.54.0+ | 13.0.4 | 13.0.4 |
Tip
When using .NET Aspire 13.0.0 or later, ensure Newtonsoft.Json is at version 13.0.4 to avoid conflicts with Aspire's Azure components.
Best Practices
- Always add as a direct dependency - The SDK does not automatically manage this dependency for you
- Use version 13.0.3 or higher - Never use 10.x despite technical compatibility, due to known security vulnerabilities
- Required even with System.Text.Json - You must include Newtonsoft.Json even when using
UseSystemTextJsonSerializerWithOptions, as the SDK uses it internally for system types - Pin the version explicitly - Don't rely on transitive dependency resolution
- Monitor warnings - Treat NuGet package downgrade warnings (NU1109) as errors in CI/CD pipelines
FAQ
How will I be notified of the retiring SDK?
Microsoft will provide 12 month's advance notice before the end of support of the retiring SDK to facilitate a smooth transition to a supported SDK. We'll notify you through various communication channels: the Azure portal, Azure updates, and direct communication to assigned service administrators.
Can I author applications by using a to-be-retired Azure Cosmos DB SDK during the 12-month period?
Yes, you'll be able to author, deploy, and modify applications by using the to-be-retired Azure Cosmos DB SDK during the 12-month notice period. We recommend that you migrate to a newer supported version of the Azure Cosmos DB SDK during the 12-month notice period, as appropriate.
After the retirement date, what happens to applications that use the unsupported Azure Cosmos DB SDK?
After the retirement date, Azure Cosmos DB will no longer make bug fixes, add new features, or provide support to the retired SDK versions. If you prefer not to upgrade, requests sent from the retired versions of the SDK will continue to be served by the Azure Cosmos DB service.
Which SDK versions will have the latest features and updates?
New features and updates will be added only to the latest minor version of the latest supported major SDK version. We recommend that you always use the latest version to take advantage of new features, performance improvements, and bug fixes. If you're using an old, non-retired version of the SDK, your requests to Azure Cosmos DB will still function, but you won't have access to any new capabilities.
What should I do if I can't update my application before a cutoff date?
We recommend that you upgrade to the latest SDK as early as possible. After an SDK is tagged for retirement, you'll have 12 months to update your application. If you're not able to update by the retirement date, requests sent from the retired versions of the SDK will continue to be served by Azure Cosmos DB, so your running applications will continue to function. But Azure Cosmos DB will no longer make bug fixes, add new features, or provide support to the retired SDK versions.
If you have a support plan and require technical support, contact us by filing a support ticket.
How can I request features be added to an SDK or connector?
New features are not always added to every SDK or connector immediately. If there is a feature not supported that you would like added, please add feedback to our community forum.
See also
To learn more about Azure Cosmos DB, see Microsoft Azure Cosmos DB service page.