Переход с System.Data.SqlClient на Microsoft. Data.SqlClient

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

Воспринимайте миграцию как обновление провайдера, а не просто замену пространства имён.

Планирование миграции

Перед сменой кода:

  1. Запишите версии сервисов .NET, System.Data.SqlClientSQL Server и Microsoft SQL, которые поддерживает приложение.

  2. Режимы проверки подлинности, ключевые слова строки подключения, пользовательские сертификаты, поставщики Always Encrypted, конфигурация DbProviderFactories, пользовательские типы SQL Server и использование System.Data.SqlTypes.

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

  4. Ищите прямые и транзитивные ссылки на пакеты:

    dotnet list package --include-transitive

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

Заменить упаковку

Удалите явную System.Data.SqlClient ссылку на пакет, если она есть:

dotnet remove package System.Data.SqlClient

Добавить Microsoft.Data.SqlClient:

dotnet add package Microsoft.Data.SqlClient

Если Microsoft. Data.SqlClient 7.0 или более позднее использует режим аутентификации Microsoft Entra, предоставляемый драйвером, также добавьте:

dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version <same-version-as-Microsoft.Data.SqlClient>

Для выбора версии и пакета см. Установка, обновление и развертывание Microsoft. Data.SqlClient.

Обновить пространства имен

Заменить основное пространство имён провайдера:

-using System.Data.SqlClient;
+using Microsoft.Data.SqlClient;

Обновить полностью квалифицированные имена, псевдонимы, сгенерированный код, регистрации инъекций зависимостей, строки отражения, конфигурацию и тестовые двойники, ссылающиеся на System.Data.SqlClient.

Не заменяйте общие System.Data или System.Data.Common пространства имён. Microsoft.Data.SqlClientпродолжает использовать типы ADO.NET, такие как CommandType, DbType, IsolationLevel, DataTableDbConnection, и DbCommand из этих пространств имён.

Некоторые типы, специфичные для SQL Server, перемещаются в другие Microsoft.Data пространства имён:

Type Предыдущее пространство имён Пространство имен Microsoft.Data.SqlClient
SqlDataRecord, SqlMetaData Microsoft.SqlServer.Server Microsoft.Data.SqlClient.Server
SqlFileStream System.Data.SqlTypes Microsoft.Data.SqlTypes
SqlNotificationRequest System.Data.Sql Microsoft.Data.Sql
OperationAbortedException System.Data Microsoft.Data

В версиях 5.0 и позднее другие типы Microsoft.Data.SqlClient общего языка выполнения (CLR) SQL Server остаются в Microsoft.SqlServer.Server. Обновляйте каждый тип, ориентируясь на ошибки компилятора и справочную документацию по API Microsoft.Data.SqlClient, а не заменяя всё пространство имён.

Обновить конфигурацию .NET Framework

Приложению, которое получает поставщиков через DbProviderFactories, может потребоваться регистрация поставщика в App.config или Web.config:

<configuration>
  <system.data>
    <DbProviderFactories>
      <add name="SqlClient Data Provider"
           invariant="Microsoft.Data.SqlClient"
           description=".NET data provider for SQL Server"
           type="Microsoft.Data.SqlClient.SqlClientFactory, Microsoft.Data.SqlClient" />
    </DbProviderFactories>
  </system.data>
</configuration>

Обновите код, который запрашивает инвариантное имя поставщика данных:

DbProviderFactory factory =
    DbProviderFactories.GetFactory("Microsoft.Data.SqlClient");

Не добавляйте эту конфигурацию, когда приложение создаёт SqlConnection напрямую и не использует DbProviderFactories.

Проверка шифрования и проверки сертификатов

Microsoft. Data.SqlClient использует более защищённые настройки по умолчанию, чем System.Data.SqlClient.

Behavior System.Data.SqlClient Microsoft.Data.SqlClient
Стандартное шифрование Encrypt=false Encrypt=true Начиная с версии 4.0
Проверка сертификата сервера Проверяет сертификат только при включении шифрования клиента Начиная с версии 2.0, сертификат проверяется в соответствии с TrustServerCertificate, когда сервер принудительно использует шифрование, даже если Encrypt=false
Строгое шифрование Не поддерживаются Encrypt=Strict начиная с версии 5.0 для серверов с поддержкой TDS 8.0
тип SqlConnectionStringBuilder.Encrypt bool SqlConnectionEncryptOption Начиная с версии 5.0

Не используйте Encrypt=false или TrustServerCertificate=true в качестве универсального решения для исправления проблем миграции. Настройте сертификат, которому клиент доверяет, и используйте имя сервера, соответствующее сертификату. Используйте TrustServerCertificate=true только для контролируемых сред разработки, где валидация невозможна.

Изменение для SqlConnectionEncryptOption не нарушает совместимость исходного кода в типичных случаях присваивания за счёт неявных преобразований, но нарушает бинарную совместимость. Перекомпилируйте каждую ассемблеру, которая обращается к SqlConnectionStringBuilder.Encrypt.

Дополнительные сведения см. в разделе о шифровании и проверке сертификатов.

Пересмотреть строки соединения

Microsoft. Data.SqlClient добавляет ключевые слова и псевдонимы, которые System.Data.SqlClient не распознаёт. Например, он принимает псевдонимы с пробелами, такими Application Intent как и Multi Subnet Failover.

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

Проверьте ключевые слова аутентификации, шифрования, повторного тестирования, отказа и сертификации по синтаксису строк соединения.

Проверить поведение параметра

Параметры даты и времени тестирования явно указаны:

Parameter Поведение System.Data.SqlClient Поведение Microsoft.Data.SqlClient
DbType.Time с DateTime значением Принимает значение Используйте значение TimeSpan
DbType.Date с DateTime значением Можно отправлять компоненты с датами и временем Усекает временные компоненты

Указывайте SqlDbType, длину, точность и масштаб для параметров, для которых вывод типа в SQL Server может изменить планы запросов или поведение преобразования. Не используйте AddWithValue как сокращение для миграции, если тип базы данных известен.

Проверьте ссылки на транзитивных поставщиков

Прямое удаление пакета не гарантирует, что System.Data.SqlClient будет удалён. Запустить:

dotnet list package --include-transitive

Если оба поставщика остаются:

  1. Определите пакет, который включает System.Data.SqlClient.
  2. Обновляйте или заменяйте эту зависимость, когда это возможно.
  3. Сохраняйте специфичные для провайдера типы внутри границы зависимости, если необходимо сохранить и то и другое.
  4. Используйте явные псевдонимы пространства имён только как временную помощь. Не передавайте соединение, транзакцию, параметр или считыватель от одного провайдера к другому.

Особое внимание обратите на библиотеки типа SQL Server CLR и старые фреймворки для доступа к данным, которые открывают System.Data.SqlClient типы в своих публичных API.

Обзор поведения в глобализации

Версии .NET Framework и .NET до .NET 5 используют глобализацию Национальной поддержки языков (NLS) на Windows. Текущие версии .NET по умолчанию используют International Components for Unicode (ICU) для Windows, Linux и macOS.

Это различие во время выполнения может повлиять на результаты некоторых сравнений SqlString. SQL Server использует поведение сравнения NLS. Если сравнения на стороне клиента SqlString должны совпадать с поведением сервера, проверьте затронутые значения и ознакомьтесь с разделом Глобализация и ICU. Приложение может использовать NLS вместо ICU при необходимости.

Режим инвариантной глобализации не поддерживается в Microsoft.Data.SqlClient.

Проверьте мигрированное приложение

Создавайте и тестируйте на каждом поддерживаемом целевом фреймворке и операционной системе.

Проверить:

  • Восстановление пакета и опубликованный результат.
  • Аутентификация SQL, интегрированная аутентификация Windows и аутентификация Microsoft Entra, используемые приложением.
  • Согласование TLS, проверка сертификатов и разбор строки подключения.
  • Пул соединений и обновление токена доступа.
  • Типы параметров, нулевые значения, точность, масштаб, поведение по дате и времени.
  • Транзакции, отмены, тайм-ауты, повторные запуски и отказ.
  • Always Encrypted, типы CLR SQL Server, массовое копирование, уведомления о запросах и другие специфические для поставщика функции, используемые приложением.
  • Логирование, счетчики, трассировка и обработка исключений.

Запускайте репрезентативные запросы ко всем поддерживаемым версиям движка базы данных. Успешная компиляция не проверяет безопасность соединения, зависимости во время выполнения или преобразования данных.

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

  • Last updated on