你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
适用范围：
NoSQL
| 链接 | |
|---|---|
| 发行说明 | 发行说明 |
| SDK 下载 | NuGet |
| API 文档 | 参考文档 |
| 示例 | .NET代码示例 |
| 入门 | Azure Cosmos DB .NET SDK 入门 |
| 最佳实践 | Azure Cosmos DB .NET SDK 的最佳做法 |
| Entity Framework Core 教程 | Entity Framework Core 与 Azure Cosmos DB 提供程序 |
| 当前受支持的框架 | Microsoft .NET Standard 2.0 |
版本历史记录
版本历史记录保留在 Azure Cosmos DB .NET SDK 源存储库中。 有关每个版本中功能发布和修复的 bug 的详细列表，请参阅 SDK 更改日志文档
建议的版本
3\.x.x 版本下支持 .NET SDK 的不同子版本。 建议的最低版本为 3.47.0。
已知问题
有关最低建议版本的 SDK 的已知问题列表，请参阅已知问题部分。
管理 Newtonsoft.Json 依赖项
概述
Azure Cosmos DB .NET SDK Newtonsoft.Json 依赖于 JSON 序列化作。
此依赖项不会自动管理 - 必须在项目中显式添加 Newtonsoft.Json 为直接依赖项。
SDK 在内部针对 Newtonsoft.Json 10.x 进行编译，该 SDK 具有已知的安全漏洞。 虽然 SDK 在技术上与 10.x 兼容，但 SDK 对 Newtonsoft.Json 的使用并不容易受到报告安全问题的影响，但仍 建议使用版本 13.0.3 或更高版本 来避免潜在的安全问题或冲突。 13.x 版本包括中断性变更，但 SDK 的使用模式与这些更改兼容。
重要
即使通过 CosmosClientOptions.UseSystemTextJsonSerializerWithOptions 使用System.Text.Json用户定义的类型，也需要此依赖项，因为 SDK 的内部作仍对系统类型使用 Newtonsoft.Json。
建议的配置
使用 Azure Cosmos DB .NET SDK v3 时，始终将版本 13.0.3 或更高版本显式添加Newtonsoft.Json为直接依赖项。 由于已知的安全漏洞，请勿使用版本 10.x。
对于标准 .csproj 项目
<ItemGroup>
<PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
<PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>
对于使用中央包管理的项目
如果项目使用 Directory.Packages.props：
<Project>
<ItemGroup>
<PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
<PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>
</Project>
版本冲突疑难解答
缺少 Newtonsoft.Json 参考
如果遇到生成错误，例如：
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.
此错误是由 Cosmos DB SDK 的生成目标有意生成的，以确保正确配置依赖项。
应用程序解决方案：
添加对 Newtonsoft.Json 的显式引用，如上面的 “建议配置” 部分所示。
库解决方案：
如果要生成库（而不是应用程序），并且想要将 Newtonsoft.Json 依赖项延迟到库的使用者，可以通过在以下项 .csproj中设置 MSBuild 属性来绕过此检查：
<PropertyGroup>
<AzureCosmosDisableNewtonsoftJsonCheck>true</AzureCosmosDisableNewtonsoftJsonCheck>
</PropertyGroup>
警告
仅当生成最终用户将提供 Newtonsoft.Json 依赖项的库时，才使用此绕过。 对于应用程序，请始终添加显式引用。
包版本冲突
如果遇到生成错误，例如：
error NU1109: Detected package downgrade: Newtonsoft.Json from 13.0.4 to centrally defined 13.0.3
Solution:
通过检查哪些包需要较新版本来确定所需的版本：
dotnet list package --include-transitive | Select-String "Newtonsoft.Json"更新集中式包版本 以匹配或超过所需的最高版本：
<PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />清理并重新生成：
dotnet clean dotnet restore dotnet build
版本兼容性
下表显示了每个 Cosmos DB SDK 版本的 Newtonsoft.Json 的最低建议安全版本 。 虽然 SDK 在技术上可与 10.x 配合使用，但由于安全漏洞，不应使用这些版本。
| Cosmos DB SDK 版本 | 最低安全版本 | Recommended |
|---|---|---|
| 3.47.0+ | 13.0.3 | 13.0.4 |
| 3.54.0+ | 13.0.4 | 13.0.4 |
小窍门
使用 .NET Aspire 13.0.0 或更高版本时，请确保 Newtonsoft.Json 版本为 13.0.4，以避免与 Aspire 的 Azure 组件冲突。
最佳做法
- 始终添加为直接依赖项 - SDK 不会自动为你管理此依赖项
- 使用版本 13.0.3 或更高版本 - 由于已知的安全漏洞，请勿使用 10.x，尽管技术兼容性
-
即使 System.Text.Json 是必需的 - 即使使用
UseSystemTextJsonSerializerWithOptionsNewtonsoft.Json，也必须包括 Newtonsoft.Json，因为 SDK 在内部使用它用于系统类型 - 显式固定版本 - 不要依赖于可传递依赖项解析
- 监视警告 - 将 NuGet 包降级警告 （NU1109） 视为 CI/CD 管道中的错误
FAQ
如何收到即将停用的 SDK 的通知？
Microsoft 会在即将停用的 SDK 的支持结束之前提前 12 个月进行通知，以便协助平稳地转换到支持的 SDK。 我们会通过以下通信通道通知你：Azure 门户、Azure 更新以及与分配的服务管理员的直接通信。
在这 12 个月期间，我是否可以使用即将停用的 Azure Cosmos DB SDK 来创作应用程序？
可以，你可以在 12 个月的宽限期内使用即将停用的 Azure Cosmos DB SDK 创作、部署和修改应用程序。 建议在 12 个月的宽限期内根据相应情况迁移到支持的较新版本 Azure Cosmos DB SDK。
停用日期之后，使用不受支持的 Azure Cosmos DB SDK 的应用程序会发生什么情况？
停用日期之后，Azure Cosmos DB 将不再进行 bug 修复、添加新功能或为已停用的 SDK 版本提供支持。 如果不想升级，从已停用的 SDK 版本发送的请求将继续由 Azure Cosmos DB 服务提供服务。
哪些 SDK 版本将包含最新功能和更新？
新功能和更新将仅添加到最新的受支持的主要 SDK 版本的最新次要版本。 建议始终使用最新版本，以充分利用新功能、性能改进和 bug 修补程序。 如果使用的是未停用的旧版本 SDK，则对 Azure Cosmos DB 进行的请求仍然有效，但是你无法访问任何新功能。
如果无法在截止日期之前更新应用程序，该怎么办？
我们建议尽早升级到最新 SDK。 SDK 标记为要停用之后，你将有 12 个月的时间来更新应用程序。 如果无法在停用日期之前更新，从已停用的 SDK 版本发送的请求将继续由 Azure Cosmos DB 提供服务，因此正在运行的应用程序将继续运行。 但 Azure Cosmos DB 将不再进行 bug 修复、添加新功能或为已停用的 SDK 版本提供支持。
如果你有支持计划并需要技术支持，请创建支持工单以联系我们。
如何请求将功能添加到 SDK 或连接器？
新功能并不总是立即添加到每个 SDK 或连接器中。 如果你想添加的功能不受支持，请在我们的社区论坛提出反馈。
另请参阅
若要详细了解 Azure Cosmos DB，请参阅 Microsoft Azure Cosmos DB 服务页。