Пространство имён Microsoft.Data.SqlClient и совместимость

Пространство имен Microsoft.Data.SqlClient включает поддерживаемый поставщик данных .NET для баз данных, совместимых с SQL Server. Изначально это было ответвление от System.Data.SqlClient, и оно сохраняет знакомую модель программирования ADO.NET, при этом новые функции SQL Server поставляются независимо от среды выполнения .NET.

Используйте Microsoft.Data.SqlClient для новой разработки.

Установка и импорт пространства имён

Добавьте пакет NuGet:

dotnet add package Microsoft.Data.SqlClient

Импортируйте пространство имён:

using Microsoft.Data.SqlClient;

Большинство приложений используют SqlConnection, SqlCommand, SqlParameterSqlDataReader, и SqlTransaction. Для полной публичной поверхности см. ссылку на API Microsoft. Data.SqlClient.

Связь с ADO.NET

ADO.NET — это модель доступа к данным, встроенная в .NET. Он определяет независимые от провайдера абстракции в пространстве имён System.Data.Common, а Microsoft.Data.SqlClient предоставляет конкретные реализации.

Абстракция ADO.NET Тип SqlClient Purpose
DbConnection SqlConnection Открывает логическое соединение с одной базой данных.
DbCommand SqlCommand Выполняет Transact-SQL текст (T-SQL) или сохранённую процедуру.
DbParameter SqlParameter Отправляет введённое значение отдельно от командного текста.
DbDataReader SqlDataReader Передаёт строки результата потоком с сервера.
DbTransaction SqlTransaction Объединяет команды в одну транзакцию, которая коммитирует или откатывается как единое целое.
DbDataAdapter SqlDataAdapter Заполняет и обновляет отключенные объекты DataSet и DataTable.
DbBatch SqlBatch Отправляет несколько команд одним пакетом для поддерживаемых целевых платформ.

Microsoft. Data.SqlClient также предоставляет специфические для SQL Server API такие, как:

  • SqlBulkCopy
  • SqlConnectionStringBuilder
  • SqlConfigurableRetryFactory
  • SqlDependency
  • Поддержка аутентификации, шифрования и типов данных, специфичных для SQL Server

Программировать против абстракций ADO.NET, когда библиотека должна поддерживать несколько поставщиков баз данных. Используйте типы SqlClient, когда приложение нацелено на SQL Server и нуждается в специфических для провайдера функциях, таких как аутентификация Microsoft Entra, Always Encrypted, массовое копирование, параметры с табличным значением или настраиваемая логика повторных попыток. Оставляйте код, специфичный для провайдера, в пределах слоя доступа к данным, если остальная часть приложения должна оставаться независимой от провайдера.

Онлайн- и офлайн-доступ

Подключённый доступ оставляет соединение открытым, пока выполняется команда и пока приложение читает её результаты. Типичный запрос следует следующей последовательности:

  1. Создайте SqlConnection из строка подключения и откройте её.
  2. Создайте SqlCommand и добавьте значения SqlParameter.
  3. Выполните команду .
  4. Обрабатывайте скалярное значение, количество затронутых строк или объект SqlDataReader.
  5. Избавьтесь от считывателя, команды и соединения.

Используйте подключённый доступ для большинства веб-API, сервисов, рабочих и командных приложений. SqlDataReader передаёт строки потоком и обычно использует меньше памяти, чем при загрузке всего результата в DataSet.

Автономный доступ использует SqlDataAdapter для копирования данных в память DataSet или DataTable. Приложение может закрыть соединение во время чтения или изменения данных в памяти, а затем снова подключиться для отправки обновлений. Используйте его для привязки данных, отношений и ограничений в памяти, офлайн-правок, которые вы позже синхронизируете, или для существующего приложения, построенного на основе DataAdapters. Для новых сервисов, ориентированных на запросы, начинайте с SqlCommand и SqlDataReader.

Время жизни объектов и параллелизм

Откройте и освобождайте SqlConnection для каждой единицы работы. Пул соединений повторно использует базовое физическое соединение, поэтому не оставляйте одно глобальное соединение открытым на весь срок службы приложения. Быстро избавляйтесь от соединений, команд, считывателей, транзакций и массового копирования объектов. В асинхронном коде используйте await using для типов, реализующих IAsyncDisposable на целевом фреймворке, таких как SqlConnection и SqlDataReader на .NET, и обычный using для типов, реализующих только IDisposable, например SqlBulkCopy.

SqlConnection, SqlCommand, SqlDataReader и SqlTransaction не поддерживают одновременное использование несколькими потоками. Дайте каждой параллельной операции отдельное соединение и полагайтесь на пул соединений. Технология Multiple Active Result Sets (MARS) допускает наличие нескольких активных наборов результатов в одном соединении, но не делает объекты SqlClient потокобезопасными.

Связь с System.Data.SqlClient

System.Data.SqlClientэто старый провайдер, который поставляется с .NET Framework и более ранними версиями .NET. Microsoft.Data.SqlClient использует многие одинаковые типовые имена, но имеет разные пакеты, пространства имён, настройки по умолчанию, функции и политики поддержки.

Не ссылайтесь на обоих провайдеров в новом коде приложения. Типы с одинаковыми названиями из двух пакетов не взаимозаменяемы. Например, System.Data.SqlClient.SqlConnection нельзя передать там, где требуется Microsoft.Data.SqlClient.SqlConnection.

Миграция обычно начинается с добавления пакета Microsoft.Data.SqlClient и изменения ссылок на пространство имён, но также необходимо проверить шифрование соединений, параметры, конфигурацию, транзитивные зависимости и поведение во время выполнения. Перед развертыванием выполните инструкции в статье Переход с System.Data.SqlClient на Microsoft.Data.SqlClient.

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

Версия пакета драйверов независима от версии приложения в .NET и версии движка базы данных. Проверьте все три:

Component Что проверить
Microsoft.Data.SqlClient Выпускная линия поддерживается и содержит функции, используемые вашим приложением.
.NET или .NET Фреймворк Приложение ориентировано на среду выполнения, поддерживаемую этим выпуском драйвера.
База данных, совместимых с SQL Server Версия драйвера поддерживает версию базы данных, а сервер — любые запрошенные функции протокола, такие как TDS 8.0.

Для актуальных матриц см. жизненный цикл поддержки драйверов SqlClient.

Изменения, связанные с версией

Выпуски драйверов могут добавлять API, перемещать опциональные зависимости и менять безопасные настройки по умолчанию. Проверяйте изменения перед каждым незначительным или крупным обновлением.

Вот некоторые примеры:

  • В версии 4.0 для Encrypt по умолчанию установлено значение true.
  • В версии 5.0 были представлены SqlConnectionEncryptOption и Encrypt=Strict для TDS 8.0.
  • В версии 5.2 была представлена функция SqlBatch для поддерживаемых современных целевых платформ .NET.
  • Версия 7.0 переместила аутентификацию Microsoft Entra, предоставляемую драйвером, в Microsoft.Data.SqlClient.Extensions.Azure.

Посмотрите, что нового в Microsoft. Data.SqlClient — ссылки на релизные заметки и обзор обновлений.

Некоторые функции используют типы вне основного пространства имён или опциональные пакеты.

Пространство имён или пакет Purpose
Microsoft.Data.SqlClient.Server Реализации SqlDataRecord и SqlMetaData в SqlClient.
Microsoft.Data.SqlTypes Типы, специфичные для SqlClient, например SqlFileStream, SqlJson и SqlVector<T>.
Microsoft.Data.SqlClient.Diagnostics Строго типизированные данные диагностических событий.
Microsoft.Data.SqlClient.Extensions.Azure Аутентификация Microsoft Entra, предоставляемая драйвером, для версии 7.0 и более поздних версий.
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider Интеграция Azure Key Vault для Always Encrypted

Не делайте выводы о требованиях пакета только по пространству имён. Ознакомьтесь со статьёй с описанием функций и сведениями о зависимостях пакета NuGet для используемой версии драйвера.

Связанные материалы

  • Последнее обновление: