SqlConnectionStringBuilder Класс

Определение

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

Microsoft.Data.SqlClient

Сборка:

Microsoft.Data.SqlClient.dll

Пакет:

Microsoft.Data.SqlClient v5.2.0

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

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

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

type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

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

DbConnectionStringBuilder

SqlConnectionStringBuilder

Примеры

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

Примечание

В этом примере для демонстрации взаимодействия класса 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= a!Pass113;initial catalog=AdventureWorks";

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

        // 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	Возвращает или задает метод проверки подлинности, используемый для подключения к База данных SQL с помощью проверки подлинности Azure Active Directory.
ColumnEncryptionSetting	Получает или задает параметры шифрования столбца для построителя строк подключения.
CommandTimeout	Время ожидания по умолчанию (в секундах) перед завершением попытки выполнения команды и созданием ошибки. По умолчанию это 30 секунд.
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 и выше)
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	Если приложение подключается к группе доступности Always On в разных подсетях и вы задали параметру MultiSubnetFailover значение true, операции определения активного сервера и подключения к нему ускорятся. Дополнительные сведения о поддержке SqlClient для групп доступности Always On см. в разделе Поддержка SqlClient для высокого уровня доступности и аварийного восстановления.
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	Возвращает или задает имя субъекта-службы (SPN) источника данных.
TransactionBinding	Возвращает или задает строковое значение, указывающее, как соединение поддерживает связь с прикрепленной транзакцией System.Transactions.
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.