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-приложений.

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

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

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

  • Защита транспортного уровня (TLS).
  • Управляемая идентификация.
  • Устойчивость к разрывам неактивных соединений.
  • Повторная попытка начального подключения через настраиваемую логику повторных попыток (CRL) со структурированным логированием.
  • Повторная попытка на уровне команды для временных ошибок, возникающих во время запроса.
  • Быстрое восстановление группы отработки отказа.
  • Асинхронные вызовы, принимающие токен отмены.

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

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

Фрагмент предполагает проект, ориентированный на .NET 8 или более поздние версии, и ссылается на пакеты Microsoft.Data.SqlClient и Microsoft.Data.SqlClient.Extensions.Azure версии 7.1.1. Хост, такой как .NET Generic Host или ASP.NET Core, предоставляет ILogger и IConfiguration, а конфигурация — имя сервера в Sql:Server и имя базы данных в Sql:Database.

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    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 (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);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

Метод возвращает имя базы данных, к которой он подключён, и записывает Connected to database <database>в журнал. Когда происходит повторная попытка, также регистрируется одно предупреждение для каждой такой попытки с указанием исключения, которое её вызвало.

Как работает каждая часть фрагмента:

  • Целевые объекты: любая конечная точка подключения SQL ядро СУБД, настроенная для аутентификации Microsoft Entra: База данных SQL Azure, Управляемый экземпляр SQL Azure, база данных SQL в Microsoft Fabric и SQL Server 2022 и более поздних версий на виртуальных машинах Azure или с поддержкой Azure Arc.
  • Encrypt = SqlConnectionEncryptOption.Strict: Выбор шифрования TDS 8.0. Для этого требуется SQL Server 2022 и более поздние версии, База данных SQL Azure, Управляемый экземпляр SQL Azure или SQL база данных в Microsoft Fabric. Используйте SqlConnectionEncryptOption.Mandatory для старых серверов.
  • ActiveDirectoryManagedIdentity: Работает только там, где доступна управляемая идентичность, например Служба приложений Azure, Функции Azure или виртуальная машина Azure. Для локальной разработки используйте SqlAuthenticationMethod.ActiveDirectoryDefault, который пытается выполнить аутентификацию через Azure CLI, вход в Visual Studio и другие источники учетных данных. Не используйте это в продакшене, потому что проверка каждого источника замедляет подключение. Для получения дополнительной информации см. раздел «Использовать аутентификацию по умолчанию».
  • MultiSubnetFailover = true: Пытается параллельно установить TCP-соединения ко всем IP-адресам, полученным при разрешении имени, и использует первое успешное соединение, избегая медленного последовательного перебора IP-адресов. Настройте его для База данных SQL Azure, Управляемый экземпляр SQL Azure, SQL Database в Microsoft Fabric, слушателей групп доступности и экземпляров отказоустойчивого кластера. Это безопасно для целевых систем с одним IP-адресом. Он не поддерживается для именованных экземпляров, протоколов, отличных от TCP, экземпляров с более чем 64 IP-адресами или зеркалирования базы данных, использование которого не рекомендуется. Вместо этого используйте группы доступности AlwaysOn. Для получения дополнительной информации см. разделы «Высокая доступность и восстановление после катастроф » и «Отключение разрешения IP прозрачной сети».
  • ConnectRetryCount = 3 и ConnectRetryInterval = 10: Драйвер повторно пытается выполнить операцию при временных сбоях, подпадающих под условия, во время Open(), а при следующей команде повторно устанавливает разорванное неактивное соединение. Количество по умолчанию — 1. Три попытки с интервалом в 10 секунд в сумме длятся дольше, чем более длительная перенастройка или аварийное переключение. Драйвер повышает 1–2 только тогда, когда имя сервера заканчивается известным доменом Azure SQL, например .database.windows.net, поэтому пользовательский DNS-псевдоним получает 1.
  • openRetry: Назначенный SqlConnection.RetryLogicProvider, он добавляет экспоненциальную задержку для Open(). Драйвер останавливает внутренние повторные попытки по истечении ConnectTimeout, поэтому в худшем случае до того, как OpenAsync сгенерирует исключение, будет выполнено пять попыток длительностью до 30 секунд каждая, плюс задержка между повторами. Каждая попытка повторного подключения в режиме простоя также запускает полную openRetry политику, и когда эта политика исчерпает свои повторные попытки, восстановление в простое заканчивается.
  • Безсерверная автопауза: Для База данных SQL Azure serverless увеличьте ConnectTimeout как минимум до 60 секунд. Первый Open() может завершиться с ошибкой 40613 во время возобновления базы данных, и openRetry повторяет попытку. Тайм-аут на стороне клиента проявляется как ошибка -2, для которой не выполняется повторная попытка, поэтому каждая попытка подключения должна длиться дольше возобновления. Для получения дополнительной информации смотрите разделы «Автопауза и автовозобновление».
  • commandRetry: Прикрепляйте его к SqlCommand.RetryLogicProvider только если безопасно повторно выполнять команду: операции чтения, MERGE защищённые естественным ключом, upsert-операции через сохранённую процедуру и другие идемпотентные операции. Он пропускает повторную попытку внутри транзакции, поэтому код приложения должен повторно выполнять многооператорные транзакции. ExecuteReader и ExecuteScalar повторяют попытку только для ошибок, возвращённых до начала первого набора результатов. ExecuteNonQuery повторно выполняет весь вызов.
  • Список временных ошибок: Настройка TransientErrors заменяет встроенный список. Чтобы вместо этого расширить его, используйте SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft.Data.SqlClient 7.0 и более поздних версий).
  • Retrying Событие: Retrying срабатывает перед каждой повторной попыткой с учетом количества повторных попыток, следующей задержки и исключений на данный момент. Направьте его в ILogger или в ваш телеметрический конвейер.
  • Исключения: метод не перехватывает исключения. Истощённый провайдер выбрасывает AggregateException с исключением из каждой попытки. Не временная ошибка распространяется как исходное исключение. Вызывающая сторона записывает его один раз вместе с остальной информацией запроса.
  • Отмена: CancellationToken останавливает ожидание поставщика между повторными попытками. Он не прерывает ожидание ConnectRetryInterval водителя в рамках одной Open попытки. Для получения дополнительной информации см. раздел «Асинхронное программирование».
  • Время жизни провайдера: Фрагмент создаёт провайдеры повторных попыток при каждом вызове, чтобы оставаться самостоятельным. В приложении создайте их один раз и используйте повторно.

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

Изучите основные задачи доступа к данным

После подключения используйте эти статьи в порядке:

  1. Выполните команду для выбора формы набора результатов и запустите Transact-SQL (T-SQL).
  2. Настройте параметры для соответствия контракту базы данных.
  3. Получайте данные с помощью SqlDataReader для обработки строк и нескольких результатов.
  4. Модифицировать данные с помощью сохранённых процедур, использующих выходные параметры и возвращаемые значения.
  5. Используйте асинхронное программирование и отмену для добавления отмены со стороны вызывающего кода и ограниченных тайм-аутов.
  6. Обрабатывайте ошибки и сообщения до того, как добавлять повторные попытки или диагностику в продакшене.

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

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

Get started

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

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

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

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

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

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

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

Типы данных

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

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

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

Функции SQL Server

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

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

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

Запрашивание функции

Чтобы предложить новую функцию, создайте обращение в репозитории GitHub Microsoft.Data.SqlClient.

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

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