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

Строка подключения Microsoft.Data.SqlClient — это список пар keyword=value, разделённых точкой с запятой. Передайте это SqlConnection или SqlConnectionStringBuilder:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

Строка подключения отвечает на четыре вопроса:

1. Какой сервер и базу данных использует приложение?
2. Под какой идентичностью работает приложение?
3. Как клиент проверяет сертификат сервера?
4. Какое поведение подключения требуется для рабочей нагрузки?

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

Выберите паттерн аутентификации

Используйте шаблон, который подходит для развертывания. Замените каждый заполнитель, например <server>, на ваше значение.

Environment	Рисунок	Строка соединения
SQL Server на Windows с доменной или локальной учетной записью Windows	Встроенная проверка подлинности Windows	Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
Приложение размещено в Azure и подключено к Azure SQL	Microsoft Entra ID управляемая идентичность	Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict
Рабочая станция разработчика с подключением к Azure SQL	Цепочка учетных данных по умолчанию Microsoft Entra ID	Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Рабочая станция разработчика, подключаемая к базе данных SQL в Microsoft Fabric	Цепочка учетных данных по умолчанию Microsoft Entra ID	Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
Интерактивный рабочий стол, подключаемый к Azure SQL	Интерактивная аутентификация Microsoft Entra ID	Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict
Среда, требующая SQL-аутентификации	Имя пользователя и пароль из секретного магазина	Server=<server>;Database=<database>;User ID=<user>;Password=<password>;Encrypt=true

Интегрированная аутентификация Windows подключается от имени процесса. Для настольных или консольных приложений обычно это авторизованный пользователь. Для веб-приложения или сервиса Windows это учетная запись пула приложений IIS или учетная запись службы. Имперсонация может изменить личность. Предоставьте логин и разрешения базы данных той учетной записи, которую ваше приложение действительно использует.

Эти три формы интегрированной аутентификации в Windows эквивалентны:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

Если в строке заданы Integrated Security=true и также заданы User ID и Password, драйвер использует проверку подлинности Windows и игнорирует имя пользователя и пароль.

Microsoft. Data.SqlClient 7.0 и более поздние версии требуют пакета, Microsoft.Data.SqlClient.Extensions.Azure соответствующего версии, для методов аутентификации Microsoft Entra ID, предоставляемых драйвером. Этот пакет не нужен, когда код приложения предоставляет токен доступа или функцию обратного вызова для токена доступа.

Для допустимых Authentication значений см. раздел «Опции аутентификации». Аутентификация также требует наличия пользователей базы данных, разрешений и настройки идентификации на сервере. Инструкции по настройке см. в статьях аутентификация Microsoft Entra ID и аутентификация SQL Server.

Укажите сервер и базу данных

Server и Database являются самыми читаемыми названиями ключевых слов. Строитель записывает их как их канонические эквиваленты Data Source , и Initial Catalog. Все четыре имени можно использовать в строке подключения.

Установите Server на одно из следующих значений:

Form	Example	Использовать
Имя хоста	Server=sql.example.com	Стандартный экземпляр на порте 1433.
Имя хоста и порт	Server=tcp:sql.example.com,1433	Конкретный TCP-порт. Разделяйте порт запятой, а не двоеточием.
Именованный экземпляр	Server=sql.example.com\SALES	Именованный экземпляр. Драйвер обращается к службе SQL Server Browser по UDP-порту 1434, чтобы узнать порт.
Локальный сервер	Server=(local) или Server=.	Стандартный экземпляр на локальном компьютере.
LocalDB	Server=(localdb)\MSSQLLocalDB	SQL Server Express LocalDB на Windows. Соединение не зашифровано, даже с Encrypt=Mandatory, и Encrypt=Strict не работает.
Именованный канал	Server=np:\\sql.example.com\pipe\sql\query	Соединение с именованным каналом в Windows.

Используйте tcp:, полностью квалифицированное имя хоста, и явный порт в продакшене. Используйте имя DNS, соответствующее серверному сертификату, а не IP-адресу, потому что проверка сертификата сравнивает имя сервера в строка подключения с именами в сертификате.

Когда вы подключаетесь к База данных SQL Azure с помощью SQL-аутентификации и используете имя пользователя в формате user@servername, часть servername должна совпадать с сервером в Server.

Для прослушивателя группы доступности или экземпляра отказоустойчивого кластера также ознакомьтесь с Multi Subnet Failoverнастройками соединения.

Настройка шифрования и проверки сертификатов

Encrypt Ключевое слово принимает следующие значения независимо от регистра:

Value	Значение конструктора	Meaning
Strict	Strict	Использует TDS 8.0. Шифрует соединение до входа и всегда проверяет сертификат сервера.
Mandatory, true, yes	True	Шифрует соединение. Это значение является значением по умолчанию.
Optional, false, no	False	Шифрует всё соединение только тогда, когда серверу требуется шифрование. Когда сервер поддерживает шифрование, но оно не требуется, шифрует только пакет входа.

Используйте Strict, когда сервер поддерживает TDS 8.0 и имеет сертификат, который клиент может проверить. База данных SQL Azure и SQL Database в Microsoft Fabric поддерживают это. Соединение LocalDB не шифруется, даже с Mandatory, и Strict не работает.

Значения Trust Server Certificate и Encrypt объединяются следующим образом:

Шифрование	Сертификат сервера доверия	Result
Optional	false	Когда сервер требует шифрования, всё соединение шифруется, и сертификат сервера должен пройти проверку. В противном случае соединение не устанавливается. Когда сервер поддерживает шифрование, но не требует его, шифруется только пакет входа, и драйвер не проверяет сертификат сервера, если соединение не использует AccessToken или AccessTokenCallback. Если сервер не поддерживает шифрование, ничего не шифруется.
Optional	true	Когда серверу требуется шифрование, всё соединение шифруется. Когда сервер поддерживает шифрование, но не требует его, шифруется только пакет входа. Драйвер не проверяет сертификат сервера.
Mandatory	false	Шифрование происходит только после проверки сертификата сервера. В противном случае соединение не будет установлено.
Mandatory	true	Шифрование всегда происходит, но драйвер не проверяет сертификат сервера.
Strict	Проигнорировано	Шифрование всегда происходит, и сертификат сервера должен быть проверен. В противном случае соединение завершается с ошибкой.

Не настраивайте Trust Server Certificate=true, чтобы исправить ошибку соединения в продакшене. Он шифрует канал, но не подтверждает подлинность сервера. Используйте это только в средах разработки, где доверенный сертификат недоступен.

Если имя сервера в Data Source не совпадает с сертификатом, установите Host Name In Certificate в значение имени из сертификата. SqlClient проверяет это только если имя сервера не совпадает, и не закрепляет сертификат. Чтобы принять только один конкретный сертификат, установите Server Certificate на путь к файлу PEM, DER или CER:

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

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

Использование пула соединений

Пулинг включен по умолчанию. Когда вы открываете SqlConnection, драйвер берет физическое соединение из пула, соответствующего этому соединению. Когда вы закрываете или освобождаете соединение, физическое соединение возвращается в пул, а не закрывается. Открытие из пула пропускает сетевое соединение, TLS-рукопожатие и вход.

Следуйте этим правилам:

• Откройте соединение непосредственно перед тем, как оно понадобится, и закройте его сразу после завершения с помощью using или await using. Соединение, которое не освобождено, остаётся выданным из пула, и пул соединений может исчерпаться.

• Создайте строка подключения один раз при запуске и используйте его повторно. Ключ пула включает точный текст строка подключения, поэтому другой порядок ключевых слов, синоним или значение для запроса, например идентификатор запроса или имя пользователя, создают отдельный пул. Сборщик пишет одну каноническую форму. Для получения дополнительной информации см. раздел «Используйте одну каноническую строку подключения».

• Ожидайте отдельный пул для каждой идентичности Windows в рамках интегрированной аутентификации, каждого SqlCredential экземпляра и каждого AccessToken значения. Используйте метод, предоставленный Authentication драйвером, или метод, повторно использующий AccessTokenCallback, вместо того чтобы устанавливать AccessToken на каждом соединении.

• Ищите соединения, которые не были закрыты, прежде чем повысить Max Pool Size, что по умолчанию составляет 100. Когда все соединения в пуле используются, Open ждёт до Connect Timeout и затем бросает InvalidOperationException:

  Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.
  

• Планируйте ресурсы сервера для каждого пула. Каждый процесс, или каждый домен приложения на .NET Framework, имеет свои собственные пулы. Количество соединений с сервером может достигать Max Pool Size, умноженного на число пулов в каждом процессе и на количество экземпляров приложения.

• Не устанавливайте Pooling=false, чтобы обойти проблему пула. Каждое открытие затем выполняет полный вход в систему.

Чтобы закрыть объединённые соединения, которые слишком долго остаются бездействующими, см. раздел «Ограничение времени простоя соединения». Для ключей пула, определения размера, очистки и транзакций см. раздел «Пул подключений SQL Server».

Отдельные настройки соединения и команд

Строка подключения определяет установление соединения и поведение сеанса. Команда управляет одной SQL-операцией.

Требование	Настроить на
Время, отведённое для установления связи или получения её из пула	Connect Timeout ключевое слово
Тайм-аут по умолчанию для команд для соединения	Command Timeout ключевое слово
Тайм-аут для одной команды	CommandTimeout
Отмена со стороны звонящего	CancellationToken передан асинхронным методам
Повторите политику для открытия соединения или выполнения команды	Настраиваемая логика повторного попытки на SqlConnection или SqlCommand

Более длинный тайм-аут — это не логика повторных попыток. Тайм-аут ограничивает длительность одного ожидания. Повтор означает ещё одну попытку, и он должен быть ограниченным и безопасным для повторения.

Сообщить об идентификаторе приложения

Application Name задаёт имя, которое сервер сообщает через APP_NAME(). Используйте одно стабильное имя для каждой развернутой нагрузки. Фреймворки и инструменты, открывающие соединения для приложения, также могут идентифицировать себя через свойство RegisteredApplication, которое не содержит ключевого слова строка подключения. Для получения дополнительной информации см. раздел «Указать удостоверение приложения».

Безопасно собирайте строки соединения

Используйте SqlConnectionStringBuilder, когда код добавляет или изменяет значение. Не присоединяйте недоверенный текст к строка подключения, потому что точка с запятой в этом тексте может добавить или заменить ключевое слово. Конструктор проверяет значения, сопоставляет синонимы с каноническими ключевыми словами и заключает каждое значение в кавычки, чтобы значение не могло добавить ключевые слова. Примеры см. Сборщики строк соединений.

Храните информацию о соединении вне кода

Загружайте строки соединения из системы конфигурации приложения. .NET-приложения обычно используют переменные среды, пользовательские секреты для локальной разработки, Конфигурация приложений Azure и Azure Key Vault.

Следуйте этим правилам:

• Не включайте в коммит пароли, секреты клиента, токены доступа или строки подключения к рабочей среде.
• Предпочитайте метод аутентификации, который не требует пароля в строка подключения.
• Ограничить доступ к источнику конфигурации.
• Вращайте сохранённые секреты и перезапускайте или обновляйте приложения, которые их кэшируют.
• Не записывайте строки соединения в логи, исключения, трассы или телеметрию.
• Оставьте Persist Security Info=false, по умолчанию, чтобы открытое соединение не выдало пароль через его ConnectionString свойство.

Для провайдеров конфигурации .NET см. раздел «Конфигурация в .NET». Для получения дополнительных элементов управления см. раздел «Защита соединения».

Правила разбора

Драйвер применяет следующие правила:

• Ключевые слова указываются без учета регистра. DATABASE, Database, и database — одно и то же ключевое слово.
• Многие ключевые слова имеют синонимы. Server и Data Source устанавливают одно и то же значение. В статье «Опции подключения» перечислены синонимы для каждого ключевого слова.
• Если ключевое слово появляется более одного раза, побеждает последнее значение. Синонимы считаются одним и тем же ключевым словом.
• Драйвер игнорирует пробелы вокруг ключевых слов и нецитируемых значений.
• Завершающая точка с запятой необязательна.
• Ключевое слово, которое драйвер не распознаёт, вызывает исключение ArgumentException с сообщением Keyword not supported.

Значения могут быть чувствительны к регистру, в зависимости от ключевого слова. Пароль чувствителен к регистру. Encrypt=STRICT и Encrypt=strict они одинаковы.

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

.NET

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

платформа .NET

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Synonyms and keyword case are normalized to canonical keywords.
        var parsed = new SqlConnectionStringBuilder(
            "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
        Console.WriteLine(parsed.ConnectionString);

        // When a keyword repeats, the last value wins.
        var duplicate = new SqlConnectionStringBuilder(
            "Server=sql.example.com;Database=Orders;Database=Archive");
        Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

        // The builder quotes values that contain delimiters.
        var quoted = new SqlConnectionStringBuilder
        {
            DataSource = "sql.example.com",
            UserID = "app_user",
            Password = "a;b'c\"d",
        };
        Console.WriteLine(quoted.ConnectionString);
        Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");
    }
}

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

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

Первая строка показывает, что каждый синоним заменён его каноническим ключевым словом: timeout на Connect Timeout, User ID на uid, Initial Catalog на DATABASE и Data Source на server.

Значения в кавычках

Оберните значение в двойные кавычки (") или одиночные кавычки ('), если оно содержит точку с запятой, начинается или заканчивается на пробел, или начинается или заканчивается кавычками. Внутри указанного значения запишем вводящую кавычку дважды.

Value	Форма соединительной строки
a;b	Password="a;b"
abc'	Password="abc'"
say "hi"	Password='say "hi"'
a;b'c"d	Password="a;b'c""d"

В правилах цитирования легко ошибиться. Устанавливайте значения через свойства SqlConnectionStringBuilder и пусть конструктор заключит их в кавычки. Для получения дополнительной информации см. раздел «Безопасное создание строк подключения».

Укажите булевы значения

Ключевые слова, принимающие булевое значение true, принимают , false, yesи no, в любом случае. Integrated Security также sspiпринимает , что означает true. Строитель пишет True или False.

Используйте ключевые слова из других источников

Microsoft. Data.SqlClient не принимает ключевые слова ODBC или OLE DB, такие Driver как и Provider. Удаляйте эти ключевые слова, когда перемещаете строка подключения с другого драйвера. System.Data.SqlClientСтроки соединения работают в Microsoft. Data.SqlClient, с этими отличиями:

• Encrypt по умолчанию равно Mandatory в Microsoft.Data.SqlClient. Сервер без доверенного сертификата не проходит проверку сертификата. Установите доверенный сертификат на сервер.
• В .NET, Network Library, Connection Reset, и Transparent Network IP Resolution не поддерживаются. Удалите их.
• Context Connection=true не поддерживается.
• Asynchronous Processing не является поддерживаемым ключевым словом и выбрасывает ArgumentException. Удалите его. Асинхронные методы работают и без этого.
• Type System Version=SQL Server 2000 не поддерживается. Создание соединения вызывает ArgumentException. Используйте Latest, SQL Server 2012, SQL Server 2008, или SQL Server 2005.

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

• Используйте Microsoft. Data.SqlClient в приложении .NET
• Параметры подключения
• Построители строк подключения
• Подключитесь к источнику данных
• Пул подключений SQL Server
• Проверка подлинности Microsoft Entra ID
• Шифрование и проверка сертификатов
• Пользовательские экземпляры SQL Server Express
• Жизненный цикл поддержки драйвера SqlClient