Microsoft. Data.SqlClient for SQL Server

Скачать ADO.NET

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

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

Выбор базы данных

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

Platform Setup
База данных SQL Azure Создайте базу данных с помощью портала Azure.
База данных SQL в Microsoft Fabric Загрузите примеры данных AdventureWorks.
SQL Server Установите SQL Server или используйте существующий экземпляр, доступный через TCP.
Контейнер SQL Server Создайте контейнер с помощью Docker, sqlcmd или расширения MSSQL для Visual Studio Code.

Производственные базовые показатели для 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
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // 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 применяются при первоначальном установлении соединения и восстановлении соединения после простоя. Когда значение ConnectRetryCount больше нуля, драйвер повторно пытается выполнить операции при подходящих временных сбоях в ходе Open(). После Open() успешного выполнения драйвер также использует эти настройки для повторного подключения оторванного холостого соединения при следующей команде. Провайдер SqlConnection.RetryLogicProvider, назначенный для openRetry, добавляет настраиваемую политику экспоненциальной задержки для Open(). Учитывайте оба уровня повторных попыток при установке количества повторных попыток и тайм-аута соединения.

Событие 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 Настройте проект, создайте базу данных, подключитесь, отправьте запросы и добавьте устойчивость соединений.
Архитектура ADO.NET с Microsoft. Data.SqlClient Узнайте, как Microsoft. Data.SqlClient реализует доступ к ADO.NET как подключённый, так и независимый от провайдера.
Установка, обновление и развертывание Microsoft. Data.SqlClient Установите пакеты NuGet, выберите релиз, обновите драйвер и подготовьте вывод развертывания.
Жизненный цикл поддержки Проверьте поддерживаемые версии драйверов и даты поддержки.
Переход с System.Data.SqlClient на Microsoft. Data.SqlClient Обновить ссылки на пакеты, пространства имён, конфигурацию и изменённое поведение драйверов.
Пространство имён Microsoft.Data.SqlClient и совместимость Понимайте связь драйвера с ADO.NET, System.Data.SqlClient, .NET и SQL Server.
Что нового в Microsoft. 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