Пакет 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

Обзор

Пакет 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 совместимы с этими изменениями.

Это важно

Эта зависимость требуется даже при использовании 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	Минимальная безопасная версия	Recommended
3.47.0+	13.0.3	13.0.4
3.54.0+	13.0.4	13.0.4

Подсказка

При использовании .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

Часто задаваемые вопросы

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

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

Могу ли я во время этого периода в 12 месяцев создавать приложения, используя пакет SDK для Azure Cosmos DB, поддержка которого будет прекращена?

Да, в течение 12-месячного периода уведомления вы сможете разрабатывать, развертывать и изменять приложения с помощью пакета SDK для Azure Cosmos DB, поддержка которого будет прекращена. Мы рекомендуем при удобной возможности перейти на новую поддерживаемую версию Azure Cosmos DB пакета SDK в течение 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 2025-12-19