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

Строка подключения Microsoft.Data.SqlClient указывает драйверу, какую конечную точку, совместимую с SQL Server, и какую базу данных использовать, как выполнять аутентификацию и как настроить соединение. Передайте его в SqlConnection или SqlConnectionStringBuilder.

Начните с четырёх решений:

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

Оставляйте учетные данные и токены доступа вне строка подключения, когда выбранный метод аутентификации поддерживает такую конструкцию.

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

Используйте самый узкий узор, подходящий для развертывания.

Environment	Предпочтительный узор	Основная строка подключения
SQL Server на Windows под доменной или локальной идентификацией Windows	Встроенная проверка подлинности Windows	`Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true`
Рабочая станция разработчика, подключаемая к базе данных SQL в Microsoft Fabric	Цепочка учетных данных по умолчанию Microsoft Entra ID	`Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict`
Приложение размещено в 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`
Интерактивный рабочий стол, подключаемый к 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_id>;Password=<password>;Encrypt=true`

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

Аутентификация также требует пользователей на стороне базы данных, прав доступа и конфигурации удостоверений. Полную матрицу вариантов и инструкции по настройке см. в разделах аутентификация Microsoft Entra ID и аутентификация SQL Server.

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

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

Распространённые серверные формы включают:

Server=server-name
Server=server-name\instance-name
Server=tcp:server-name,1433
Server=(localdb)\MSSQLLocalDB

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

Для прослушивателя группы доступности, группы отработки отказа, конечной точки Azure SQL или другой многоадресной конечной точки TCP см. также MultiSubnetFailover в разделе Параметры подключения.

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

Microsoft.Data.SqlClient 4.0 и более поздние версии по умолчанию используют для Encrypt значение true. Microsoft.Data.SqlClient 5.0 и более поздние версии также поддерживают Encrypt=Strict для серверов, согласующих TDS 8.0.

Использование:

Encrypt=Strict когда сервер поддерживает TDS 8.0 и имеет сертификат, клиент может проверить.
Encrypt=true для зашифрованных соединений с другими поддерживаемыми серверами.
TrustServerCertificate=false, по умолчанию для проверки производственных сертификатов.

Не используйте TrustServerCertificate=true как универсальное решение проблем с подключением. Он шифрует канал, но пропускает проверку идентичности сервера. Ограничьте это контролируемыми средами разработки, где доверенный сертификат недоступен.

Для требований к серверу, поведению версии и опциям сертификатов см. раздел Шифрование и проверка сертификатов.

Понимание синтаксиса строка подключения

Строка строка подключения — это список пар ключевых слов и значений, разделённый точкой с запятой:

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

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

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

Набор принятых ключевых слов и псевдонимов принадлежит поставщику. Строка подключения, поддерживаемая Microsoft.Data.SqlClient, может не работать с System.Data.SqlClient или другим поставщиком данных.

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

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

string baseConnectionString =
    configuration.GetConnectionString("Orders")
    ?? throw new InvalidOperationException(
        "Connection string 'Orders' wasn't configured.");

var builder = new SqlConnectionStringBuilder(baseConnectionString)
{
    ApplicationName = "Orders.Api",
    ConnectTimeout = 30,
};

string connectionString = builder.ConnectionString;

Конструктор:

Отклоняет неподдерживаемые ключевые слова и некорректные значения.
Сопоставляет псевдонимы с каноническими свойствами.
При необходимости указывает значения.
Предотвращает введение в одно значение другое ключевое слово.

Средство сборки не обеспечивает защиту пароля или токена после того, как они попадают в память процесса. Он также не решает, безопасно ли сервер, идентичность или сертификат.

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

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

Соблюдайте следующие правила:

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

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

Держите ключи пула стабильными

Пул соединений использует точную конфигурацию соединения как часть ключа пула. Эквивалентные строки могут создавать отдельные пулы, если их текст отличается, в том числе когда ключевые слова появляются в другом порядке.

Создайте одну единую строку подключения при запуске приложения и используйте её повторно. Не добавляйте идентификаторы запросов, имена пользователей, токены доступа или другие значения для каждого запроса в строку. Полные правила ключей см. раздел SQL Server Connection pooling.

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

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

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

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

Проверить поведение, зависящее от версии

Версия драйвера	Смена строк соединения
4.0	`Encrypt` по умолчанию использует `true`.
5.0	`Encrypt=Strict` и `HostNameInCertificate` доступны. `SqlConnectionStringBuilder.Encrypt` использует `SqlConnectionEncryptOption`.
5.1	`ServerCertificate` может сопоставить серверный сертификат с файлом.
5,2	AccessTokenCallback доступна для токенов, предоставляемых возобновляемыми приложениями.
7.0	Аутентификация Microsoft Entra ID через драйвер переносится в `Microsoft.Data.SqlClient.Extensions.Azure`.
7.0.2	Основной драйвер и его сопутствующие пакеты используют согласованные версии.

Используйте поддерживаемую стабильную версию драйвера и прочитайте заметки к релизу перед обновлением. Для текущих версий см. жизненный цикл поддержки драйверов SqlClient.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-09-21