Варианты подключения для Microsoft. Data.SqlClient

В этой статье перечислены все ключевые слова строка подключения, которые принимает Microsoft. Data.SqlClient. Каждое ключевое слово также обладает свойством SqlConnectionStringBuilder совпадения. Для введения, распространённых шаблонов и правил разбора см. раздел Connection strings.

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

Настройка опций с помощью SqlConnectionStringBuilder

Начните с базовой строка подключения, которая содержит настройки сервера, базы данных и аутентификации. Затем настройте параметры, специфичные для нагрузки, через свойства строителя. Вкладки .NET Framework используют C# 7.3. Чтобы создать проект, который запускает эти образцы, см. раздел «Создать проект».

.NET

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

var builder = new SqlConnectionStringBuilder(connectionString)
{
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    CommandTimeout = 60,
    MaxPoolSize = 50,
};

await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();

await using var command = new SqlCommand("SELECT APP_NAME();", connection);
Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
Console.WriteLine($"Command timeout: {command.CommandTimeout}");

платформа .NET

using System;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task Main()
    {
        string connectionString =
            Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
            ?? throw new InvalidOperationException(
                "Set the SQL_CONNECTION_STRING environment variable.");

        var builder = new SqlConnectionStringBuilder(connectionString)
        {
            ApplicationName = "Orders.Worker",
            ConnectTimeout = 30,
            CommandTimeout = 60,
            MaxPoolSize = 50,
        };

        using (var connection = new SqlConnection(builder.ConnectionString))
        {
            await connection.OpenAsync();

            using (var command = new SqlCommand("SELECT APP_NAME();", connection))
            {
                Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
                Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
                Console.WriteLine($"Command timeout: {command.CommandTimeout}");
            }
        }
    }
}

Результат выглядит так:

APP_NAME(): Orders.Worker
Connection timeout: 30
Command timeout: 60

New SqlCommand по умолчанию заканчивается ключевым Command Timeout словом соединения.

Проверьте значения по умолчанию

Новый SqlConnectionStringBuilder пользователь показывает стандартные значения для каждого варианта. Эта программа выводит настройки по умолчанию, которые большинство приложений проверяют:

.NET

using Microsoft.Data.SqlClient;

var defaults = new SqlConnectionStringBuilder();

Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
Console.WriteLine($"Encrypt: {defaults.Encrypt}");
Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
Console.WriteLine($"Pooling: {defaults.Pooling}");
Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
Console.WriteLine($"Packet Size: {defaults.PacketSize}");
Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
Console.WriteLine($"Application Name: {defaults.ApplicationName}");
Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");

платформа .NET

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        var defaults = new SqlConnectionStringBuilder();

        Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
        Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
        Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
        Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
        Console.WriteLine($"Encrypt: {defaults.Encrypt}");
        Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
        Console.WriteLine($"Pooling: {defaults.Pooling}");
        Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
        Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
        Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
        Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
        Console.WriteLine($"Packet Size: {defaults.PacketSize}");
        Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
        Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
        Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
        Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
        Console.WriteLine($"Application Name: {defaults.ApplicationName}");
        Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
        Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");
    }
}

В .NET выход выглядит:

Connect Timeout: 15
Command Timeout: 30
Connect Retry Count: 1
Connect Retry Interval: 10
Encrypt: True
Trust Server Certificate: False
Pooling: True
Min Pool Size: 0
Max Pool Size: 100
Connection Idle Timeout: 300
Load Balance Timeout: 0
Packet Size: 8000
Multi Subnet Failover: False
IP Address Preference: IPv4First
Pool Blocking Period: Auto
Application Intent: ReadWrite
Application Name: Core Microsoft SqlClient Data Provider
Type System Version: Latest
Transaction Binding: Implicit Unbind

Encrypt: True — это Mandatory вариант. В .NET Framework по умолчанию имя приложения — Framework Microsoft SqlClient Data Provider.

Опции сервера и базы данных

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Data Source	Server, Address, Addr, Network Address	DataSource	Пустой	Сервер для подключения. Принимает имя хоста, host,port, host\instance(localdb)\instance, и префикс протокола илиtcp:.np: Для принятых форм см. Укажите сервер и базу данных.
Initial Catalog	Database	InitialCatalog	Пустой	База данных для использования после входа. Когда сервер пуст, сервер использует базовую базу данных входа.
AttachDbFilename	Extended Properties, Initial File Name	AttachDBFilename	Пустой	Полный путь основного файла базы данных для присоединения для SQL Server Express и LocalDB.
User Instance	None	UserInstance	false	Перенаправляет соединение на пользовательский экземпляр SQL Server Express. Для получения дополнительной информации см. экземпляры пользователей SQL Server Express.
Failover Partner	FailoverPartner	FailoverPartner	Пустой	Партнёр по зеркалированию базы данных попробовать, когда основной сервер недоступен. Зеркалирование базы данных не рекомендуется к использованию. Используйте группы по готовности для новых развертываний.
Current Language	Language	CurrentLanguage	Пустой	Название языка SQL Server для сессии, например us_english. Контролирует форматы дат и язык системных сообщений.

Опции идентификации приложений

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Application Name	App	ApplicationName	Core Microsoft SqlClient Data Provider	Имя, через которое сервер сообщает APP_NAME() и в просмотрах сессий. Используйте одно стабильное имя для каждой развернутой рабочей нагрузки. Разные значения создают отдельные пулы соединений.
Workstation ID	WorkstationID, WSID	WorkstationID	Имя локального компьютера	Имя клиентского компьютера, через которое сервер сообщает HOST_NAME().
Application Intent	ApplicationIntent	ApplicationIntent	ReadWrite	ReadOnly запрашивает маршрутизацию чтения с намерением, когда цель это поддерживает. Он не делает заявления только для чтения. Для получения дополнительной информации см. раздел «Высокая доступность и восстановление после катастроф».

Чтобы сообщить, какой фреймворк или инструмент открыл соединение, используйте свойство RegisteredApplication . В нем нет ключевого слова строка подключения. Для получения дополнительной информации см. раздел «Сообщить о идентификации приложения».

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

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Authentication	None	Authentication	Не указано	Метод проверки подлинности. Для принятых значений см. следующую таблицу.
Integrated Security	Trusted_Connection	IntegratedSecurity	false	true, yes, или sspi использует идентичность текущего процесса.
User ID	UID, User	UserID	Пустой	Имя входа в SQL или идентификатор пользователя или клиента Microsoft Entra ID, в зависимости от Authentication.
Password	PWD	Password	Пустой	Пароль или секрет клиента для методов, которые его принимают.
Persist Security Info	PersistSecurityInfo	PersistSecurityInfo	false	Когда false, драйвер удаляет пароль после SqlConnection.ConnectionString открытия соединения. Оставь это false.
Server SPN	ServerSPN	ServerSPN	Происходит от названия сервера	Переопределяет главное имя сервиса (SPN), используемое для интегрированной аутентификации на основном сервере.
Failover Partner SPN	FailoverPartnerSPN	FailoverPartnerSPN	Происходит от имени партнёра	Переопределяет SPN, используемый для интегрированной аутентификации с резервным партнёром.

Authentication принимает эти ценности. Конструктор записывает их без пробелов, например ActiveDirectoryDefault, и парсер принимает обе формы.

Value	Identity
Sql Password	Вход в SQL с User ID и Password.
Active Directory Default	Цепочка источников учетных данных, таких как переменные среды, управляемая идентификация и вход в инструменты разработчика.
Active Directory Managed Identity	Управляемая личность. Установите User ID на идентификатор клиента идентификатора, назначенного пользователем. Active Directory MSI — это псевдоним.
Active Directory Workload Identity	Идентификатор рабочей нагрузки Kubernetes.
Active Directory Service Principal	Приложение, установленное User ID на клиентский идентификатор и Password в секрет клиента.
Active Directory Interactive	Пользователь, который входит через подсказку браузера.
Active Directory Device Code Flow	Пользователь, который входит на другое устройство с помощью кода.
Active Directory Integrated	Авторизованный пользователь Windows — через федеративную или бесшовную конфигурацию единого входа.
Active Directory Password	Имя пользователя и пароль. Этот метод устарел. Используйте другой способ.

Методы Microsoft Entra ID нуждаются в пакетеMicrosoft.Data.SqlClient.Extensions.Azure. Для настройки и примеров см. аутентификация Microsoft Entra ID и аутентификация SQL Server.

Параметры шифрования

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Encrypt	None	Encrypt	Mandatory	Strict использует TDS 8.0 и всегда проверяет сертификат сервера. Mandatory, true, или yes шифрует соединение. Optional, false, или no шифрует всё соединение только тогда, когда это требуется серверу. Когда сервер поддерживает шифрование, но оно не требуется, шифруется только пакет входа.
Trust Server Certificate	TrustServerCertificate	TrustServerCertificate	false	true пропускает проверку сертификатов сервера. Игнорируется, когда Encrypt=Strict. Не используйте его в рабочей среде.
Host Name In Certificate	HostNameInCertificate	HostNameInCertificate	Пустой	Запасное название для проверки сертификатов. SqlClient сначала проверяет сертификат по имени сервера в Data Source. Проверяется Host Name In Certificate только если это имя не совпадает, поэтому неправильное значение не приводит к ошибке, если имя сервера уже совпадает. Сертификат не закрепляется. Чтобы получить конкретный сертификат, используйте Server Certificate. Он не меняет сетевой адрес и не обходит проверки цепочки доверия и истечения срока действия. Оставляйте его неустановленным, если имя сервера уже совпадает с сертификатом.
Server Certificate	ServerCertificate	ServerCertificate	Пустой	Путь файла PEM, DER или CER, который должен точно совпадать с сертификатом сервера. Водитель проверяет совпадение только при валидации сертификата, поэтому используйте его с Encrypt=Mandatory или Encrypt=Strict и Trust Server Certificate=false. Соответствующий файл заменяет проверку имени цепочки и хоста, поэтому он работает с самоподписанным сертификатом, которому клиент не доверяет.

Полные правила проверки см. раздел Шифрование и проверка сертификатов.

Всегда зашифрованные опции

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Column Encryption Setting	ColumnEncryption	ColumnEncryptionSetting	Disabled	Enabled включает Always Encrypted для соединения.
Attestation Protocol	None	AttestationProtocol	Не указано	Протокол аттестации анклава: AAS, HGS, или None.
Enclave Attestation Url	None	EnclaveAttestationUrl	Пустой	Конечная точка службы аттестации для Always Encrypted с защищёнными энклавыми.

Опции сети

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Multi Subnet Failover	MultiSubnetFailover	MultiSubnetFailover	false	Проверяет все IP-адреса, на которые разрешается имя сервера, параллельно. Используйте его для слушателей групп доступности и резервных кластеров, доступных через TCP. Зеркалирование базы данных не поддерживается. Именованные экземпляры зависят от реализации сети. Управляемая реализация, которую .NET использует на Linux, macOS, а также на Windows при активном управляемом сетевом подключении, поддерживает именованный экземпляр и параллельно отправляет запрос SQL Server Browser на каждый разрешённый адрес. Нативная реализация на Windows может отклонить именованный экземпляр с ошибкой SNI 48.
IP Address Preference	IPAddressPreference	IPAddressPreference	IPv4First	Порядок попыток решённого адресов: IPv4First, IPv6First, или UsePlatformDefault.
Packet Size	PacketSize	PacketSize	8000	Размер пакета Tabular Data Stream (TDS) в байтах — от 512 до 32 768.

Переключатель AppContext по всему процессу может изменить Multi Subnet Failover параметр по умолчанию на true. Для получения дополнительной информации см. раздел AppContext Switches в SqlClient.

Варианты тайм-аута

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Connect Timeout	Connection Timeout, ConnectTimeout, Timeout	ConnectTimeout	15	Секунды на ожидание соединения, включая ожидание пула, когда пул заполнен. 0 ждёт бесконечно.
Command Timeout	None	CommandTimeout	30	По умолчанию CommandTimeout команды, созданные на соединении, — за секунды. 0 ждёт бесконечно.

Connect Timeout не ограничивает выполнение запросов. Command Timeout Это не ограничивает логин или ожидание пулового соединения. Передайте A CancellationToken на асинхронные вызовы, чтобы звонящий мог прекратить ожидание до истечения любого из таймаутов.

Варианты восстановления соединения

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Connect Retry Count	ConnectRetryCount	ConnectRetryCount	1	Повторные попытки после квалификационного временного отказа при первом открытии и при восстановлении сломанного холостого соединения. 0 Отключает повторные попытки. Допустимые значения — от 0 до 255.
Connect Retry Interval	ConnectRetryInterval	ConnectRetryInterval	10	Секунды между попытками повтора. Допустимые значения — от 1 до 60.

Когда Connect Retry Count есть 1, что является по умолчанию, драйвер использует 2 для Azure SQL-конечных точек и 5 для серверных SQL-пулов Azure Synapse Analytics при восстановлении сломанного простоя соединения. В первом открытии используется установленное значение, поэтому по умолчанию разрешается повторная попытка на каждой конечной точке. Драйвер использует любое другое значение, установленное в обоих случаях.

Эти ключевые слова не повторяют команду, которая не работает во время запуска. Чтобы пропустить встроенную повторную попытку для одного открытого, вызовите Open перегрузку с OpenWithoutRetry. Для пользовательских политик см. Настраиваемая логика повторного попытки. Повторяйте команду только тогда, когда повторять её безопасно.

Варианты объединения

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Pooling	None	Pooling	true	Повторно использует физические соединения для сопоставления строк соединений.
Min Pool Size	None	MinPoolSize	0	Физические соединения, которые пул оставляет открытыми после их создания.
Max Pool Size	None	MaxPoolSize	100	Больше всего физических связей в одном пуле. Должно быть не менее 1.
Connection Idle Timeout	None	IdleTimeout	300	Секунды, когда соединение может остаться без работы в бассейне до того, как пул его закроет. 0 Отключает истечение на холостом ходу. Применяется только тогда, когда переключатель Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior AppContext — .false По умолчанию, это true.
Load Balance Timeout	Connection Lifetime	LoadBalanceTimeout	0	Максимальный возраст в секундах соединения возвращался в пул. Старое соединение закрыто. 0 Выключает лимит.
Pool Blocking Period	PoolBlockingPeriod	PoolBlockingPeriod	Auto	Независимо от того, будет ли пул повторно выбросить кэшированный сбой входа на короткий период: Auto, AlwaysBlock, или NeverBlock. Autoотключает блокирование для Azure SQL endpoints.

Каждая отдельная строка подключения получает свой собственный пул. Для ключей пула, очистки и времени простоя см. раздел SQL Server connection pooling.

Опции транзакций и сессий

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Enlist	None	Enlist	true	Зачисляет соединение в окружающую System.Transactions транзакцию при её открытии.
Transaction Binding	None	TransactionBinding	Implicit Unbind	Implicit Unbind отключает соединение при завершении зарегистрированной транзакции. Explicit Unbind Держит его подключённым, пока соединение не закроется или код не отсоединит.
Multiple Active Result Sets	MultipleActiveResultSets	MultipleActiveResultSets	false	Разрешает более одного активного пакета на одном соединении.
Type System Version	None	TypeSystemVersion	Latest	Серверная система, которую показывает драйвер. Принимает Latest, SQL Server 2012, SQL Server 2008, и SQL Server 2005. Оставьте это на Latest.
Replication	None	Replication	false	Идентифицирует соединение как репликационное соединение.

Только опции для .NET Framework

Эти ключевые слова принимаются только в .NET Framework. В .NET строитель бросает NotSupportedException и SqlConnection бросает ArgumentException.

Keyword	Aliases	Недвижимость застройщика	По умолчанию	Description
Network Library	Net, Network	NetworkLibrary	Пустой	Сетевая библиотека. Не комбинируйте его с префиксом a tcp: или np: в Data Source, потому что соединение не работает. В .NET — префикс Data Source с tcp: или np: вместо этого.
Connection Reset	None	ConnectionReset	true	Obsolete.
Transparent Network IP Resolution	TransparentNetworkIPResolution	TransparentNetworkIPResolution	true	Obsolete.

Неподдерживаемые ключевые слова

Keyword	Result
Context Connection	Context Connection=true бросает InvalidOperationException. Microsoft. Data.SqlClient не поддерживает контекстные соединения SQL CLR.
Asynchronous Processing	Бросает ArgumentException: Keyword not supported. Асинхронные методы работают без него.
Driver, Provider	Бросает ArgumentException: Keyword not supported. Эти ключевые слова относятся к ODBC и OLE DB.

Правила проверки

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

Строитель и соединение отвергают эти значения с ArgumentExceptionпомощью :

• Connect Timeout, Command Timeout, Load Balance Timeout, Connection Idle Timeout, , или Min Pool Size меньше 0.
• Max Pool Size Меньше 1.
• Packet Size вне 512 по 32 768.
• Connect Retry Count Вне 0 до 255.
• Connect Retry Interval Вне 1 по 60.
• Ключевое слово, которого нет в этой статье.

SqlConnection также отвергает эти значения с ArgumentException, хотя строитель их принимает:

• Type System Version Кроме Latest, SQL Server 2012, SQL Server 2008, или SQL Server 2005.
• Transaction Binding Кроме Implicit Unbind или Explicit Unbind.
• Значение длиннее предела TDS для Application Name, Current Language, Data Source, PasswordInitial CatalogUser IDFailover PartnerWorkstation IDили .AttachDBFilename

SqlConnection также отвергает эти комбинации с ArgumentException:

• Min Pool Size больше Max Pool Size.
• Failover Partner без Initial Catalog.
• Failover Partner с Multi Subnet Failover=true, User Instance=trueили Application Intent=ReadOnly.
• Authentication с Integrated Security=true.
• Passwordс Active Directory Integrated, Active Directory Interactive, Active Directory Managed Identity, Active Directory MSIActive Directory Default, , или Active Directory Workload Identity.
• User ID или Password с Active Directory Device Code Flow.

Просмотр изменений в опциях

Прежде чем менять опцию в производстве:

1. Запишите текущую строка подключения, версию драйвера, тип endpoint и проблему, которую решаете.
2. Меняйте по одному варианту за раз.
3. Установление тестового соединения, аутентификация, проверка сертификатов, пулирование, резервирование, отмена и выполнение запросов.
4. Измеряйте задержку соединения, ожидания пула и количество ошибок.
5. Подтвердите параметры на каждом развернутом экземпляре.

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

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

• строки подключения
• Построители строк подключения
• Подключитесь к источнику данных
• Пул подключений SQL Server
• Шифрование и проверка сертификатов