Введение в пространство имен Microsoft.Data.SqlClient

Скачать ADO.NET

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

Существует несколько различий в менее используемых API по сравнению с System.Data.SqlClient, которые могут повлиять на некоторые приложения. Для этих различий обратитесь к полезной шпаргалке по портированию.

Справочник по API

Сведения об API Microsoft.Data.SqlClient можно найти в обозревателе API .NET.

Заметки о выпуске для версии 7.0

Это релиз общего доступа Microsoft.Data.SqlClient 7.0, важным этапом для поставщика данных .NET для SQL Server. В этом выпуске решается самая загруженная проблема за всю историю репозитория — извлечение зависимостей Azure из основного пакета — вводится подключаемая аутентификация SSPI, добавляется улучшенная маршрутизация для Azure и обеспечивается повышение производительности асинхронного чтения.

Также выпущен в рамках этой вехи:

• Выпущен Microsoft.Data.SqlClient.Extensions.Abstractions 1.0.0. См заметки о выпуске.
• Выпущен Microsoft.Data.SqlClient.Extensions.Azure 1.0.0. См. заметки о выпуске.
• Выпущен Microsoft.Data.SqlClient.Internal.Logging 1.0.0. Смотрите заметки о выпуске.
• Выпущен Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider 7.0.0. См. заметки о выпуске.

Критические изменения в версии 7.0

Зависимости Azure удалены из основного пакета

Что изменилось:

• Основной Microsoft.Data.SqlClient пакет больше не зависит от Azure.CoreAzure.Identity, или их транзитивных зависимостей (например, Microsoft.Identity.Client, Microsoft.Web.WebView2). Функциональность аутентификации Azure Active Directory / Entra ID (ActiveDirectoryAuthenticationProvider и связанные типы) была вынесена в новый Microsoft.Data.SqlClient.Extensions.Azure пакет. (#1108, #3680, #3902, #3904, #3908, #3917, #3982, #3978, #3986)
• Для поддержки этого разделения представлены два дополнительных пакета: Microsoft.Data.SqlClient.Extensions.Abstractions (общие типы между основным драйвером и расширениями) и Microsoft.Data.SqlClient.Internal.Logging (общая инфраструктура трассировки ETW).
  (#3626, #3628, #3967, #4038)

Кто получает преимущества:

• Все пользователи получают преимущества от более легкого основного пакета. Ранее цепочка зависимостей Azure включала многочисленные сборки даже для приложений, которым требовалось только базовое подключение к SQL Server. Это был наиболее проголосованный открытый вопрос в репозитории.
• Пользователи, которые не используют аутентификацию Entra ID, больше не содержат сборок, связанных с Azure, в окончательных данных сборки.
• Пользователи, использующие проверку подлинности Entra ID, теперь могут управлять версиями зависимостей Azure независимо от основного драйвера.

Влияние.

• Приложения, использующие проверку подлинности Entra ID (например, ActiveDirectoryInteractive, ActiveDirectoryDefault, ActiveDirectoryManagedIdentityи т. д.), теперь должны установить Microsoft.Data.SqlClient.Extensions.Azure пакет NuGet отдельно:

dotnet add package Microsoft.Data.SqlClient.Extensions.Azure

• Никаких изменений кода не требуется, кроме добавления ссылки на пакет.
• Если метод проверки подлинности с Entra ID используется без установленного пакета Azure, драйвер теперь предоставляет понятное сообщение об ошибке, которое позволяет пользователям установить правильный пакет.

Другие критические изменения в версии 7.0

• Отменена общедоступная видимость внутренних перечислений взаимодействия (IoControlCodeAccess и IoControlTransferType), которые были случайно обнародованы во время слияния проекта. (#3900)

Новые возможности в версии 7.0

Подключаемая проверка подлинности с помощью SspiContextProvider

Что изменилось:

• Добавлено общедоступное SspiContextProvider свойство для SqlConnection, завершающее работу по обеспечению возможности расширения SSPI, начатую в версии 6.1.0. Теперь приложения могут предоставлять настраиваемый поставщик контекста SSPI для интегрированной проверки подлинности, что позволяет выполнять согласование пользовательских запросов Kerberos и сценарии проверки подлинности имени пользователя и пароля NTLM. (#2253, #2494)

Кто получает преимущества:

• Пользователи, проверяющие подлинность в ненадежных доменах, не присоединенных к домену компьютерах или кроссплатформенных средах, где настройка интегрированной проверки подлинности затруднена.
• Пользователи, работающие в контейнерах, которым требуется ручное согласование Kerberos без развертывания сайдкаров или внешних механизмов обновления тикетов.
• Пользователи, которым требуется аутентификация NTLM с использованием имени пользователя и пароля в SQL Server, которую драйвер не поддерживает в своем собственном коде.

Влияние.

• Приложения могут задать настраиваемый SspiContextProvider параметр SqlConnection перед открытием подключения:

var connection = new SqlConnection(connectionString);
connection.SspiContextProvider = new MyKerberosProvider();
connection.Open();

• Поставщик обрабатывает обмен токенами аутентификации во время интегрированной аутентификации. Существующее поведение проверки подлинности не изменяется при отсутствии настраиваемого поставщика. Пример реализации см. в SspiContextProvider_CustomProvider.cs .
• Примечание: Элемент SspiContextProvider является частью ключа пула подключений. Убедитесь, что реализация возвращает постоянный идентификатор для каждого ресурса.

Производительность асинхронного чтения: мультиплексирование пакетов (предварительная версия)

Что изменилось:

• Продолжающееся уточнение мультиплексирования пакетов с исправлениями ошибок и улучшения стабильности с 6.1.0, а также новые параметры контекста приложения для управления согласием. (#3534, #3537, #3605)

Кто получает преимущества:

• Приложения, выполняющие большие асинхронные операции чтения (ExecuteReaderAsync с большими результирующих наборами, сценариями потоковой передачи или извлечением массовых данных).

Влияние.

• Мультиплексирование пакетов доступно через два переключателя опциональных функций:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityAsyncBehaviour", false);
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityProcessSni", false);

• Установка обоих переключателей на false позволяет использовать новый асинхронный механизм обработки. По умолчанию драйвер использует существующее (совместимое) поведение.

Расширенная поддержка маршрутизации

Что изменилось:

• Добавлена поддержка расширенной маршрутизации, функция TDS, которая позволяет серверу перенаправлять подключения к определенному серверу и базе данных во время входа. (#3641, #3969, #3970, #3973)

Кто получает преимущества:

• Пользователи, подключающиеся к средам Azure, использующие именованные реплики чтения и балансировку нагрузки на основе шлюза.

Влияние.

• Расширенная маршрутизация выполняется автоматически во время входа, когда сервер поддерживает его. Никаких изменений кода приложения не требуется.

Поддержка .NET 10

Что изменилось:

• Обновлены конвейеры и наборы тестов для компиляции драйвера с помощью пакета SDK для .NET 10. (#3686)

Кто получает преимущества:

• Разработчики, нацеленные на .NET 10 с первого дня.

Влияние.

• SqlClient 7.0 компилирует и тестирует на .NET 10, обеспечивая совместимость.

Строго типизированные диагностические события в .NET Framework

Что изменилось:

• Включена SqlClientDiagnosticListener для SqlCommand на платформе .NET Framework, закрывая давний разрыв в наблюдаемости, при котором диагностические события ранее выдавались только на .NET Core. (#3658)

• Принесли 15 строго типизированных классов диагностических событий в пространстве имен Microsoft.Data.SqlClient.Diagnostics, первоначально появившиеся для .NET Core версии 6.0, в .NET Framework в рамках слияния кодовой базы. Обе платформы теперь используют одну и ту же строго типизированную модель событий. Типы охватывают события жизненного цикла команд, подключений и транзакций:

  • SqlClientCommandBefore, SqlClientCommandAfter, SqlClientCommandError
  • SqlClientConnectionOpenBefore, SqlClientConnectionOpenAfter, SqlClientConnectionOpenError
  • SqlClientConnectionCloseBefore, SqlClientConnectionCloseAfter, SqlClientConnectionCloseError
  • SqlClientTransactionCommitBefore, SqlClientTransactionCommitAfter, SqlClientTransactionCommitError
  • SqlClientTransactionRollbackBefore, SqlClientTransactionRollbackAfter, SqlClientTransactionRollbackError

  (#3493)

Кто получает преимущества:

• Пользователи .NET Framework подписываются на SqlClientDiagnosticListener события для наблюдения, распределенной трассировки или пользовательской телеметрии. Теперь у пользователей есть паритет с .NET Core, доступ к IntelliSense, обеспечение безопасности компиляции и устранение необходимости обращения к диагностическим данным с использованием отражения или поиска в словаре.

Влияние.

• В .NET Framework SqlCommand теперь выдает те же диагностические события, которые ранее были доступны только в .NET Core. Подписчики событий DiagnosticListener (например, Microsoft.Data.SqlClient.WriteCommandBefore) получают объекты с строгой типизацией:

listener.Subscribe(new Observer<KeyValuePair<string, object?>>(kvp =>
{
    if (kvp.Value is SqlClientCommandBefore before)
    {
        Console.WriteLine($"Executing: {before.Command.CommandText}");
    }
}));

• Типы реализуются IReadOnlyList<KeyValuePair<string, object>> для обратной совместимости с кодом, который выполняет итерацию свойств универсально.

Другие дополнения в версии 7.0

• Добавлено статичное SqlConfigurableRetryFactory.BaselineTransientErrors свойство, предоставляющее список кодов ошибок по умолчанию в виде ReadOnlyCollection<int>списка временных ошибок, что упрощает расширение списка по умолчанию с помощью кодов ошибок для конкретного приложения. (#3903)

• Добавлен переключатель контекста приложения Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault для глобальной установки MultiSubnetFailover=true без изменения строк подключения. (#3841)

• Добавлен переключатель контекста приложения Switch.Microsoft.Data.SqlClient.IgnoreServerProvidedFailoverPartner, чтобы клиент мог игнорировать предоставленные сервером сведения о партнере отработки отказа в базовых группах доступности. (#3625)

• Включаемое расширение возможностей пользовательского агента (с возможностью подписки через Switch.Microsoft.Data.SqlClient.EnableUserAgent). (#3606)

Изменения в версии 7.0

Устаревание SqlAuthenticationMethod.ActiveDirectoryPassword

Что изменилось:

• SqlAuthenticationMethod.ActiveDirectoryPassword (поток ROPC) теперь помечен [Obsolete] и создаст предупреждения компилятора. Это соответствует переходу Корпорации Майкрософт к обязательной многофакторной проверке подлинности. (#3671)

Кто получает преимущества:

• Команды переходят к более надежной, без пароля или многофакторной проверке подлинности.

Влияние.

• При использовании Authentication=Active Directory Passwordвыполните миграцию в поддерживаемую альтернативу:

Сценарий	Рекомендуемая проверка подлинности
Интерактивные и настольные приложения	Active Directory Interactive
Взаимодействие между службами	Active Directory Service Principal
Размещенные в Azure рабочие нагрузки	Active Directory Managed Identity
Среды разработчика и CI	Active Directory Default

• Дополнительные сведения см. в статье "Подключение к SQL Azure" с проверкой подлинности Microsoft Entra .

Поддержка целевой платформы версии 7.0

• .NET Framework 4.6.2+ (Windows x86, Windows x64, Windows ARM64)
• .NET 8.0+ (Windows x86, Windows x64, Windows ARM, Windows ARM64, Linux, macOS)

Полные заметки о выпуске, включая зависимости, доступны в репозитории GitHub: заметки о выпуске 7.0.

Заметки о выпуске для версии 6.1

Новые возможности в версии 6.1

Добавлена поддержка выделенного типа данных вектора SQL Server

Что изменилось:

• Оптимизированная векторная связь между MDS и SQL Server 2025 (17.x), используюющая настраиваемый двоичный формат по протоколу TDS (#3433, #3443).

• Снижение нагрузки на обработку по сравнению с существующей поддержкой векторов на основе JSON.

• Начальная поддержка 32-разрядных векторов с плавающей точкой одинарной точности.

Кто выигрывает:

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

Эффект:

• Сокращение времени передачи и обработки для векторных операций и JSON с помощью SQL Server 2025 (17.x):

  • Чтение: улучшение 50x
  • Запись данных: улучшение в 3.3 раза
  • Массовое копирование: увеличение в 19 раз
  • (Наблюдается с векторным столбцом максимальной длины 1998 и 10 000 записей для каждой операции.)

• Улучшено потребление памяти благодаря устранению сериализации/десериализации JSON и избыточности строковых представлений.

• Для обратной совместимости с более ранними реализациями векторов SQL Server приложения могут продолжать использовать строки JSON для отправки и получения векторных данных, хотя они не видят никаких улучшений производительности, отмеченных ранее.

Возрождение целевой поддержки .NET Standard 2.0

Что изменилось:

• Поддержка для платформы .NET Standard 2.0 восстановлена (#3381)
• Ранее поддержка была удалена в выпуске 6.0 с выражением обеспокоенности со стороны сообщества.

Кто выигрывает:

• Библиотеки, зависящие от MDS, могут легко нацеливается на любую из следующих платформ:
  • .NET Standard 2.0
  • .NET Framework 4.6.2 и более поздних версий
  • .NET 8.0
  • .NET 9.0
• Приложения должны продолжать использовать целевые среды выполнения.
  • Поддержка целевой платформы MDS .NET Standard 2.0 не включает фактическую реализацию и не может использоваться с средой выполнения.
  • Процесс сборки и публикации приложения всегда должен выбирать соответствующую реализацию среды выполнения MDS .NET/.NET Framework.
  • Пользовательские действия сборки и публикации, которые некорректно пытаются выполнить развертывание ссылочной DLL MDS .NET Standard 2.0 во время выполнения, не поддерживаются.

Эффект:

• Библиотеки, предназначенные для .NET Standard 2.0, больше не получают предупреждения, такие как:

  warning NU1701: Package 'Microsoft.Data.SqlClient 6.0.2' was restored using '.NETFramework,Version=v4.6.1, .NETFramework,Version=v4.6.2, .NETFramework,Version=v4.7, .NETFramework,Version=v4.7.1, .NETFramework,Version=v4.7.2, .NETFramework,Version=v4.8, .NETFramework,Version=v4.8.1' instead of the project target framework '.NETStandard,Version=v2.0'. This package may not be fully compatible with your project.
  

Другие дополнения

• Добавлена поддержка специального регистра с конечными точками Fabric. (#3084)

Поддержка целевой платформы 6.1

• .NET Framework 4.6.2+ (Windows Arm64, Windows x86, Windows x64)
• .NET 8.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Полные заметки о выпуске, включая зависимости, доступны в репозитории GitHub: заметки о выпуске 6.1.

Заметки о выпуске для версии 6.0

Критические изменения в версии 6.0

• Удалена поддержка .NET Standard. #2386
• Удалена поддержка .NET 6 #2927
• Удалены ссылки на UWP (UAP). #2483
• Удалена поддержка отладки на стороне клиента SQL 2000 для .NET Framework #2981, #2940

Новые возможности в версии 6.0

• Добавлена поддержка типа данных JSON #2916, #2892, #2891, #2880, #2882, #2829, #2830
• Добавлена поддержка .NET 9 #2946
• Добавлен тип Microsoft.Data.SqlClient.Diagnostics.SqlClientDiagnostic в .NET. #2226
• Добавлена поддержка DateOnly и TimeOnly для DataTable в качестве структурированного параметра. #2258
• Добавлена поддержка SqlConnectionOverrides в OpenAsync() API #2433
• Добавлена локализация в чешском, польском и турецком #2987
• Добавлен объект TokenCredential, чтобы воспользоваться преимуществами кэширования токенов в ActiveDirectoryAuthenticationProvider. #2380
• Добавлен файл readme в пакет NuGet #2826
• Включен аудит пакета NuGet с помощью источника аудита NuGet.org #3024
• Добавлен отсутствующий пример кода SqlCommand_BeginExecuteReader #3009
• Добавлена трассировка области видимости для GenerateSspiClientContext. #2497, #2725

Поддержка типов данных JSON

Поддержка типов данных JSON теперь доступна в Microsoft.Data.SqlClient версии 6.0. В этом выпуске представлен тип SqlJson, доступный как расширение для System.Data.SqlDbTypes:

using System;
using System.Data.SqlTypes;
using System.Text.Json;

namespace Microsoft.Data.SqlTypes
{
    /// <summary>
    /// Represents the Json data type in SQL Server.
    /// </summary>
    public class SqlJson : INullable
    {
        /// <summary>
        /// Parameterless constructor. Initializes a new instance of the SqlJson class which
        /// represents a null JSON value.
        /// </summary>
        public SqlJson() { }

        /// <summary>
        /// Takes a <see cref="string"/> as input and initializes a new instance of the SqlJson class.
        /// </summary>
        /// <param name="jsonString"></param>
        public SqlJson(string jsonString) { }

        /// <summary>
        /// Takes a <see cref="JsonDocument"/> as input and initializes a new instance of the SqlJson class.
        /// </summary>
        /// <param name="jsonDoc"></param>
        public SqlJson(JsonDocument jsonDoc) { }

        /// <inheritdoc/>
        public bool IsNull => throw null;

        /// <summary>
        /// Represents a null instance of the <see cref="SqlJson"/> type.
        /// </summary>
        public static SqlJson Null { get { throw null; } }

        /// <summary>
        /// Gets the string representation of the JSON content of this <see cref="SqlJson" /> instance.
        /// </summary>
        public string Value { get ; }
    }
}

Тип данных JSON поддерживает операции чтения, записи, потоковой передачи и массового копирования.

Знакомство с SqlClientDiagnostics

Новые типы доступны в Microsoft.Data.SqlClient.Diagnostics пространстве имен, предоставляющем строго типизированную коллекцию пар "ключ-значение". Эти типы можно фиксировать с помощью приложений для сбора диагностических событий, генерируемых драйвером. В этом выпуске представлены следующие типы:

• SqlClientCommandBefore
• SqlClientCommandAfter
• SqlClientCommandError
• SqlClientConnectionOpenBefore
• SqlClientConnectionOpenAfter
• SqlClientConnectionOpenError
• SqlClientConnectionCloseBefore
• SqlClientConnectionCloseAfter
• SqlClientConnectionCloseError
• SqlClientTransactionCommitBefore
• SqlClientTransactionCommitAfter
• SqlClientTransactionCommitError
• SqlClientTransactionRollbackBefore
• SqlClientTransactionRollbackAfter
• SqlClientTransactionRollbackError

Добавлена поддержка переопределений подключений в API OpenAsync()

Поведение по умолчанию SqlConnection.OpenAsync() можно переопределить, чтобы отключить десятисекундную задержку и автоматические попытки подключения, вызванные временными ошибками.

using(SqlConnection sqlConnection = new SqlConnection("Data Source=(local);Integrated Security=true;Initial Catalog=AdventureWorks;"))
{
    await sqlConnection.OpenAsync(SqlConnectionOverrides.OpenWithoutRetry, cancellationToken);
}

Поддержка целевой платформы 6.0

• Платформа .NET Framework 4.6.2+ (Windows x86, Windows x64)
• .NET 8.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Полные заметки о выпуске, включая зависимости, доступны в репозитории GitHub: Заметки о выпуске 6.0.

Заметки о выпуске для версии 5.2

Новые возможности в версии 5.2

• Добавлена поддержка для SqlDiagnosticListener.NET Standard. #1931
• Добавлено новое свойство RowsCopied64 в SqlBulkCopy. #2004Подробнее
• Добавлен новый API AccessTokenCallBack к SqlConnection. #1260Подробнее
• Добавлена поддержка SuperSocketNetLib параметра реестра для Encrypt в .NET на Windows. #2047
• Добавлена SqlBatch поддержка .NET 6+ #1825, #2223Подробнее
• Добавлена поддержка аутентификации по удостоверению рабочей нагрузки #2159, #2264
• Добавлена поддержка локализации в .NET #2210
• Добавлена поддержка грузинского сопоставления #2194
• Добавлена поддержка систем Big Endian #2170
• Добавлена поддержка .NET 8 #2230
• Добавлена явная версия для основных зависимостей версии .NET в System.Runtime.Caching 8.0.0, System.Configuration.ConfigurationManager 8.0.0 и System.Diagnostics.DiagnosticSource 8.0.0 #2303
• Добавлена возможность создания символов отладки в отдельном файле пакета #2137

Добавлено новое свойство RowsCopied64 в SqlBulkCopy

SqlBulkCopy имеет новое свойство RowsCopied64 , которое поддерживает long типы значений.

Существующее SqlBulkCopy.RowsCopied поведение не изменяется. При превышении значения int.MaxValue элемент RowsCopied может возвращать отрицательное число.

Пример использования:

    using (SqlConnection srcConn = new SqlConnection(srcConstr))
    using (SqlCommand srcCmd = new SqlCommand("select top 5 * from employees", srcConn))
    {
        srcConn.Open();
        using (DbDataReader reader = srcCmd.ExecuteReader())
        {
            using (SqlBulkCopy bulkcopy = new SqlBulkCopy(dstConn))
            {
                bulkcopy.DestinationTableName = dstTable;
                SqlBulkCopyColumnMappingCollection ColumnMappings = bulkcopy.ColumnMappings;

                ColumnMappings.Add("EmployeeID", "col1");
                ColumnMappings.Add("LastName", "col2");
                ColumnMappings.Add("FirstName", "col3");

                bulkcopy.WriteToServer(reader);
                long rowsCopied = bulkcopy.RowsCopied64;
            }
        }
    }

Добавлено новое свойство AccessTokenCallBack в SqlConnection

SqlConnection поддерживает TokenCredential проверку подлинности, вводя новое свойство AccessTokenCallBack, представляющее собой делегат Func<SqlAuthenticationParameters, CancellationToken,Task<SqlAuthenticationToken>>, для возврата токена доступа к федеративной проверке подлинности.

Пример использования:

using Microsoft.Data.SqlClient;
using Azure.Identity;

const string defaultScopeSuffix = "/.default";
string connectionString = GetConnectionString();
DefaultAzureCredential credential = new();
using SqlConnection connection = new(connectionString);

connection.AccessTokenCallback = async (authParams, cancellationToken) =>
{
    string scope = authParams.Resource.EndsWith(defaultScopeSuffix)
        ? authParams.Resource
        : $"{authParams.Resource}{defaultScopeSuffix}";
    AccessToken token = await credential.GetTokenAsync(
        new TokenRequestContext([scope]),
        cancellationToken);

    return new SqlAuthenticationToken(token.Token, token.ExpiresOn);
}

connection.Open();
Console.WriteLine("ServerVersion: {0}", connection.ServerVersion);
Console.WriteLine("State: {0}", connection.State);

SqlBatch API

Пример использования:

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        string str = "Data Source=(local);Initial Catalog=Northwind;"
        + "Integrated Security=SSPI;Encrypt=False";
        RunBatch(str);
    }

    static void RunBatch(string connString)
    {
        using var connection = new SqlConnection(connString);
        connection.Open();

        var batch = new SqlBatch(connection);

        const int count = 10;
        const string parameterName = "parameter";
        for (int i = 0; i < count; i++)
        {
            var batchCommand = new SqlBatchCommand($"SELECT @{parameterName} as value");
            batchCommand.Parameters.Add(new SqlParameter(parameterName, i));
            batch.BatchCommands.Add(batchCommand);
        }

        // Optionally Prepare
        batch.Prepare();

        var results = new List<int>(count);
        using (SqlDataReader reader = batch.ExecuteReader())
        {
            do
            {
                while (reader.Read())
                {
                    results.Add(reader.GetFieldValue<int>(0));
                }
            } while (reader.NextResult());
        }
        Console.WriteLine(string.Join(", ", results));
    }
}

5.2 Поддержка целевой платформы

• Платформа .NET Framework 4.6.2+ (Windows x86, Windows x64)
• .NET 6.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Полные заметки о выпуске, включая зависимости, доступны в репозитории GitHub: Заметки о выпуске 5.2.

Заметки о выпуске для версии 5.1

Критические изменения в версии 5.1

• Удалена поддержка .NET Core 3.1. #1704#1823

Новые возможности в версии 5.1

• Добавлена поддержка для DateOnly и TimeOnly значений, а также для SqlParameter и GetFieldValue. #1813
• Добавлена поддержка TLS 1.3 для .NET Core и SNI Native. #1821
• Добавлен параметр ServerCertificate для Encrypt=Mandatory или Encrypt=Strict. #1822 Подробнее
• Добавлена поддержка Windows Arm64 при выборе платформы .NET Framework. #1828

Сертификат сервера

Значение ServerCertificate по умолчанию параметра подключения является пустой строкой. Если задано Encrypt, Mandatory или Strict, тогда ServerCertificate может использоваться для указания пути в файловой системе к файлу сертификата, чтобы сопоставить его с сертификатом TLS/SSL сервера. Указанный сертификат должен точно соответствовать, чтобы быть действительным. Допустимые форматы сертификатов: PEMи DERCER. Вот пример использования:

"Data Source=...;Encrypt=Strict;ServerCertificate=C:\\certificates\\server.cer"

5.1 Поддержка целевой платформы

• Платформа .NET Framework 4.6.2+ (Windows x86, Windows x64)
• .NET 6.0+ (Windows x86, Windows x64, Windows Arm64, Azure Resource Manager, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Полные заметки о выпуске, включая зависимости, доступны в репозитории GitHub: заметки о выпуске 5.1.

Заметки о выпуске для версии 5.0

Критические изменения в версии 5.0

• Удалена поддержка .NET Framework 4.6.1 № 1574
• Добавлена зависимость от пакета Microsoft.SqlServer.Server. Эта новая зависимость может привести к конфликтам пространства имен, если приложение ссылается на это пространство имен и по-прежнему имеет ссылки на пакеты (прямые или косвенные) в System.Data.SqlClient из .NET Core.
• Удалены классы из пространства имен Microsoft.Data.SqlClient.Server и заменены поддерживаемыми типами из пакета Microsoft.SqlServer.Server.№ 1585. Затронутые классы и перечисления:
  • Microsoft.Data.SqlClient.Server.IBinarySerialize —> Microsoft.SqlServer.Server.IBinarySerialize
  • Microsoft.Data.SqlClient.Server.InvalidUdtException —> Microsoft.SqlServer.Server.InvalidUdtException
  • Microsoft.Data.SqlClient.Server.SqlFacetAttribute —> Microsoft.SqlServer.Server.SqlFacetAttribute
  • Microsoft.Data.SqlClient.Server.SqlFunctionAttribute —> Microsoft.SqlServer.Server.SqlFunctionAttribute
  • Microsoft.Data.SqlClient.Server.SqlMethodAttribute —> Microsoft.SqlServer.Server.SqlMethodAttribute
  • Microsoft.Data.SqlClient.Server.SqlUserDefinedAggregateAttribute —> Microsoft.SqlServer.Server.SqlUserDefinedAggregateAttribute
  • Microsoft.Data.SqlClient.Server.SqlUserDefinedTypeAttribute —> Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute
  • (перечисление) Microsoft.Data.SqlClient.Server.DataAccessKind —> Microsoft.SqlServer.Server.DataAccessKind
  • (перечисление) Microsoft.Data.SqlClient.Server.Format —> Microsoft.SqlServer.Server.Format
  • (перечисление) Microsoft.Data.SqlClient.Server.SystemDataAccessKind —> Microsoft.SqlServer.Server.SystemDataAccessKind

Новые возможности в версии 5.0

• Добавлена поддержка TDS8. Чтобы использовать TDS 8, пользователи должны указать Encrypt=Strict в строке подключения. #1608Подробнее
• Добавлена поддержка указания SPN сервера и SPN резервного сервера в подключении. #1607Подробнее
• Добавлена поддержка псевдонимов при нацеливании на .NET Core в Windows. #1588Подробнее
• Добавлен SqlDataSourceEnumerator. № 1430, Подробнее
• Добавлен новый переключатель AppContext для подавления небезопасных предупреждений TLS. № 1457, Подробнее

Расширенная безопасность TDS 8.0

Чтобы использовать TDS 8.0, укажите Encrypt=Strict в строке подключения. Строгий режим отключает TrustServerCertificate (всегда обрабатывается как False в строгом режиме). HostNameInCertificate добавлен для помощи в некоторых сценариях строгого режима. TDS 8.0 начинает и продолжает все серверные сообщения внутри безопасного зашифрованного TLS-подключения.

Добавлены новые значения шифрования для уточнения поведения шифрования подключений. Encrypt=Mandatory эквивалентно Encrypt=True и шифрует соединения во время согласования соединения TDS. Encrypt=Optional эквивалентно Encrypt=False и шифрует соединение только в том случае, если сервер сообщает клиенту, что шифрование требуется во время согласования подключения TDS.

Дополнительные сведения о шифровании подключений к серверу см. в разделе "Шифрование и проверка сертификатов" в Microsoft.Data.SqlClient.

HostNameInCertificate можно указать в строке подключения при использовании псевдонимов для подключения с шифрованием к серверу, у которого сертификат имеет другое имя или альтернативное имя субъектa, отличающееся от имени, используемого клиентом для идентификации сервера (например, псевдонимы DNS). Пример использования: HostNameInCertificate=MyDnsAliasName

SPN сервера

При подключении в среде с уникальной топографией домена/леса могут быть особые требования к служебным УИД сервера. Параметры строки подключения ServerSPN/Server SPN и FailoverServerSPN/Failover Server SPN могут быть использованы для переопределения автоматически сгенерированных SPN-серверов, которые используются в процессе интегрированной аутентификации в доменной среде.

Поддержка псевдонимов SQL

Пользователи могут настраивать псевдонимы с помощью диспетчера конфигурации SQL Server. Эти псевдонимы хранятся в реестре Windows и уже поддерживаются при выборе платформы .NET Framework. Этот выпуск обеспечивает поддержку псевдонимов при нацеливании на .NET или .NET Core в Windows.

Поддержка перечислителя источников данных SQL

Предоставляет механизм перечисления всех доступных экземпляров SQL Server в локальной сети.

using Microsoft.Data.Sql;
static void Main()
  {
    // Retrieve the enumerator instance and then the data.
    SqlDataSourceEnumerator instance =
      SqlDataSourceEnumerator.Instance;
    System.Data.DataTable table = instance.GetDataSources();

    // Display the contents of the table.
    DisplayData(table);

    Console.WriteLine("Press any key to continue.");
    Console.ReadKey();
  }

  private static void DisplayData(System.Data.DataTable table)
  {
    foreach (System.Data.DataRow row in table.Rows)
    {
      foreach (System.Data.DataColumn col in table.Columns)
      {
        Console.WriteLine("{0} = {1}", col.ColumnName, row[col]);
      }
      Console.WriteLine("============================");
    }
  }

Отключение предупреждений о небезопасном протоколе TLS

На консоль выводится предупреждение системы безопасности, если для согласования с сервером используется версия TLS ниже 1.2. Это предупреждение можно подавить при подключении к SQL, включив следующий переключатель AppContext при запуске приложения, если Encrypt = false:

Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning

Поддержка целевой платформы 5.0

• Платформа .NET Framework 4.6.2+ (Windows x86, Windows x64)
• .NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Полные заметки о выпуске, в том числе зависимости, доступны в репозитории GitHub: Заметки о выпуске 5.0.

Заметки к выпуску версии 4.1

Полные заметки о выпуске, в том числе зависимости, доступны в репозитории GitHub: заметки о выпуске 4.1.

Новые возможности в версии 4.1

Ввод протокола аттестации None

В строке подключения разрешен новый протокол аттестации None. Этот протокол позволяет пользователям отказаться от аттестации для VBS анклавов. Если выбран этот протокол, свойство URL-адреса аттестации анклава становится необязательным.

Пример строки подключения:

//Attestation protocol NONE with no URL
"Data Source = {server}; Initial Catalog = {db}; Column Encryption Setting = Enabled; Attestation Protocol = None;"

Поддержка целевой платформы 4.1

• .NET Framework 4.6.1+ (Windows x86, Windows x64)
• .NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Заметки о выпуске для версии 4.0

Полные заметки о выпуске, в том числе зависимости, доступны в репозитории GitHub: заметки о выпуске 4.0.

Критические изменения в версии 4.0

• Изменено свойство строки подключения Encrypt на true по умолчанию. № 1210Подробнее
• Теперь драйвер выдает SqlException в качестве замены AggregateException для режимов проверки подлинности Active Directory. № 1213
• Удалено устаревшее свойство подключения Asynchronous Processingиз платформы .NET Framework. № 1148
• Удален переключатель безопасности Configurable Retry Logic. № 1254Подробнее
• Прекращена поддержка .NET Core 2.1 № 1272
• [платформа .NET Framework] Исключение не возникает, если пользовательский идентификатор указан в строке подключения при использовании Active Directory Integrated проверки подлинности #1359

Новые возможности в версии 4.0

Значение параметра Encrypt по умолчанию заменено на true

Значение параметра подключения Encrypt по умолчанию изменено с false на true. В связи с растущим использованием облачных баз данных и необходимостью обеспечения безопасности этих подключений пришло время для изменения, нарушающего обратную совместимость.

Обеспечьте сбой подключения, если требуется шифрование

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

Переключение контекста приложения для использования системных протоколов по умолчанию

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

Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols

Включение оптимизированной привязки параметра

Microsoft.Data.SqlClient представляет новый API SqlCommandEnableOptimizedParameterBinding для повышения производительности запросов с большим количеством параметров. По умолчанию это свойство отключено. Если задано значение true, имена параметров не отправляются в экземпляр SQL Server при выполнении команды.

public class SqlCommand
{
    public bool EnableOptimizedParameterBinding { get; set; }
}

Удаление настраиваемого защитного механизма логики повторных попыток

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

Поддержка общего экземпляра SqlLocalDb

Теперь при использовании управляемого SNI поддерживаются общие экземпляры SqlLocalDb.

• Возможные сценарии:
  • (localdb)\. (подключается к экземпляру SqlLocalDb по умолчанию)
  • (localdb)\<named instance>
  • (localdb)\.\<shared instance name> (*недавно включенная поддержка)

Поддержка GetFieldValueAsync<T> и GetFieldValue<T> для типов XmlReader, TextReader, Stream

Типы XmlReader, TextReader, Stream теперь поддерживаются при использовании GetFieldValueAsync<T> и GetFieldValue<T>.

Пример использования:

using (SqlConnection connection = new SqlConnection(connectionString))
{
    using (SqlCommand command = new SqlCommand(query, connection))
    {
        connection.Open();
        using (SqlDataReader reader = await command.ExecuteReaderAsync())
        {
            if (await reader.ReadAsync())
            {
                using (Stream stream = await reader.GetFieldValueAsync<Stream>(1))
                {
                    // Continue to read from stream
                }
            }
        }
    }
}

Поддержка целевой платформы 4.0

• .NET Framework 4.6.1+ (Windows x86, Windows x64)
• .NET Core 3.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Заметки о выпуске для версии 3.1

Полные заметки о выпуске, включая зависимости, доступны в репозитории GitHub: заметки о выпуске 3.1.

Новые возможности в версии 3.1

Введен протокол аттестации "Нет"

В строке подключения будет разрешено использование нового протокола аттестации None. Этот протокол позволит пользователям обойти процесс аттестации для VBS анклавов. Если выбран этот протокол, свойство URL-адреса аттестации анклава становится необязательным.

Пример строки подключения:

//Attestation protocol NONE with no URL
"Data Source = {server}; Initial Catalog = {db}; Column Encryption Setting = Enabled; Attestation Protocol = None;"

Поддержка целевой платформы

• .NET Framework 4.6.1+ (Windows x86, Windows x64)
• .NET Core 3.1+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows ARM64, Windows ARM, Linux, macOS)

Заметки о релизе версии 3.0

Полные заметки о выпуске, в том числе зависимости, доступны в репозитории GitHub: заметки о выпуске 3.0.

Критические изменения в версии 3.0

• Минимальная поддерживаемая версия платформы .NET Framework повысилась до версии 4.6.1. Версия .NET Framework 4.6.0 больше не поддерживается. #899
• Теперь для свойства подключения User Id требуется Client Id вместо Object Id для управляемого удостоверения, назначаемого пользователем#1010Дополнительные сведения
• SqlDataReader теперь возвращает значение DBNull вместо пустого массива byte[]. Устаревшее поведение можно включить, установив AppContext переключатель Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior#998Подробнее.

Новые возможности в версии 3.0

Настраиваемая логика повторных попыток

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

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableRetryLogic", true);

После включения параметра .NET AppContext политику логики повторных попыток можно определить отдельно для SqlConnection и SqlCommand или вместе с помощью различных параметров настройки.

В SqlConnection и SqlCommand введены новые публичные API для регистрации пользовательской реализации SqlRetryLogicBaseProvider:

public SqlConnection
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

public SqlCommand
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

Примеры использования API см. здесь:

using Microsoft.Data.SqlClient;

/// Detecting retriable exceptions is a vital part of the retry pattern.
/// Before applying retry logic it is important to investigate exceptions and choose a retry provider that best fits your scenario.
/// First, log your exceptions and find transient faults.
/// The purpose of this sample is to illustrate how to use this feature and the condition might not be realistic.
class RetryLogicSample
{
    private const string DefaultDB = "Northwind";
    private const string CnnStringFormat = "Server=localhost; Initial Catalog={0}; Integrated Security=true; pooling=false;";
    private const string DropDatabaseFormat = "DROP DATABASE {0}";

    // For general use
    private static SqlConnection s_generalConnection = new SqlConnection(string.Format(CnnStringFormat, DefaultDB));

    static void Main(string[] args)
    {
        // 1. Define the retry logic parameters
        var options = new SqlRetryLogicOption()
        {
            NumberOfTries = 5,
            MaxTimeInterval = TimeSpan.FromSeconds(20),
            DeltaTime = TimeSpan.FromSeconds(1)
        };

        // 2. Create a retry provider
        var provider = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(options);

        // define the retrying event to report the execution attempts
        provider.Retrying += (object s, SqlRetryingEventArgs e) =>
            {
                int attempts = e.RetryCount + 1;
                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine($"attempt {attempts} - current delay time:{e.Delay} \n");
                Console.ForegroundColor = ConsoleColor.DarkGray;
                if (e.Exceptions[e.Exceptions.Count - 1] is SqlException ex)
                {
                    Console.WriteLine($"{ex.Number}-{ex.Message}\n");
                }
                else
                {
                    Console.WriteLine($"{e.Exceptions[e.Exceptions.Count - 1].Message}\n");
                }

                // It is not a good practice to do time-consuming tasks inside the retrying event which blocks the running task.
                // Use parallel programming patterns to mitigate it.
                if (e.RetryCount == provider.RetryLogic.NumberOfTries - 1)
                {
                    Console.WriteLine("This is the last chance to execute the command before throwing the exception.");
                    Console.WriteLine("Press Enter when you're ready:");
                    Console.ReadLine();
                    Console.WriteLine("continue ...");
                }
            };

        // Open the general connection.
        s_generalConnection.Open();

        try
        {
            // Assume the database is being created and other services are going to connect to it.
            RetryConnection(provider);
        }
        catch
        {
            // exception is thrown if connecting to the database isn't successful.
            throw;
        }
    }

    private static void ExecuteCommand(SqlConnection cn, string command)
    {
        using var cmd = cn.CreateCommand();
        cmd.CommandText = command;
        cmd.ExecuteNonQuery();
    }

    private static void RetryConnection(SqlRetryLogicBaseProvider provider)
    {
        // Change this if you already have a database with the same name in your database.
        string dbName = "Invalid_DB_Open";

        // Create a connection to an invalid database.
        using var cnn = new SqlConnection(string.Format(CnnStringFormat, dbName));
        // 3. Assign the `provider` to the connection
        cnn.RetryLogicProvider = provider;
        Console.WriteLine($"Connecting to the [{dbName}] ...");
        // Manually execute the following command in SSMS to create the invalid database while the SqlConnection is attempting to connect to it.
        // >> CREATE DATABASE Invalid_DB_Open;
        Console.WriteLine($"Manually, run the 'CREATE DATABASE {dbName};' in the SQL Server before exceeding the {provider.RetryLogic.NumberOfTries} attempts.");
        // the connection tries to connect to the database 5 times
        Console.WriteLine("The first attempt, before getting into the retry logic.");
        cnn.Open();
        Console.WriteLine($"Connected to the [{dbName}] successfully.");

        cnn.Close();

        // Drop it after test
        ExecuteCommand(s_generalConnection, string.Format(DropDatabaseFormat, dbName));
        Console.WriteLine($"The [{dbName}] is removed.");
    }
}

/// Detecting retriable exceptions is a vital part of the retry pattern.
/// Before applying retry logic it is important to investigate exceptions and choose a retry provider that best fits your scenario.
/// First, log your exceptions and find transient faults.
/// The purpose of this sample is to illustrate how to use this feature and the condition might not be realistic.

    private const string DefaultDB = "Northwind";
    private const string CnnStringFormat = "Server=localhost; Initial Catalog={0}; Integrated Security=true; pooling=false;";
    private const string DropDatabaseFormat = "DROP DATABASE {0}";
    private const string CreateDatabaseFormat = "CREATE DATABASE {0}";

    // For general use
    private static SqlConnection s_generalConnection = new SqlConnection(string.Format(CnnStringFormat, DefaultDB));

    static void Main(string[] args)
    {
        // 1. Define the retry logic parameters
        var options = new SqlRetryLogicOption()
        {
            NumberOfTries = 5,
            MaxTimeInterval = TimeSpan.FromSeconds(20),
            DeltaTime = TimeSpan.FromSeconds(1),
            AuthorizedSqlCondition = null,
            // error number 3702 : Cannot drop database "xxx" because it is currently in use.
            TransientErrors = new int[] {3702}
        };

        // 2. Create a retry provider
        var provider = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(options);

        // define the retrying event to report execution attempts
        provider.Retrying += (object s, SqlRetryingEventArgs e) =>
            {
                int attempts = e.RetryCount + 1;
                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine($"attempt {attempts} - current delay time:{e.Delay} \n");
                Console.ForegroundColor = ConsoleColor.DarkGray;
                if (e.Exceptions[e.Exceptions.Count - 1] is SqlException ex)
                {
                    Console.WriteLine($"{ex.Number}-{ex.Message}\n");
                }
                else
                {
                    Console.WriteLine($"{e.Exceptions[e.Exceptions.Count - 1].Message}\n");
                }

                // It is not good practice to do time-consuming tasks inside the retrying event which blocks the running task.
                // Use parallel programming patterns to mitigate it.
                if (e.RetryCount == provider.RetryLogic.NumberOfTries - 1)
                {
                    Console.WriteLine("This is the last chance to execute the command before throwing the exception.");
                    Console.WriteLine("Press Enter when you're ready:");
                    Console.ReadLine();
                    Console.WriteLine("continue ...");
                }
            };

        // Open a general connection.
        s_generalConnection.Open();

        try
        {
            // Assume the database is creating and other services are going to connect to it.
            RetryCommand(provider);
        }
        catch
        {
            s_generalConnection.Close();
            // exception is thrown if connecting to the database isn't successful.
            throw;
        }
        s_generalConnection.Close();
    }

    private static void ExecuteCommand(SqlConnection cn, string command)
    {
        using var cmd = cn.CreateCommand();
        cmd.CommandText = command;
        cmd.ExecuteNonQuery();
    }

    private static void FindActiveSessions(SqlConnection cnn, string dbName)
    {
        using var cmd = cnn.CreateCommand();
        cmd.CommandText = "DECLARE @query NVARCHAR(max) = '';" + Environment.NewLine +
            $"SELECT @query = @query + 'KILL ' + CAST(spid as varchar(50)) + ';' FROM sys.sysprocesses WHERE dbid = DB_ID('{dbName}')" + Environment.NewLine +
            "SELECT @query AS Active_sessions;";
        var reader = cmd.ExecuteReader();
        if (reader.Read())
        {
            Console.ForegroundColor = ConsoleColor.Green;
            Console.Write($">> Execute the '{reader.GetString(0)}' command in SQL Server to unblock the running task.");
            Console.ResetColor();
        }
        reader.Close();
    }

var RetryLogicOption = new SqlRetryLogicOption()
{
    NumberOfTries = 5,
    // Declare the error number 102 as a transient error to apply the retry logic when it occurs.
    TransientErrors = new int[] { 102 },
    // When a SqlCommand executes out of a transaction, 
    // the retry logic will apply if it contains a 'select' keyword.
    AuthorizedSqlCondition = x => string.IsNullOrEmpty(x)
            || Regex.IsMatch(x, @"\b(SELECT)\b", RegexOptions.IgnoreCase),
    DeltaTime = TimeSpan.FromSeconds(1),
    MaxTimeInterval = TimeSpan.FromSeconds(60),
    MinTimeInterval = TimeSpan.FromSeconds(3)
};

Кроме того, появились новые разделы конфигурации, позволяющие выполнить регистрацию в файлах конфигурации, не изменяя существующий код:

<section name="SqlConfigurableRetryLogicConnection"
            type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/>

<section name="SqlConfigurableRetryLogicCommand"
            type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/>

Ниже приведен простой пример использования новых разделов конфигурации в файлах конфигурации:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="SqlConfigurableRetryLogicConnection"
             type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/>
    <section name="SqlConfigurableRetryLogicCommand"
             type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/>

    <section name="AppContextSwitchOverrides"
             type="Microsoft.Data.SqlClient.AppContextSwitchOverridesSection, Microsoft.Data.SqlClient"/>
  </configSections>

  <!--Enable safety switch in .NET Core-->
  <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableRetryLogic=true"/>

  <!--Retry method for SqlConnection-->
  <SqlConfigurableRetryLogicConnection retryMethod ="CreateFixedRetryProvider" numberOfTries ="3" deltaTime ="00:00:10" maxTime ="00:00:30"
                                    transientErrors="40615" />

  <!--Retry method for SqlCommand containing SELECT queries-->
  <SqlConfigurableRetryLogicCommand retryMethod ="CreateIncrementalRetryProvider" numberOfTries ="5" deltaTime ="00:00:10" maxTime ="00:01:10"
                                    authorizedSqlCondition="\b(SELECT)\b" transientErrors="102, 4060, 0"/>
</configuration>

Кроме того, в приложении можно реализовать собственный поставщик базового класса SqlRetryLogicBaseProvider и зарегистрировать его с помощью SqlConnection/SqlCommand.

Счетчики событий

Для приложений, предназначенных для .NET Core 3.1 или более поздней версии и .NET Standard 2.1 или более поздней версии, теперь доступны указанные ниже счетчики.

Имя.	отображаемое имя	Описание
активные жесткие соединения	Фактическое число активных подключений к серверам	Количество подключений, открытых в настоящее время к серверам баз данных.
жесткие соединения	Фактическая скорость подключения к серверам	Количество подключений в секунду, открываемых серверам баз данных.
жесткие отключения	Фактическая скорость отключения от серверов	Количество отключений в секунду от серверов баз данных.
активные мягкие соединения	Активные подключения, полученные из пула подключений	Количество уже открытых подключений, используемых из пула подключений.
soft-connects	Скорость подключений, получаемых из пула подключений	Количество подключений в секунду, потребляемых из пула подключений.
мягкие отключения	Скорость возвращения подключений в пул подключений	Количество подключений в секунду, возвращаемое в пул подключений.
number-of-non-pooled-connections	Число подключений, не использующих пул подключений	Количество активных подключений, не помещаемых в пул.
количество объединенных подключений	Число подключений, управляемых пулом подключений	Инфраструктура пула подключений управляла количеством активных подключений.
число активных групп пулов подключений	Число уникальных активных строк подключения	Количество активных, уникальных групп пула подключений. Этот счетчик основан на числе уникальных строк подключения, найденных в AppDomain.
число-неактивных-групп-пула-соединений	Число уникальных строк подключения в очереди на удаление	Число уникальных групп пулов подключений, помеченных для обрезки. Этот счетчик основан на количестве уникальных строк подключения, найденных в домене приложения.
число-активных-пулов-соединений	Число активных пулов подключений	Общее число пулов соединений.
количество неактивных пулов подключений	Число неактивных пулов подключений	Количество неактивных пулов соединений, без недавней активности и ожидающих удаления.
number-of-active-connections	Число активных подключений.	Количество активных подключений, используемых в настоящее время.
количество-свободных-подключений	Число готовых подключений в пуле подключений	Количество открытых подключений, доступных в пулах подключений.
число стазисных подключений	Число подключений, ожидающих подготовки	Число подключений, ожидающих завершения действия и недоступных для использования приложением.
Количество-восстановленных-соединений	Число подключений, освобожденных в результате сборки мусора	Количество подключений, восстановленных через сборку мусора, где Close или Dispose не было вызвано приложением. Примечание. Если подключения не закрывать и не удалять явно, производительность может снижаться.

Эти счетчики можно использовать с глобальными средствами CLI .NET Core: dotnet-counters и dotnet-trace в Windows или Linux и PerfView в Windows. При этом в качестве имени поставщика следует указывать Microsoft.Data.SqlClient.EventSource. Дополнительные сведения см. в разделе Получение значений счетчиков событий.

dotnet-counters monitor Microsoft.Data.SqlClient.EventSource -p
PerfView /onlyProviders=*Microsoft.Data.SqlClient.EventSource:EventCounterIntervalSec=1 collect

Введение зависимости от удостоверений Azure

Microsoft.Data.SqlClient теперь зависит от библиотеки Azure.Identity для получения токенов для режимов проверки подлинности "Управляемое удостоверение Active Directory/MSI" и "Учетная запись службы Active Directory". Это нововведение обуславливает указанные ниже изменения в общедоступной контактной зоне.

• Критическое изменение

  Теперь для свойства подключения "Идентификатор пользователя" требуется "Идентификатор клиента" вместо "Идентификатор объекта" для "User-Assigned Управляемое удостоверение".

• Общедоступный API

  Новое открытое свойство только для чтения: SqlAuthenticationParameters.ConnectionTimeout

• Зависимость

  Azure.Identity 1.3.0

Усовершенствования трассировки событий в SNI.dll

Версии Microsoft.Data.SqlClient.SNI (зависимость платформы .NET Framework) и Microsoft.Data.SqlClient.SNI.runtime (зависимость .NET Core/Standard) обновлены до v3.0.0-preview1.21104.2. Трассировка событий в SNI.dll больше не активируется через клиентское приложение. Подписка сеанса на источник событий Microsoft.Data.SqlClient.EventSource с использованием таких инструментов, как xperf или perfview, вполне достаточна. Дополнительные сведения см. в разделе Поддержка трассировки событий в Native SNI.

Включить поведение null для версий строк

SqlDataReader возвращает значение DBNull вместо пустого массива byte[]. Чтобы включить устаревшее поведение, необходимо включить следующий параметр AppContext Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior при запуске приложения.

Поддержка аутентификации Microsoft Entra по умолчанию

Примечание.

Хотя Microsoft Entra ID — это новое имя Azure Active Directory (Azure AD), чтобы предотвратить нарушение существующих сред, Azure AD всё ещё используется в некоторых жёстко закодированных элементах, таких как элементы интерфейса, поставщики подключений, коды ошибок и командлеты. В этой статье два имени являются взаимозаменяемыми.

В этом выпуске введен новый метод проверки подлинности SQL: Active Directory по умолчанию. Этот режим проверки подлинности расширяет возможности проверки подлинности пользователей с помощью идентификатора Microsoft Entra, расширяя решения для входа в клиентную среду, Visual Studio Code, Visual Studio, Azure CLI и т. д.

В этом режиме проверки подлинности драйвер получает маркер, передавая DefaultAzureCredential из библиотеки удостоверений Azure для получения маркера доступа. Этот режим пытается использовать эти типы учетных данных для получения токена доступа в таком порядке.

• EnvironmentCredential
  • Включает проверку подлинности с Microsoft Entra ID с использованием client ID и секрета, либо имени пользователя и пароля. Эти данные настроены в следующих переменных среды: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_CERTIFICATE_PATH, AZURE_USERNAME, AZURE_PASSWORD (дополнительные сведения)
• ManagedIdentityCredential
  • Пытается выполнить проверку подлинности с помощью идентификатора Microsoft Entra с помощью управляемого удостоверения, назначенного среде развертывания. Идентификатор клиента "управляемой идентификации", назначаемой пользователем, считывается из свойства подключения "ИД пользователя".
• SharedTokenCacheCredential
  • Проверяет подлинность с использованием токенов в локальном кэше, совместно используемом приложениями Майкрософт.
• VisualStudioCredential
  • Включает проверку подлинности с Microsoft Entra ID, используя данные из Visual Studio
• VisualStudioCodeCredential
  • Позволяет настраивать аутентификацию с Microsoft Entra ID, используя данные из Visual Studio Code.
• AzureCliCredential
  • Включает проверку подлинности с помощью Microsoft Entra ID с помощью Azure CLI, чтобы получить токен доступа.

InteractiveBrowserCredential отключен в реализации драйвера "Active Directory Default", а "Active Directory Interactive" — это единственный доступный вариант для получения токена с помощью многофакторной аутентификации или интерактивной аутентификации.

На данный момент дополнительные параметры настройки недоступны.

Усовершенствования для регистрации пользовательских поставщиков хранилища главных ключей

Microsoft.Data.SqlClient теперь предлагает более широкий контроль над тем, где поставщики хранилища главных ключей доступны в приложении для повышения поддержки мультитенантных приложений и использования шифрования столбцов и расшифровки столбцов. Чтобы обеспечить регистрацию пользовательских поставщиков хранилища главных ключей в экземплярах SqlConnection и SqlCommand, введены следующие API:

public class SqlConnection
{
    public void RegisterColumnEncryptionKeyStoreProvidersOnConnection(IDictionary<string, SqlColumnEncryptionKeyStoreProvider> customProviders)
}
public class SqlCommand
{
    public void RegisterColumnEncryptionKeyStoreProvidersOnCommand(IDictionary<string, SqlColumnEncryptionKeyStoreProvider> customProviders)
}

Статический API для SqlConnection, SqlConnection.RegisterColumnEncryptionKeyStoreProviders, используемый для глобальной регистрации пользовательских поставщиков хранилища главных ключей, по-прежнему поддерживается. Глобальный кэш ключей шифрования столбцов применяется только к глобально зарегистрированным поставщикам.

Приоритет при регистрации поставщиков хранилища главных ключей для столбцов

Встроенные поставщики для хранения главных ключей столбцов, предусмотренные для Хранилища сертификатов Windows, Хранилища CNG и CSP, уже предварительно зарегистрированы. Поставщики не должны регистрироваться для экземпляров соединений или команд, если требуется использование одного из встроенных поставщиков хранилища основных ключей столбцов.

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

Ниже описывается, в какой очередности применяются эти три уровня регистрации:

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

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

Приоритет кэша ключей шифрования для столбцов

Драйвер не кэширует ключи шифрования столбцов (CEKs) для поставщиков пользовательских хранилищ ключей, зарегистрированных с помощью новых API уровня экземпляра. Для повышения производительности поставщики хранилища ключей должны реализовывать собственный кэш. Драйвер отключает локальный кэш ключей шифрования столбцов, реализованных настраиваемыми поставщиками хранилища ключей, если экземпляр поставщика хранилища ключей зарегистрирован в драйвере на глобальном уровне.

У базового класса SqlColumnEncryptionKeyStoreProvider также появился новый API для установки времени существования кэша:

public abstract class SqlColumnEncryptionKeyStoreProvider
{
    // The default value of Column Encryption Key Cache Time to Live is 0.
    // Provider's local cache is disabled for globally registered providers.
    // Custom key store provider implementation must include column encryption key cache to provide caching support to locally registered providers.
    public virtual TimeSpan? ColumnEncryptionKeyCacheTtl { get; set; } = new TimeSpan(0);
}

Настройки предпочтений IP-адреса

Новое свойство подключения IPAddressPreference используется для указания предпочтительного семейства IP-адресов для драйвера при установлении TCP-подключений. Если Transparent Network IP Resolution (в .NET Framework) или Multi Subnet Failover имеет значение true, этот параметр не действует. Для этого свойства используются три допустимых значения:

• IPv4First

  • Это значение по умолчанию. Сначала драйвер использует разрешенные IPv4-адреса. Если ни к одному из них не удается подключиться, он пытается использовать разрешенные адреса IPv6.

• IPv6First

  • Сначала драйвер использует разрешенные IPv6-адреса. Если ни один из них не может быть успешно подключен, он пытается разрешить адреса IPv4.

• UsePlatformDefault

  • Драйвер пробует IP-адреса в порядке, в котором они получены из ответа DNS-разрешения.

3.0 Поддержка целевой платформы

• .NET Framework 4.6.1+ (Windows x86, Windows x64)
• .NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Заметки о выпуске 2.1

Полные заметки о выпуске, в том числе зависимости, доступны в репозитории GitHub: заметки о выпуске 2.1.

Новые возможности в версии 2.1

Кроссплатформенная поддержка Always Encrypted

В Microsoft.Data.SqlClient версии 2.1 добавлена поддержка Always Encrypted для следующих платформ:

Поддержка Always Encrypted	Поддержка Always Encrypted с Secure Enclave	Целевая платформа	Версия Microsoft.Data.SqlClient	Операционная система
Да	Да	.NET Framework 4.6+	1.1.0 и выше	Windows
Да	Да	.NET Core 2.1+	2.1.0 и выше1	Windows, Linux, macOS
Да	Нет2	.NET Standard 2.0	2.1.0 и выше	Windows, Linux, macOS
Да	Да	.NET Standard 2.1 и выше	2.1.0 и выше	Windows, Linux, macOS

¹ В версиях Microsoft.Data.SqlClient ниже 2.1 функцию Always Encrypted поддерживает только Windows.
² Функция "Always Encrypted" с использованием безопасных анклавов не поддерживается в .NET Standard 2.0.

Аутентификация потока кода устройства Microsoft Entra

Microsoft.Data.SqlClient версии 2.1 поддерживает аутентификацию "Device Code Flow" с помощью MSAL.NET. Справочная документация. Поток предоставления авторизации устройства OAuth2.0

Пример строки подключения:

Server=<server>.database.windows.net; Authentication=Active Directory Device Code Flow; Database=Northwind;Encrypt=True

Следующий API позволяет настраивать механизм обратного вызова для потока кода устройства:

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetDeviceCodeFlowCallback(Func<DeviceCodeResult, Task> deviceCodeFlowCallbackMethod)
}

Проверка подлинности управляемого удостоверения Microsoft Entra

Microsoft.Data.SqlClient версии 2.1 предоставляет поддержку проверки подлинности Microsoft Entra с помощью управляемых удостоверений.

Режим проверки подлинности поддерживает такие ключевые слова:

• Active Directory Managed Identity (управляемое удостоверение Active Directory);
• Active Directory MSI (для совместимости с драйверами MS SQL).

Примеры строк подключения.

// For System Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory MSI; Encrypt=True; Initial Catalog={db};"

// For System Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory Managed Identity; Initial Catalog={db};"

// For User Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory MSI; Encrypt=True; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};"

// For User Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory Managed Identity; Encrypt=True; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};"

Улучшения интерактивной проверки подлинности Microsoft Entra

Microsoft.Data.SqlClient версии 2.1 добавляет следующие API для настройки процесса интерактивной аутентификации с помощью Microsoft Entra:

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework targeted applications only
    public void SetIWin32WindowFunc(Func<IWin32Window> iWin32WindowFunc);

    // For .NET Standard targeted applications only
    public void SetParentActivityOrWindowFunc(Func<object> parentActivityOrWindowFunc);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetAcquireAuthorizationCodeAsyncCallback(Func<Uri, Uri, CancellationToken, Task<Uri>> acquireAuthorizationCodeAsyncCallback);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void ClearUserTokenCache();
}

Раздел конфигурации SqlClientAuthenticationProviders

В Microsoft.Data.SqlClient версии 2.1 добавлен новый раздел конфигурации, SqlClientAuthenticationProviders (это клон существующего SqlAuthenticationProviders). Существующий раздел SqlAuthenticationProvidersконфигурации по-прежнему поддерживается для обратной совместимости при определении соответствующего типа.

Этот новый раздел позволяет включать в файлы конфигурации одновременно раздел SqlAuthenticationProviders для System.Data.SqlClient и раздел SqlClientAuthenticationProviders для Microsoft.Data.SqlClient.

Проверка подлинности Microsoft Entra с помощью идентификатора клиента приложения

В Microsoft.Data.SqlClient версии 2.1 добавлена поддержка передачи определяемого пользователем идентификатора клиента приложения в библиотеку проверки подлинности Майкрософт. Идентификатор клиента приложения используется при проверке подлинности с помощью идентификатора Microsoft Entra.

Также добавлены следующие API-интерфейсы:

1. В ActiveDirectoryAuthenticationProvider добавлен новый конструктор:

   Область применения: все платформы .NET (.NET Framework, .NET Core и .NET Standard)

   public ActiveDirectoryAuthenticationProvider(string applicationClientId)
   

   Использование:

   string APP_CLIENT_ID = "<GUID>";
   SqlAuthenticationProvider customAuthProvider = new ActiveDirectoryAuthenticationProvider(APP_CLIENT_ID);
   SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, customAuthProvider);
   
   using (SqlConnection sqlConnection = new SqlConnection("<connection_string>"))
   {
       sqlConnection.Open();
   }
   

2. Добавлено новое свойство конфигурации в SqlAuthenticationProviderConfigurationSection и SqlClientAuthenticationProviderConfigurationSection:

   Область применения: .NET Framework и .NET Core

   internal class SqlAuthenticationProviderConfigurationSection : ConfigurationSection
   {
       ...
       [ConfigurationProperty("applicationClientId", IsRequired = false)]
       public string ApplicationClientId => this["applicationClientId"] as string;
   }
   
   // Inheritance
   internal class SqlClientAuthenticationProviderConfigurationSection : SqlAuthenticationProviderConfigurationSection
   { ... }
   

   Использование:

   <configuration>
       <configSections>
           <section name="SqlClientAuthenticationProviders"
                            type="Microsoft.Data.SqlClient.SqlClientAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
       </configSections>
       <SqlClientAuthenticationProviders applicationClientId ="<GUID>" />
   </configuration>
   
   <!--or-->
   
   <configuration>
       <configSections>
           <section name="SqlAuthenticationProviders"
                            type="Microsoft.Data.SqlClient.SqlAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
       </configSections>
       <SqlAuthenticationProviders applicationClientId ="<GUID>" />
   </configuration>
   

Поддержка Классификации данных версии 2

В Microsoft.Data.SqlClient версии 2.1 добавлена поддержка информации о "Уровне конфиденциальности" в рамках Классификации данных. Доступны следующие API-интерфейсы:

public class SensitivityClassification
{
    public SensitivityRank SensitivityRank;
}

public class SensitivityProperty
{
    public SensitivityRank SensitivityRank;
}

public enum SensitivityRank
{
    NOT_DEFINED = -1,
    NONE = 0,
    LOW = 10,
    MEDIUM = 20,
    HIGH = 30,
    CRITICAL = 40
}

Идентификатор сеанса для активного SqlConnection

В Microsoft.Data.SqlClient версии 2.1 введено новое свойство SqlConnection для активного подключения: ServerProcessId.

public class SqlConnection
{
    // Returns the session ID (SPID) of the active connection.
    public int ServerProcessId;
}

Поддержка логирования трассировки в собственном SNI

Microsoft.Data.SqlClient версии 2.1 пополняет существующую реализацию SqlClientEventSource возможностью трассировки событий в SNI.dll. События должны собираться с использованием инструмента типа Xperf.

Трассировка может быть включена, отправив команду SqlClientEventSource , как показано ниже.

// Enables trace events:
EventSource.SendCommand(eventSource, (EventCommand)8192, null);

// Enables flow events:
EventSource.SendCommand(eventSource, (EventCommand)16384, null);

// Enables both trace and flow events:
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);

Свойство строки подключения "Command Timeout" (время ожидания команды)

В Microsoft.Data.SqlClient версии 2.1 введено новое свойство строки подключения "Command Timeout", которое позволяет переопределить стандартное время ожидания (30 секунд). Время ожидания отдельных команд можно переопределить с помощью CommandTimeout свойства в SqlCommand.

Примеры строк подключения.

"Server={serverURL}; Initial Catalog={db}; Encrypt=True; Integrated Security=true; Command Timeout=60"

Удаление символов из собственного SNI

Начиная с Microsoft.Data.SqlClient версии 2.1, мы удалили символы, добавленные в версии 2.0.0, из пакета NuGet Microsoft.Data.SqlClient.SNI.runtime (начиная с версии 2.1.1). Теперь общедоступные символы публикуются на сервере символов Майкрософт для BinSkim и других инструментов, которым требуется доступ к общедоступным символам.

Связывание символов с исходниками Microsoft.Data.SqlClient

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

2.1 Поддержка целевой платформы

• Платформа .NET Framework 4.6+ (Windows x86, Windows x64)
• .NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Заметки о выпуске версии 2.0

Полные заметки о выпуске, в том числе зависимости, доступны в репозитории GitHub: заметки о выпуске 2.0.

Критические изменения в версии 2.0

• Модификатор доступа для интерфейса поставщика анклава SqlColumnEncryptionEnclaveProvider изменен с public на internal.
• Константы в классе SqlClientMetaDataCollectionNames были обновлены, чтобы отражать изменения в SQL Server.
• Теперь драйвер выполняет проверку сертификата сервера, когда целевой СЕРВЕР SQL Server применяет шифрование TLS, которое используется по умолчанию для подключений Azure.
• SqlDataReader.GetSchemaTable() теперь возвращает пустой DataTable вместо null.
• Теперь драйвер выполняет округление по десятичной шкале, что соответствует поведению SQL Server. Для обратной совместимости предыдущее поведение усечения можно включить с помощью переключателя AppContext.
• Для приложений платформы .NET Framework, использующих Microsoft.Data.SqlClient, файлы SNI.dll, ранее загруженные в папки bin\x64 и bin\x86, теперь переименованы в Microsoft.Data.SqlClient.SNI.x64.dll и Microsoft.Data.SqlClient.SNI.x86.dll и загружаются в каталог bin.
• Новые синонимы свойств строки подключения заменяют старые свойства при получении строк подключения для согласованности с SqlConnectionStringBuilder. Подробнее

Новые возможности в версии 2.0

В Microsoft.Data.SqlClient 2.0 появились следующие новые возможности.

Устойчивость к сбоям DNS

Теперь драйвер кэширует IP-адреса из каждого успешного подключения к конечной точке SQL Server, поддерживающей эту функцию. Если во время попытки подключения возникает сбой разрешения DNS, драйвер пытается установить подключение с помощью кэшированного IP-адреса для этого сервера, если таковой существует.

Трассировка EventSource

В этом выпуске реализована поддержка записи журналов трассировки событий для отладки приложений. Чтобы отслеживать эти события, клиентские приложения должны прослушивать события от реализации EventSource в SqlClient.

Microsoft.Data.SqlClient.EventSource

Дополнительные сведения см. в разделе Включение трассировки событий в SqlClient.

Включение управляемых сетей в Windows

Новый параметр AppContext Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows позволяет использовать управляемую реализацию SNI в Windows для тестирования и отладки. Этот переключатель переключает поведение драйвера на использование управляемого SNI в .NET Core 2.1+ и .NET Standard 2.0+ проектов в Windows, устраняя все зависимости от собственных библиотек для библиотек Microsoft.Data.SqlClient.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);

Полный список доступных переключателей драйвера можно найти в разделе параметры AppContext в SqlClient.

Включить режим усечения десятичных знаков

Драйвер округляет масштаб десятичных данных по умолчанию, как и SQL Server. Для обратной совместимости можно задать для параметра AppContext параметр Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal значение true.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);

Новые синонимы свойств строки подключения

Для следующих свойств строки подключения были добавлены новые синонимы, чтобы избежать путаницы в свойствах, состоящих более чем из одного слова. Старые имена свойств по-прежнему поддерживаются для обратной совместимости. Но новые свойства строки подключения теперь включаются при её получении из SqlConnectionStringBuilder.

Существующее свойство строки подключения	Новый синоним
ApplicationIntent	Назначение приложения
КоличествоПопытокПодключения	Подключение счетчика повторных попыток
ConnectRetryInterval	Интервал повтора подключения
ПериодБлокировкиПула	Период блокировки пула
MultipleActiveResultSets	Несколько активных результирующих наборов данных
MultiSubnetFailover	Отработка отказа нескольких подсетей
Прозрачное разрешение IP-адресов в сети	Получение прозрачного сетевого IP-адреса
TrustServerCertificate	Надежный сертификат сервера

Свойство SqlBulkCopy RowsCopied

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

Переопределение открытия соединения

Поведение по умолчанию для SqlConnection.Open() можно переопределить, чтобы отключить 10-секундную задержку и автоматические попытки подключения, активируемые временными ошибками.

using(SqlConnection sqlConnection = new SqlConnection("Data Source=(local);Integrated Security=true;Initial Catalog=AdventureWorks;"))
{
    sqlConnection.Open(SqlConnectionOverrides.OpenWithoutRetry);
}

Примечание.

Это переопределение можно применить к SqlConnection.OpenAsync() начиная с Microsoft.Data.SqlClient версии 6.0.0.

Поддержка имени пользователя для интерактивного режима Active Directory

Имя пользователя может быть указано в строке подключения при использовании интерактивного режима аутентификации Microsoft Entra для платформ .NET Framework и .NET Core.

Задайте имя пользователя, используя идентификатор пользователя или свойство строки подключения UID.

"Server=<server name>; Database=<db name>; Authentication=Active Directory Interactive; User Id=<username>;Encrypt=True;"

Подсказки для упорядочивания для SqlBulkCopy

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

Изменения зависимостей SNI

Microsoft.Data.SqlClient (.NET Core и .NET Standard) в Windows теперь зависят от Microsoft.Data.SqlClient.SNI.runtime вместо runtime.native.System.Data.SqlClient.SNI. Новая зависимость добавляет поддержку платформы ARM вместе с уже поддерживаемыми платформами Arm64, x64 и x86 в Windows.

Поддержка целевой платформы 2.0

• Платформа .NET Framework 4.6+ (Windows x86, Windows x64)
• .NET Core 2.1+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Windows Arm64, Windows ARM, Linux, macOS)

Заметки о выпуске для версии 1.1

Полные заметки о выпуске, в том числе зависимости, доступны в репозитории GitHub: заметки о выпуске 1.1.

Новые возможности в версии 1.1

Always Encrypted с безопасными анклавами.

Always Encrypted доступна начиная с Microsoft SQL Server 2016. Безопасные анклавы доступны начиная с Microsoft SQL Server 2019. Чтобы использовать функцию анклава, строки подключения должны включать необходимый протокол аттестации и URL-адрес аттестации. Например:

"Attestation Protocol=HGS;Enclave Attestation Url=<attestation_url_for_HGS>"

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

• Использование Always Encrypted с поставщиком данных Microsoft .NET для SQL Server
• Руководство по разработке приложения .NET с помощью Always Encrypted с безопасными анклавами

1.1 Поддержка целевой платформы

• Платформа .NET Framework 4.6+ (Windows x86, Windows x64)
• .NET Core 2.1+ (Windows x86, Windows x64, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Linux, macOS)

Заметки о выпуске для версии 1.0

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

Полные заметки о выпуске, в том числе зависимости, доступны в репозитории GitHub: заметки о выпуске 1.0.

Новые возможности в версии 1.0

Новые возможности по сравнению с .NET Framework 4.7.2 System.Data.SqlClient

• Классификация данных. Доступна в Базе данных SQL Azure и Microsoft SQL Server 2019.

• Поддержка UTF-8. Доступна в Microsoft SQL Server 2019.

Новые возможности по сравнению с .NET Core 2.2 System.Data.SqlClient

• Классификация данных. Доступна в Базе данных SQL Azure и Microsoft SQL Server 2019.

• Поддержка UTF-8. Доступна в Microsoft SQL Server 2019.

• Аутентификация - режим аутентификации паролем через Active Directory.

Классификация данных

Классификация данных предоставляет новый набор API-интерфейсов, которые предоставляют сведения только для чтения о конфиденциальности и классификации данных для объектов, полученных через SqlDataReader, если базовый источник поддерживает эту функцию и содержит метаданные о конфиденциальности и классификации данных. См. пример приложения в разделе Обнаружение и классификация данных в SqlClient.

public class SqlDataReader
{
    public Microsoft.Data.SqlClient.DataClassification.SensitivityClassification SensitivityClassification
}

namespace Microsoft.Data.SqlClient.DataClassification
{
    public class ColumnSensitivity
    {
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.SensitivityProperty> SensitivityProperties
    }
    public class InformationType
    {
        public string Id
        public string Name
    }
    public class Label
    {
        public string Id
        public string Name
    }
    public class SensitivityClassification
    {
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.ColumnSensitivity> ColumnSensitivities
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.InformationType> InformationTypes
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.Label> Labels
    }
    public class SensitivityProperty
    {
        public Microsoft.Data.SqlClient.DataClassification.InformationType InformationType
        public Microsoft.Data.SqlClient.DataClassification.Label Label
    }
}

Поддержка UTF-8

Поддержка UTF-8 не требует изменения кода приложения. Эти изменения SqlClient оптимизируют связь между клиентом и сервером, когда сервер поддерживает UTF-8, а базовым параметром сортировки столбца является UTF-8. См. раздел о UTF-8 в статье Новые возможности SQL Server 2019.

Always Encrypted с безопасными анклавами.

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

• Использование функции Always Encrypted с провайдером данных .NET Framework для SQL Server
• Always Encrypted: защита конфиденциальных данных и хранение ключей шифрования в хранилище сертификатов Windows

Проверка подлинности

С помощью параметра строки подключения Аутентификация можно указать различные режимы проверки подлинности. Дополнительные сведения см. в документации по SqlAuthenticationMethod.

Поставщики пользовательского хранилища ключей, такие как поставщик Azure Key Vault, должны быть обновлены для поддержки Microsoft.Data.SqlClient. Аналогичным образом, поставщики анклава также должны быть обновлены для поддержки Microsoft.Data.SqlClient.

Always Encrypted поддерживается только для целевых объектов .NET Framework и .NET Core. Это не поддерживается для .NET Standard, потому что в .NET Standard отсутствуют определенные зависимости шифрования.

Поддержка целевой платформы 1.0

• Платформа .NET Framework 4.6+ (Windows x86, Windows x64)
• .NET Core 2.1+ (Windows x86, Windows x64, Linux, macOS)
• .NET Standard 2.0+ (Windows x86, Windows x64, Linux, macOS)