Пакет SDK для .NET для Azure Cosmos DB версии 3 для API для NoSQL: скачивание и заметки о выпуске

Применяется к: ✅ NoSQL

	Links
Заметки о выпуске	Заметки о выпуске
Скачивание пакета SDK	NuGet
Документация по API	Справочная документация по API .NET
Образцы	Примеры кода для .NET
Начало работы	Azure Cosmos DB. Приступая к работе с API DocumentDB
Рекомендации	Рекомендации по использованию пакета SDK .NET для Azure Cosmos DB
Учебник по Entity Framework Core	Entity Framework Core с поставщиком БД Azure Cosmos
Текущая поддерживаемая платформа	Microsoft .NET Standard 2.0

История выпусков

История выпусков хранится в исходном репозитории пакета SDK .NET для Azure Cosmos DB. Подробный список выпусков с новыми функциями и ошибок, устраненных в каждом выпуске, см. в документации журнала изменений SDK.

Известные проблемы

Список известных проблем с рекомендуемой минимальной версией SDK см. в разделе Известные проблемы.

Управление зависимостями Newtonsoft.Json

Overview

Пакет SDK для .NET для Azure Cosmos DB для операций сериализации JSON зависит от Newtonsoft.Json. Эта зависимость не управляется автоматически — необходимо явно добавить Newtonsoft.Json как прямую зависимость в ваш проект.

Пакет SDK компилируется в Newtonsoft.Json 10.x внутри системы, которая имеет известную уязвимость безопасности. Хотя пакет SDK технически совместим с 10.x, а использование пакета SDK Newtonsoft.Json не подвержено обнаруженной проблеме безопасности, мы по-прежнему рекомендуем использовать версию 13.0.3 или более позднюю , чтобы избежать потенциальных проблем безопасности или конфликтов. Версии 13.x включают критические изменения, но шаблоны использования пакета SDK совместимы с этими изменениями.

Important

Эта зависимость требуется даже при использовании System.Text.Json для определяемых пользователем типов через CosmosClientOptions.UseSystemTextJsonSerializerWithOptions, так как внутренние операции пакета SDK по-прежнему используют Newtonsoft.Json для системных типов.

Устранение проблем конфликтов версий

Отсутствует ссылка на 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.

Эта ошибка намеренно создается целевыми объектами сборки пакета SDK Cosmos DB для обеспечения правильной настройки зависимостей.

Решение для приложений:

Добавьте явную ссылку на Newtonsoft.Json, как показано в разделе рекомендуемой конфигурации выше.

Решение для библиотек:

Если вы создаете библиотеку (не приложение) и хотите перенести зависимость Newtonsoft.Json на пользователей вашей библиотеки, это можно обойти, задав свойство MSBuild в вашем .csproj:

<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
```

Совместимость версий

В следующей таблице показаны минимальные рекомендуемые безопасные версии Newtonsoft.Json для каждой версии пакета SDK Cosmos DB. Хотя пакет SDK может технически работать с 10.x, эти версии никогда не должны использоваться из-за уязвимостей безопасности.

Версия пакета SDK Cosmos DB	Минимальная безопасная версия	Рекомендуется
3.47.0+	13.0.3	13.0.4
3.54.0+	13.0.4	13.0.4

Tip

При использовании .NET Aspire 13.0.0 или более поздней, убедитесь, что Aspire Newtonsoft.Json имеет версию 13.0.4, чтобы избежать конфликтов с компонентами Azure.

Лучшие практики

Всегда добавляйте как прямую зависимость. Пакет SDK не управляет этой зависимостью автоматически.
Используйте версию 13.0.3 или более поздней. Никогда не используйте 10.x , несмотря на техническую совместимость, из-за известных уязвимостей безопасности
Обязательный даже при использовании System.Text.Json — вы должны включить Newtonsoft.Json даже при использовании UseSystemTextJsonSerializerWithOptions, так как пакет SDK использует его внутренне для системных типов.
Закрепите версию явным образом . Не полагаться на разрешение транзитивной зависимости
Предупреждения мониторинга - Обработайте предупреждения о понижении уровня пакета NuGet (NU1109) как ошибки в конвейерах CI/CD

FAQ

Как меня уведомят о прекращении поддержки пакета SDK?

Microsoft предоставьте предварительное уведомление 12 месяцев до окончания поддержки пакета SDK для выхода на пенсию, чтобы упростить переход на поддерживаемый пакет SDK. Мы уведомим вас через различные каналы коммуникации: портал Azure, обновления Azure и прямой обмен данными с назначенными администраторами служб.

Can I author application by using a to-be-retired Azure Cosmos DB SDK в течение 12-месячного периода?

Да, вы сможете создавать, развертывать и изменять приложения с помощью пакета SDK Azure Cosmos DB to-beв течение 12-месячного периода уведомления. Рекомендуется перейти на более новую поддерживаемую версию пакета SDK Azure Cosmos DB в течение 12-месячного периода уведомления.

После даты выхода на пенсию приложения, использующие неподдерживаемый пакет SDK для Azure Cosmos DB?

После даты выхода на пенсию Azure Cosmos DB больше не исправлять ошибки, добавлять новые функции или предоставлять поддержку устаревших версий пакета SDK. Если вы предпочитаете не обновлять, запросы, отправляемые из устаревших версий пакета SDK, будут по-прежнему обслуживаться службой Azure Cosmos DB.

Какие версии пакета SDK получат последние функции и обновления?

Новые функции и обновления получит только последняя дополнительная версия последней основной поддерживаемой версии пакета SDK. Мы рекомендуем всегда работать с последней версией, чтобы вы имели доступ к новым функциям, улучшениям производительности и исправлениям ошибок. Если вы используете старую, не удаляемую версию пакета SDK, ваши запросы на Azure Cosmos DB по-прежнему будут работать, но у вас нет доступа к новым возможностям.

Что делать, если не удается обновить приложение до даты прекращения поддержки?

Рекомендуется как можно раньше выполнить обновление до последней версии SDK. После уведомления о том, что поддержка пакета SDK будет прекращена, у вас будет 12 месяцев на обновление приложения. Если вы не сможете обновиться по дате выхода на пенсию, запросы, отправленные из устаревших версий пакета SDK, будут по-прежнему обслуживаться Azure Cosmos DB, поэтому запущенные приложения будут продолжать функционировать. Но Azure Cosmos DB больше не исправлять ошибки, добавлять новые функции или предоставлять поддержку устаревших версий пакета SDK.

Если у вас есть план поддержки и вам требуется техническая поддержка, свяжитесь с нами, отправив соответствующий запрос.

Как запросить добавление компонентов в пакет SDK или соединитель?

Новые функции не всегда добавляются во все пакеты SDK или соединители сразу. Если вам хотелось бы добавить функцию, которая в настоящее время не поддерживается, напишите об этом на нашем форуме сообщества.

См. также

Дополнительные сведения о Azure Cosmos DB см. на странице службы Microsoft Azure Cosmos DB.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-04-27