Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Microsoft.Data.SqlClient — это поддерживаемый поставщик данных .NET для SQL Server, База данных SQL Azure, Управляемый экземпляр SQL Azure, Azure Synapse Analytics, базы данных SQL в Microsoft Fabric и Хранилища в Microsoft Fabric. Драйвер поставляется в виде пакетов NuGet независимо от времени выполнения .NET.
Выберите релиз
Используйте поддерживаемый выпуск General Availability (GA) для производственных приложений. Последний релиз GA — Microsoft. Data.SqlClient 7.1.1.
| Линейка релиза | Последняя версия | Уровень поддержки | Выберите, когда |
|---|---|---|---|
| 7.1 | 7.1.1 | Стандартный срок поддержки (STS) | Вам нужны текущие функции драйверов, и вы можете обновлять их в обычном темпе релиза. |
| 7.0 | 7.0.3 | Стандартный срок поддержки (STS) | Вам потребуются исправления для обслуживания, пока вы готовитесь к переходу на новую версию до окончания поддержки 17 декабря 2026 года. |
| 6.1 | 6.1.7 | Долгосрочная поддержка (LTS) | Вы предпочитаете более длительный период поддержки и не нуждаетесь в функциях, представленных в версии 7.x. |
Для актуальных версий патчей, дат поддержки, целевых фреймворков и совместимости базы данных см. жизненный цикл поддержки драйверов SqlClient.
Установите основной пакет
Выполните следующую команду из каталога, содержащего ваш проектный файл:
dotnet add package Microsoft.Data.SqlClient
Команда выбирает последнюю стабильную версию, совместимую с проектом. Чтобы закрепить версию для повторяемых сборок, укажите версию:
dotnet add package Microsoft.Data.SqlClient --version <version>
Эта команда добавляет PackageReference элемент в файл проекта. Для версии 7.1.1 файл проекта содержит следующую строку:
<PackageReference Include="Microsoft.Data.SqlClient" Version="7.1.1" />
Если добавить ещё Microsoft.Data.SqlClient.Extensions.Azure, в нём PackageReference используется та же версия.
Восстановить зависимости и построить проект:
dotnet restore
dotnet build
Если восстановление или сборка сообщает о предупреждении о пакете с известной уязвимостью, например NU1902 или NU1903, выполняйте шаги в разделе «Действия, если сообщается о пакетах с известными уязвимостями».
Импортируйте пространство драйверов в C#:
using Microsoft.Data.SqlClient;
Для новых приложений не ссылайтесь на старый System.Data.SqlClient пакет или пространство имён. Чтобы обновить существующее приложение, см. Переход с System.Data.SqlClient на Microsoft.Data.SqlClient.
Установка с помощью Visual Studio
- В Обозреватель решений кликните правой кнопкой мыши по проекту и выберите Управление пакетами NuGet.
- На вкладке «Просмотр » выполните поиск по
Microsoft.Data.SqlClient. - Выберите пакет, принадлежащий Microsoft.
- Выберите поддерживаемую стабильную версию, затем выберите Установить.
Дополнительные сведения см. в статье Установка пакетов в Visual Studio и управление ими с помощью диспетчера пакетов NuGet.
Добавить дополнительные пакеты
Устанавливайте дополнительные пакеты только тогда, когда ваше приложение использует соответствующую функцию.
| Package | Добавляйте, когда |
|---|---|
Microsoft.Data.SqlClient.Extensions.Azure |
Microsoft. Data.SqlClient 7.0 или более поздние версии используют режим аутентификации Microsoft Entra, предоставляемый драйвером, такой как Active Directory Default, Active Directory Interactive, или Active Directory Managed Identity. |
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider |
Always Encrypted хранит мастер-ключи столбцов в Azure Key Vault. |
Для аутентификации Microsoft Entra с SqlClient 7.0 или более поздними версиями запустите:
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version <same-version-as-Microsoft.Data.SqlClient>
Основной пакет 7.0 больше не включает зависимости Azure Identity. Начиная с версии 7.0.2, основной драйвер и сопутствующие пакеты используют согласованные версии. Ссылаемся на ту же версию Microsoft.Data.SqlClient и Microsoft.Data.SqlClient.Extensions.Azure. Приложения, не использующие драйверную аутентификацию Microsoft Entra, не нуждаются в пакете расширения Azure. Для настройки аутентификации см. Аутентификация Microsoft Entra с Microsoft.Data.SqlClient.
Обновление драйвера
Перед обновлением ознакомьтесь с этими пунктами:
Прочитайте «Что нового в Microsoft.Data.SqlClient» и исходные примечания к выпуску для каждой версии, через которую проходит обновление.
Перечислите прямые и транзитивные ссылки на пакеты приложения:
dotnet list package --include-transitiveОтметьте каждый дополнительный пакет, на который приложение ссылается напрямую, например
Microsoft.Data.SqlClient.Extensions.AzureилиMicrosoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider.
Обновите ссылку на упаковку.
dotnet add package Microsoft.Data.SqlClient --version <version>Для версии 7.0.2 и более поздних обновите каждый напрямую указанный сопутствующий пакет до той же версии.
Восстановить, собрать и запустить тесты приложения.
Тестирование установления соединения, аутентификации, проверки сертификатов, пула соединений, преобразования типов данных, транзакций и повторного поведения против каждого поддерживаемого объекта базы данных.
Крупные и патчные релизы могут требовать изменений в приложениях. Например, в версии 4.0 шифрование было включено по умолчанию, в версии 5.0 значение SqlConnectionStringBuilder.Encrypt было изменено с bool на SqlConnectionEncryptOption, а в версии 7.0 предоставляемая драйвером аутентификация Microsoft Entra была вынесена в отдельный пакет.
Начиная с версии 7.0.2, версии сборок Microsoft.Data.SqlClient.Extensions.Azure, Microsoft.Data.SqlClient.Extensions.Abstractions и Microsoft.Data.SqlClient.Internal.Logging изменились с 1.0.0.0 на 7.0.0.0. Приложения .NET Framework должны перестраиваться на основе выровнённых пакетов или добавлять перенаправления связывания. Приложения в текущем .NET не подвержены изменению идентичности ассемблера.
Понимание целевых фреймворков
Microsoft. Data.SqlClient 7.1 поддерживает приложения на:
- .NET 8 и более поздние версии поддерживали версии Windows, Linux и macOS.
- .NET Framework 4.6.2 или выше на Windows.
Пакет NuGet также содержит ресурс совместимости библиотек с .NET Standard 2.0. Исполняемое приложение должно быть предназначено для поддерживаемой среды выполнения .NET или .NET Framework. Ориентация библиотеки на .NET Standard не означает поддержку каждой среды выполнения, использующей эту библиотеку.
Пакет восстанавливает управляемые и нативные зависимости через NuGet. Не копируйте отдельные сборки драйверов или нативные библиотеки SQL Network Interface (SNI) между приложениями.
Проекты .NET Framework
Примеры в этих статьях предназначены для .NET. Для новой разработки используйте .NET вместо .NET Framework. Для получения дополнительной информации см. Обзор .NET Framework.
Проекты, ориентированные на .NET Framework, по умолчанию используют C# 7.3, поэтому образец, написанный для .NET, не компилируется без изменений. Краткое руководство: Подключение и выполнение запросов с помощью Microsoft.Data.SqlClient содержит вкладку .NET Framework с версией примера на C# 7.3.
Подготовка к развертыванию
Публикуйте для той же операционной системы и архитектуры, что и в продакшене. Для развертывания, зависящего от фреймворка:
dotnet publish --configuration ReleaseДля развертывания в конкретной среде выполнения:
dotnet publish --configuration Release --runtime <runtime-identifier>Развернуть полный результат публикации. Не выбирайте только
Microsoft.Data.SqlClient.dll.Убедитесь, что целевой сервер обладает необходимым временем выполнения .NET, если только вы не публикуете самостоятельное приложение.
Протестируйте опубликованные результаты на целевой операционной системе и архитектуре.
Протестируйте все режимы аутентификации, используемые в продакшене. Интегрированная аутентификация, Kerberos, сертификаты, управляемая идентификация и доступ к Azure Key Vault зависят от среды развертывания.
Сканируйте разрешённый граф зависимостей на наличие известных уязвимостей и обновляйте поддерживаемые строки пакета, когда появятся исправления.
Режим, не зависящий от параметров глобализации, не поддерживается. Для актуальных квалификаций платформы см. раздел «Поддерживаемые операционные системы».
Установка офлайн-пакета
Скачайте пакет и его зависимости с NuGet.org, скопируйте их во внутренний исходник пакета и восстановите их с этого источника. Для повторяемых офлайн-сборок закрепляйте версии пакетов и сохраняйте полный набор зависимостей.