SqlConnectionStringBuilder Класс

Определение

Пространство имен:

Microsoft.Data.SqlClient

Сборка:

Microsoft.Data.SqlClient.dll

Пакет:

Microsoft.Data.SqlClient v7.1.0

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

public ref class SqlConnectionStringBuilder sealed : System::Data::Common::DbConnectionStringBuilder

[System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Наследование

DbConnectionStringBuilder

SqlConnectionStringBuilder

Атрибуты

TypeConverterAttribute

Примеры

Следующее консольное приложение создает строки подключения для базы данных SQL Server. Код использует SqlConnectionStringBuilder класс для создания строка подключения, а затем передает ConnectionString свойство SqlConnectionStringBuilder экземпляра конструктору класса подключения. В этом примере также анализируется существующий строка подключения и демонстрируется различные способы управления содержимым строка подключения.

Note

В этом примере содержится пароль для демонстрации работы SqlConnectionStringBuilder со строками подключения. В приложениях рекомендуется использовать проверку подлинности Windows. Если вы должны использовать пароль, не включайте в приложение жестко закодированный пароль.

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Create a new SqlConnectionStringBuilder and
        // initialize it with a few name/value pairs.
        SqlConnectionStringBuilder builder =
            new SqlConnectionStringBuilder(GetConnectionString());

        // The input connection string used the 
        // Server key, but the new connection string uses
        // the well-known Data Source key instead.
        Console.WriteLine(builder.ConnectionString);

        // Pass the SqlConnectionStringBuilder an existing 
        // connection string, and you can retrieve and
        // modify any of the elements.
        builder.ConnectionString = "server=(local);user id=ab;" +
            "password=********;initial catalog=AdventureWorks";

        // Now that the connection string has been parsed,
        // you can work with individual items.
        Console.WriteLine(builder.Password);
        builder.Password = "********";

        // You can refer to connection keys using strings, 
        // as well. When you use this technique (the default
        // Item property in Visual Basic, or the indexer in C#),
        // you can specify any synonym for the connection string key
        // name.
        builder["Server"] = ".";
        builder["Connect Timeout"] = 1000;
        builder["Trusted_Connection"] = true;
        Console.WriteLine(builder.ConnectionString);

        Console.WriteLine("Press Enter to finish.");
        Console.ReadLine();
    }

    private static string GetConnectionString()
    {
        // To avoid storing the connection string in your code,
        // you can retrieve it from a configuration file. 
        return "Server=(local);Integrated Security=SSPI;" +
            "Initial Catalog=AdventureWorks";
    }
}

Комментарии

Построитель строк подключения позволяет разработчикам программно создавать синтаксически правильные строки подключения, а также анализировать и перестроить существующие строки подключения, используя свойства и методы класса. Построитель строк подключения предоставляет строго типизированные свойства, соответствующие известным парам "ключ-значение", разрешенным SQL Server. Разработчики, необходимые для создания строк подключения в рамках приложений, могут использовать SqlConnectionStringBuilder класс для создания и изменения строк подключения. Класс также упрощает управление строками подключения, хранящимися в файле конфигурации приложения.

Выполняет SqlConnectionStringBuilder проверку допустимых пар "ключ-значение". Поэтому нельзя использовать этот класс для создания недопустимых строк подключения; При попытке добавить недопустимые пары возникает исключение. Класс поддерживает фиксированную коллекцию синонимов и может переводиться из синонима в соответствующее известное имя ключа.

Например, при использовании свойства Item для получения значения можно указать строку, содержащую любой синоним нужного ключа. Например, можно указать "Сетевой адрес", "addr" или любой другой приемлемый синоним для этого ключа в строка подключения при использовании любого элемента, содержащего строку, содержащую имя ключа, например свойство Item или Remove метод. Полный список допустимых синонимов см. в свойстве ConnectionString.

Свойство Item обрабатывает попытку вставки вредоносных записей. Например, следующий код, используя свойство Item по умолчанию (индексатор в C#), правильно экранирует пару вложенных ключей и значений:

Dim builder As New Microsoft.Data.SqlClient.SqlConnectionStringBuilder  
builder("Data Source") = "(local)"  
builder("Integrated Security") = True  
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"  
Console.WriteLine(builder.ConnectionString)  

Microsoft.Data.SqlClient.SqlConnectionStringBuilder builder =  
new Microsoft.Data.SqlClient.SqlConnectionStringBuilder();  
builder["Data Source"] = "(local)";  
builder["Integrated Security"] = true;  
builder["Initial Catalog"] = "AdventureWorks;NewValue=Bad";  
Console.WriteLine(builder.ConnectionString);  

Результатом является следующая строка подключения, которая обрабатывает недопустимое значение безопасным образом:

Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";  
Integrated Security=True  

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

Имя.	Описание
SqlConnectionStringBuilder()	Инициализирует новый экземпляр класса SqlConnectionStringBuilder.
SqlConnectionStringBuilder(String)	Инициализирует новый экземпляр класса SqlConnectionStringBuilder. Указанная строка подключения предоставляет данные для внутренних сведений о подключении экземпляра.

Свойства

Имя.	Описание
ApplicationIntent	Объявляет тип рабочей нагрузки приложения при подключении к базе данных в группе доступности SQL Server. Значение этого свойства можно задать с помощью ApplicationIntent. Дополнительные сведения о поддержке SqlClient для групп доступности Always On см.: Поддержка SqlClient для высокой доступности и аварийного восстановления.
ApplicationName	Возвращает или задает имя приложения, связанного со строкой подключения.
AttachDBFilename	Возвращает или задает строку, содержащую имя первичного файла данных. Сюда входит полное имя присоединенной базы данных.
AttestationProtocol	Возвращает или задает значение протокола аттестации.
Authentication	Возвращает или задает метод проверки подлинности, используемый для подключения с Microsoft Entra для Azure SQL ресурсов.
ColumnEncryptionSetting	Возвращает или задает параметры шифрования столбцов для построителя строк подключения.
CommandTimeout	Время ожидания по умолчанию (в секундах) перед завершением попытки выполнения команды и создания ошибки. Значение по умолчанию — 30 секунд.
ConnectionReset	Устаревшие. Является устаревшей. Возвращает или задает логическое значение, указывающее, сбрасывается ли соединение при получении из пула соединений.
ConnectRetryCount	Количество попыток повторного подключения после выявления сбоя бездействия подключения. Это должно быть целое число от 0 до 255. Значение по умолчанию для конечных точек, отличных от Azure, равно 1. Для конечных точек Azure SQL значение по умолчанию равно 2. Начиная с версии 5.x, для Azure SQL бессерверных или конечных точек по запросу значение по умолчанию равно 5, чтобы повысить успешность подключения к неактивному или приостановленному экземпляру. Установите значение 0, чтобы отключить повторное подключение при сбоях бездействующего подключения. Если ArgumentException задано значение за пределами допустимого диапазона, создается исключение.
ConnectRetryInterval	Время (в секундах) между каждой попыткой повторного подключения после определения сбоя бездействия подключения. Это должно быть целое число от 1 до 60. Значение по умолчанию — 10 секунд.
ConnectTimeout	Возвращает или задает длительность (в секундах), чтобы ждать подключения к серверу, прежде чем завершать попытку и создать ошибку.
CurrentLanguage	Возвращает или задает язык, используемый для предупреждений или сообщений об ошибках сервера базы данных..
DataSource	Возвращает или задает имя или сетевой адрес экземпляра SQL Server для подключения.
EnclaveAttestationUrl	Возвращает или задает URL-адрес аттестации анклава, используемый с анклавом на основе Always Encrypted.
Encrypt	Возвращает или задает SqlConnectionEncryptOption значение с версии 5.0 или Boolean значение для предыдущих версий, указывающее, требуется ли шифрование TLS для всех данных, отправляемых между клиентом и сервером.
Enlist	Возвращает или задает логическое значение, указывающее, автоматически ли пул подключений SQL Server автоматически заверяет соединение в текущем контексте транзакции потока создания.
FailoverPartner	Возвращает или задает имя или адрес сервера партнера, к которому необходимо подключиться, если основной сервер отключен.
FailoverPartnerSPN	Возвращает или задает имя субъекта-службы (SPN) партнера отработки отказа для подключения.
HostNameInCertificate	Возвращает или задает имя узла, используемое при проверке сертификата сервера для подключения. Если он не указан, имя сервера из этого Data Source сервера используется для проверки сертификата. (Доступно только в версии 5.0+)
IdleTimeout	Возвращает или задает максимальное время в секундах, когда соединение может сидеть неиспользуемо (неактивно) в пуле соединений до его отмены. Значение по умолчанию — 300 (5 минут).
InitialCatalog	Возвращает или задает имя базы данных, связанной с подключением.
IntegratedSecurity	Возвращает или задает логическое значение, указывающее, указан ли идентификатор пользователя и пароль в соединении (когда false ) или используются ли текущие учетные данные учетной записи Windows для проверки подлинности (когда true ).
IPAddressPreference	Возвращает или задает параметр семейства IP-адресов при установке TCP-подключений.
IsFixedSize	Возвращает значение, указывающее, имеет ли SqlConnectionStringBuilder размер фиксированного размера.
Item[String]	Возвращает или задает значение, связанное с указанным ключом. В C#это свойство является индексатором.
Keys	Возвращает объект ICollection , содержащий ключи в объекте SqlConnectionStringBuilder.
LoadBalanceTimeout	Возвращает или задает минимальное время (в секундах) для подключения к пулу соединений перед уничтожением.
MaxPoolSize	Возвращает или задает максимальное количество подключений, разрешенных в пуле подключений для этой конкретной строки подключения.
MinPoolSize	Возвращает или задает минимальное количество подключений, разрешенных в пуле подключений для этой конкретной строки подключения.
MultipleActiveResultSets	Если задано значение true, приложение может поддерживать несколько активных результирующих наборов (MARS). Если значение false, приложение должно обрабатывать или отменять все результирующие наборы из одного пакета, прежде чем он сможет выполнить любой другой пакет в этом соединении. Дополнительные сведения см. в разделе Несколько активных результирующих наборов (MARS).
MultiSubnetFailover	Если приложение подключается к группе доступности AlwaysOn в разных подсетях, параметр MultiSubnetFailover=true обеспечивает быстрое обнаружение и подключение к активному серверу (в настоящее время). Дополнительные сведения о поддержке SqlClient для групп доступности Always On см.: Поддержка SqlClient для высокой доступности и аварийного восстановления.
NetworkLibrary	Возвращает или задает строку, содержащую имя сетевой библиотеки, используемой для установления подключения к SQL Server.
PacketSize	Возвращает или задает размер в байтах сетевых пакетов, используемых для взаимодействия с экземпляром SQL Server.
Password	Возвращает или задает пароль для учетной записи SQL Server.
PersistSecurityInfo	Возвращает или задает логическое значение, указывающее, следует ли возвращать конфиденциальные данные безопасности, например пароль или маркер доступа, как часть строка подключения подключения, созданного с этим SqlConnectionStringBuilder после того, как это подключение когда-либо находилось в открытом состоянии. Это свойство должно быть задано true только в том случае, если приложению требуется считывать пароль из уже открытого подключения к базе данных. Значение false по умолчанию является более безопасным параметром. Использование true этого свойства открывает приложение для рисков безопасности, таких как случайное ведение журнала или трассировка пароля базы данных.
PoolBlockingPeriod	Поведение периода блокировки для пула подключений.
Pooling	Возвращает или задает логическое значение, указывающее, будет ли соединение быть пулом или явно открываться при каждом запросе подключения.
Replication	Возвращает или задает логическое значение, указывающее, поддерживается ли репликация с помощью подключения.
ServerCertificate	Возвращает или задает путь к файлу сертификата, который соответствует SQL Server TLS/SSL-сертификату для подключения. Допустимые форматы сертификатов: PEM, DER и CER. При указании сертификат SQL Server проверяется путем проверки того, соответствует ли ServerCertificate предоставленный сертификат точному совпадению. (Доступно только в версии 5.1+)
ServerSPN	Возвращает или задает имя субъекта-службы источника данных.
TransactionBinding	Возвращает или задает строковое значение, указывающее, как соединение сохраняет связь с заверяемой System.Transactions транзакцией.
TransparentNetworkIPResolution	Устаревшие. В .NET Framework, если задано trueзначение этого ключа, драйвер выполняет несколько округлений подключения по IP-адресам, разрешаемых DNS, с постепенно большим временем ожидания для каждой попытки и 500 мс минимального значения при попытке последовательного режима, пока подключение не завершится или не будет достигнуто общее Connect Timeout значение.
TrustServerCertificate	Возвращает или задает значение, указывающее, будет ли канал зашифрован при обходе цепочки сертификатов для проверки доверия.
TypeSystemVersion	Возвращает или задает строковое значение, указывающее систему типов, которую ожидает приложение.
UserID	Возвращает или задает идентификатор пользователя, используемый при подключении к SQL Server.
UserInstance	Возвращает или задает значение, указывающее, следует ли перенаправлять подключение из экземпляра SQL Server Express по умолчанию в экземпляр, инициированный средой выполнения, в учетной записи вызывающего объекта.
Values	Возвращает значение ICollection , содержащее значения в объекте SqlConnectionStringBuilder .
WorkstationID	Возвращает или задает имя рабочей станции, подключающейся к SQL Server.

Методы

Имя.	Описание
Clear()	Очищает содержимое экземпляра SqlConnectionStringBuilder .
ContainsKey(String)	Определяет, содержит ли SqlConnectionStringBuilder определенный ключ.
Remove(String)	Удаляет запись с указанным ключом из экземпляра SqlConnectionStringBuilder.
ShouldSerialize(String)	Указывает, существует ли указанный ключ в этом SqlConnectionStringBuilder экземпляре.
TryGetValue(String, Object)	Извлекает значение, соответствующее предоставленному ключу, из этого SqlConnectionStringBuilder .