Microsoft. Data.SqlClient for SQL Server

Скачать ADO.NET

Microsoft.Data.SqlClient является официально поддерживаемым поставщиком данных .NET для SQL Server, База данных SQL Azure, Управляемый экземпляр SQL Azure, Azure Synapse Analytics и базы данных SQL в Microsoft Fabric. Он распространяется в виде пакета NuGet, развивается независимо от среды выполнения .NET и заменяет System.Data.SqlClient в новой разработке. Используйте его для открытия соединений, выполнения команд, обработки результатов, управления транзакциями, массовой загрузки данных и использования специфических для SQL Server функций из приложений .NET.

Выберите начальную точку

Производственные базовые показатели для Azure SQL

Используйте этот фрагмент как отправную точку для ориентированного на продакшн пути доступа к данным Azure SQL. Он считывает имена сервера и базы данных из IConfiguration, так что значения поступают от тех поставщиков конфигурации, которые подключены в хосте (appsettings.json, переменные среды, Конфигурация приложений Azure, параметры, хранящиеся в Key Vault, и так далее). Конфигурация сочетает безопасность транспортного уровня (TLS), управляемую идентификацию, устойчивость к простою, повторную попытку начального подключения через настраиваемую логику повторного тестирования (CRL) с структурированным логированием, командным повторным тестированием временных ошибок, срабатывающих во время запроса, и быстрым восстановлением группы отказов.

Для повышения безопасности и поддержки конфигурации между окружениями храните информацию о соединении вне вашего кода. В продакшене храните информацию о соединениях в системе конфигурации приложения и используйте Azure Key Vault для чувствительных значений. Дополнительные сведения см. в разделе Защита сведений о подключении.

Фрагмент кода C# в этой статье не содержит директив using и обёрток классов для краткости.

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

Этот фрагмент предназначен для любой конечной точки SQL ядро СУБД, настроенной для аутентификации Microsoft Entra: База данных SQL Azure, Управляемый экземпляр SQL Azure, базы данных SQL в Microsoft Fabric, а также SQL Server 2022 и более поздних версий на виртуальных машинах Azure или с поддержкой Azure Arc.

Encrypt = SqlConnectionEncryptOption.Strict выбирает шифрование TDS 8.0. Для этого требуется Microsoft. Data.SqlClient 5.0 и более поздние версии, а также сервер, поддерживающий TDS 8.0 (SQL Server 2022 и более поздние версии, База данных SQL Azure, Управляемый экземпляр SQL Azure и SQL Database in Microsoft Fabric). Используйте SqlConnectionEncryptOption.Mandatory при подключении к старым серверам.

ConnectRetryCount и ConnectRetryInterval обеспечивают устойчивость неактивного соединения: после успешного выполнения Open() драйвер автоматически повторно устанавливает разорванное неактивное соединение при следующей команде. Они не повторяют начальную попытку Open(). Повторные попытки начального подключения поступают от openRetry провайдера, назначенного к SqlConnection.RetryLogicProvider. Эти две особенности дополняют друг друга.

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

Укажите MultiSubnetFailover = true, если целевым объектом является База данных SQL Azure, Управляемый экземпляр SQL Azure, база данных SQL в Microsoft Fabric, прослушиватель группы доступности или экземпляр отказоустойчивого кластера. Он выбирает параллельный кодовый путь, который пытается сделать TCP-соединения со всеми разрешенными IP-адресами параллельно и использует первое успешное соединение, избегая медленного последовательного перехода по IP, который мог бы затормозить эти соединения. Для целей с одним IP-адресом эта настройка безопасна. MultiSubnetFailover не поддерживается, когда вы подключаетесь к именованому экземпляру, через протокол, отличный от TCP, или к экземпляру с более чем 64 IP-адресами. Также нельзя использовать его с зеркалированием базы данных, которое устарело во всех поддерживаемых версиях SQL Server. Вместо этого используйте группы доступности AlwaysOn. Для получения дополнительной информации см. разделы «Высокая доступность и восстановление после катастроф » и «Отключение разрешения IP прозрачной сети».

Если целевым объектом является База данных SQL Azure serverless с включённой автопаузой, увеличьте ConnectTimeout как минимум до 60 секунд. Автоматически приостановленная база данных возобновляется на первом Open(), и эта первая Open() может выйти из строя с ошибкой 40613 , пока база данных возобновляется. Ошибка 40613 есть в встроенном списке временных ошибок, поэтому openRetry попробуйте её повторить. Тайм-ауты на стороне клиента проявляются в виде ошибки -2, которой нет в этом списке, поэтому openRetry не поможет, если для Open() во время возобновления истечёт тайм-аут. Попытка личного контакта должна быть достаточно длинной, чтобы покрыть резюме. Для получения дополнительной информации смотрите разделы «Автопауза и автовозобновление».

Повторная попытка на уровне команды — это решение вызывающего, в зависимости от команды. Присоединяйте commandRetry к SqlCommand.RetryLogicProvider только если повторное выполнение команды безопасно: чтение, MERGE, защищённые естественным ключом, апсерты через хранимую процедуру и другие идемпотентные операции. Встроенный командный провайдер пропускает повторную попытку, когда транзакция активна, поэтому многокомпонентные транзакции должны повторяться с помощью кода приложения, который может повторно открыть транзакцию. Настройка TransientErrors заменяет встроенный список ошибок драйвера; чтобы расширить встроенную базовую линию, используйте SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 и более поздние).

Дополнительные сведения о каждой части этой конфигурации см. в следующей статье:

Ключевые особенности

  • Современная поддержка .NET: работает на текущих версиях .NET и .NET Framework. Для разбивки по версиям см . Жизненный цикл поддержки.
  • По умолчанию зашифровано: соединения с TLS-шифрованием и Encrypt=true по умолчанию. Установите Encrypt=Strict для шифрования TDS 8.0 в Microsoft.Data.SqlClient версии 5.0 и более поздних.
  • Аутентификация Microsoft Entra ID: подключения без пароля с использованием управляемого удостоверения, субъекта-службы, интерактивного потока, интегрированного потока, цепочки учетных данных по умолчанию и потока токена доступа.
  • Kerberos и NTLM: Интегрированная проверка подлинности Windows для локальной Active Directory и устаревших сценариев.
  • Always Encrypted: шифрование на стороне клиента для конфиденциальных столбцов с необязательными безопасными анклавами для операций на месте.
  • Массовое копирование: высокопроизводительные вставки с SqlBulkCopy.
  • Устойчивость соединения: встроенные повторные попытки соединения (ConnectRetryCount и ConnectRetryInterval) плюс настраиваемая логика повторных попыток для соединений и команд.
  • Богатые типы данных SQL Server: datetimeoffset, sql_variant, JSON, векторные, пространственные, XML и табличные параметры.
  • Диагностика: отслеживание источников событий, диагностические счётчики, статистика поставщиков и специальное руководство по устранению неполадок.

Get started

Статья Description
Начало работы с драйвером SqlClient Настройте проект, создайте базу данных, подключитесь, отправьте запросы и добавьте устойчивость соединений.
Общие сведения о драйвере SqlClient Узнайте, какое место Microsoft.Data.SqlClient занимает в ADO.NET.
Скачайте Microsoft. Data.SqlClient Установите пакет NuGet и найдите исходные версии.
Жизненный цикл поддержки Проверьте поддерживаемые версии драйверов и даты поддержки.
Microsoft. Data.SqlClient namespace Выполните миграцию с System.Data.SqlClient и изучите различия в пространствах имён.

Настройка и подключение

Статья Description
Подключитесь к источнику данных Открывайте и управляйте подключениями к SQL Server и Azure SQL.
строки подключения Настройте поведение сервера, базы данных, аутентификации, шифрования и подключения.
Шифрование и проверка сертификатов Настройте зашифрованные соединения и проверку сертификатов сервера.
Пул подключений SQL Server Эффективно используйте физические соединения.
События подключения Отвечайте на сообщения о состоянии соединения и информационные сообщения.

Аутентифицировать и защитить

Статья Description
Безопасность SQL Server Проверьте рекомендации по аутентификации, авторизации и безопасности приложений.
Аутентификация Microsoft Entra Подключайтесь к управляемой идентификации, принципу сервиса, паролям и интерактивным потокам.
Защита информации о соединениях Держите учетные данные и настройки соединения вне кода приложения.
Всегда зашифрованный Защитить чувствительные значения столбцов от системы базы данных.
Всегда зашифровано с безопасными анклавами Выполняйте сложные операции с зашифрованными данными с помощью защищённого анклава.

Получение и обновление данных

Статья Description
Команды и параметры Выполнять параметризованные операторы SQL и хранимые процедуры.
DataAdapters и DataReaders Передавайте наборы результатов в потоковом режиме или заполняйте автономные структуры данных.
Транзакции и параллелизм Используйте локальные и распределённые транзакции, а также контроли параллелизма.
Получить информацию о схеме базы данных Откройте для себя коллекции схем и ограничения.
Операции массового копирования Эффективно загружайте большие наборы данных с помощью SqlBulkCopy.
Параметры, возвращающие табличные значения Отправьте несколько строк в параметризованное выражение или хранимую процедуру.
Асинхронное программирование Используйте асинхронные соединения, команды и операции с данными.
Множественные активные наборы результатов (MARS) Чередуйте несколько пакетов в одном соединении.

Типы данных

Статья Description
Отображения типов данных ADO.NET Сопоставьте типичные типы выполнения языков с типами провайдера и SQL Server.
Типы данных SQL Server Работайте с значениями и System.Data.SqlTypes типами, специфичными для SQL Server.
Данные JSON Отправьте и получите тип данных SQL Serverjson.
Векторные данные Отправляйте и получайте векторные значения.
XML-данные Читать, записывать и параметризировать значения XML.
Бинарные и крупнозначительные данные Потоковая передача и обновление двоичных данных, FILESTREAM и данных большого размера.

Надёжность и диагностика

Статья Description
Настраиваемая логика повторных попыток Повторяйте попытки при временных сбоях подключения и выполнения команд с помощью ограниченных стратегий повторных попыток.
Высокий уровень доступности и аварийное восстановление Подключайтесь к группам доступности и партнёрам по отказу.
Диагностические счетчики Отслеживайте активные соединения, объединённые соединения и другие метрики драйверов.
Включить трассировку источников событий Фиксируйте детальные события водителя для диагностики.
Трассировка данных Отслеживайте операции ADO.NET и доступ к данным.
Руководство по устранению неполадок с SqlClient Диагностируйте распространённые проблемы с подключением и драйверами.
Уведомления о запросах Получайте уведомления при изменении результатов запросов.

Функции SQL Server

Статья Description
Функции SQL Server и ADO.NET Просмотрите функции, специфичные для SQL Server, доступные через SqlClient.
Локальная база данных Подключитесь к экземплярам SQL Server Express LocalDB.
Обнаружение и классификация данных Читайте метаданные классификации чувствительности из наборов результатов.

Справочник и ресурсы

Статья Description
Справочник по API Microsoft.Data.SqlClient Просмотрите справочник по API .NET для драйвера.
Переключатели AppContext Настройте совместимость и поведение безопасности.
Найдите дополнительную информацию о SqlClient Найдите исходный код, поддержку и ресурсы сообщества.

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

  • Last updated on