SqlConnectionStringBuilder Класс

Определение

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

System.Data.SqlClient

Сборка:

System.Data.dll

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

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

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

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

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

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

Object

DbConnectionStringBuilder

SqlConnectionStringBuilder

Атрибуты

TypeConverterAttribute

Примеры

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

// Create a new SqlConnectionStringBuilder and
// initialize it with a few name/value pairs.
SqlConnectionStringBuilder builder = new(
    "Server=(local);Integrated Security=true;" +
    "Initial Catalog=AdventureWorks"
    );

// The input connection string used the
// Server key, but the new connection string uses
// the well-known Data Source key instead.
Console.WriteLine($"Original connection string: '{builder.ConnectionString}'");

// Now that the connection string has been parsed,
// you can work with individual items.
Console.WriteLine($"Initial catalog: '{builder.InitialCatalog}'");
builder.InitialCatalog = "Northwind";
builder.AsynchronousProcessing = true;

// 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($"Modified connection string: '{builder.ConnectionString}'");

Imports System.Data.SqlClient

Module Module1
    Sub Main()
        ' Create a new SqlConnectionStringBuilder and
        ' initialize it with a few name/value pairs:
        Dim builder As New SqlConnectionStringBuilder(
            "Server=(local);Integrated Security=true;" &
            "Initial Catalog=AdventureWorks"
            )

        ' The input connection string used the 
        ' Server key, but the new connection string uses
        ' the well-known Data Source key instead.
        Console.WriteLine("Original connection string: " + builder.ConnectionString)

        ' Now that the connection string has been parsed,
        ' you can work with individual items.
        Console.WriteLine("Initial catalog: " + builder.InitialCatalog)
        builder.InitialCatalog = "Northwind"
        builder.AsynchronousProcessing = True

        ' 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

        ' The Item property is the default for the class, 
        ' and setting the Item property adds the value to the 
        ' dictionary, if necessary. 
        builder.Item("Trusted_Connection") = True
        Console.WriteLine("Modified connection string: " + builder.ConnectionString)
    End Sub
End Module

Комментарии

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

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

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

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

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

System.Data.SqlClient.SqlConnectionStringBuilder builder =
  new System.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 для групп доступности AlwaysOn см. в поддержке SqlClient для обеспечения высокой доступности, аварийного восстановления.
ApplicationName	Возвращает или задает имя приложения, связанного со строкой подключения.
AsynchronousProcessing	Возвращает или задает логическое значение, указывающее, разрешена ли асинхронная обработка соединением, созданное с помощью этой строки подключения.
AttachDBFilename	Возвращает или задает строку, содержащую имя первичного файла данных. Сюда входит полное имя присоединенной базы данных.
Authentication	Возвращает проверку подлинности строки подключения.
BrowsableConnectionString	Возвращает или задает значение, указывающее, отображается ли свойство ConnectionString в конструкторах Visual Studio. (Унаследовано от DbConnectionStringBuilder)
ColumnEncryptionSetting	Возвращает или задает параметры шифрования столбцов для построителя строк подключения.
ConnectionReset	Устаревшие.. Устаревший. Возвращает или задает логическое значение, указывающее, сбрасывается ли соединение при получении из пула соединений.
ConnectionString	Возвращает или задает строку подключения, связанную с DbConnectionStringBuilder. (Унаследовано от DbConnectionStringBuilder)
ConnectRetryCount	Количество попыток повторного подключения после выявления сбоя бездействия подключения. Это должно быть целое число от 0 до 255. Значение по умолчанию — 1. Установите значение 0, чтобы отключить повторное подключение при сбоях бездействующего подключения. ArgumentException будет возникать, если задано значение за пределами допустимого диапазона.
ConnectRetryInterval	Время (в секундах) между каждой попыткой повторного подключения после определения сбоя бездействия подключения. Это должно быть целое число от 1 до 60. Значение по умолчанию — 10 секунд. ArgumentException будет возникать, если задано значение за пределами допустимого диапазона.
ConnectTimeout	Возвращает или задает длительность (в секундах), чтобы ждать подключения к серверу, прежде чем завершать попытку и создать ошибку.
ContextConnection	Возвращает или задает значение, указывающее, следует ли выполнять подключение клиента или сервера или внутрипроцессного подключения к SQL Server.
Count	Возвращает текущее количество ключей, содержащихся в свойстве ConnectionString. (Унаследовано от DbConnectionStringBuilder)
CurrentLanguage	Возвращает или задает имя записи языка SQL Server.
DataSource	Возвращает или задает имя или сетевой адрес экземпляра SQL Server для подключения.
EnclaveAttestationUrl	Возвращает или задает URL-адрес аттестации анклава, используемый с анклавом на основе Always Encrypted.
Encrypt	Возвращает или задает логическое значение, указывающее, использует ли SQL Server шифрование SSL для всех данных, отправляемых между клиентом и сервером, если у сервера установлен сертификат.
Enlist	Возвращает или задает логическое значение, указывающее, автоматически ли пул подключений SQL Server автоматически заверяет соединение в текущем контексте транзакции потока создания.
FailoverPartner	Возвращает или задает имя или адрес сервера партнера, к которому необходимо подключиться, если основной сервер отключен.
InitialCatalog	Возвращает или задает имя базы данных, связанной с подключением.
IntegratedSecurity	Возвращает или задает логическое значение, указывающее, указан ли идентификатор пользователя и пароль в соединении (когда false) или используются ли текущие учетные данные учетной записи Windows для проверки подлинности (при true).
IsFixedSize	Возвращает значение, указывающее, имеет ли SqlConnectionStringBuilder фиксированный размер.
IsReadOnly	Возвращает значение, указывающее, доступен ли DbConnectionStringBuilder только для чтения. (Унаследовано от DbConnectionStringBuilder)
Item[String]	Возвращает или задает значение, связанное с указанным ключом. В C#это свойство является индексатором.
Keys	Получает ICollection, содержащий ключи в SqlConnectionStringBuilder.
LoadBalanceTimeout	Возвращает или задает минимальное время (в секундах) для подключения к пулу соединений перед уничтожением.
MaxPoolSize	Возвращает или задает максимальное количество подключений, разрешенных в пуле подключений для этой конкретной строки подключения.
MinPoolSize	Возвращает или задает минимальное количество подключений, разрешенных в пуле подключений для этой конкретной строки подключения.
MultipleActiveResultSets	Если задано значение true, приложение может поддерживать несколько активных результирующих наборов (MARS). Если значение false, приложение должно обрабатывать или отменять все результирующие наборы из одного пакета, прежде чем он сможет выполнить любой другой пакет в этом соединении. Дополнительные сведения см. в нескольких активных результирующих наборов (MARS).
MultiSubnetFailover	Если приложение подключается к группе доступности AlwaysOn или экземпляру отказоустойчивого кластера Always On (FCI) в разных подсетях, параметр MultiSubnetFailover=true обеспечивает быстрое обнаружение и подключение к активному серверу (в настоящее время). Дополнительные сведения о поддержке SqlClient для функций AlwaysOn см. в поддержке SqlClient для обеспечения высокой доступности, аварийного восстановления.
NetworkLibrary	Возвращает или задает строку, содержащую имя сетевой библиотеки, используемой для установления подключения к SQL Server.
PacketSize	Возвращает или задает размер в байтах сетевых пакетов, используемых для взаимодействия с экземпляром SQL Server.
Password	Возвращает или задает пароль для учетной записи SQL Server.
PersistSecurityInfo	Возвращает или задает значение, указывающее, следует ли возвращать конфиденциальные данные безопасности, например пароль или маркер доступа, как часть строки подключения, созданной с помощью этого SqlConnectionStringBuilder после того, как это подключение когда-либо находилось в открытом состоянии.
PoolBlockingPeriod	Поведение периода блокировки для пула подключений.
Pooling	Возвращает или задает логическое значение, указывающее, будет ли соединение быть пулом или явно открываться при каждом запросе подключения.
Replication	Возвращает или задает логическое значение, указывающее, поддерживается ли репликация с помощью подключения.
TransactionBinding	Возвращает или задает строковое значение, указывающее, как соединение сохраняет связь с заверяемой транзакцией System.Transactions.
TransparentNetworkIPResolution	Если для этого ключа задано значение true, приложение требуется для получения всех IP-адресов для определенной записи DNS и попытки подключиться к первой в списке. Если подключение не установлено в течение 0,5 секунд, приложение попытается подключиться ко всем остальным параллельно. При первом ответе приложение установит соединение с IP-адресом респондента.
TrustServerCertificate	Возвращает или задает значение, указывающее, будет ли канал зашифрован при обходе цепочки сертификатов для проверки доверия.
TypeSystemVersion	Возвращает или задает строковое значение, указывающее систему типов, которую ожидает приложение.
UserID	Возвращает или задает идентификатор пользователя, используемый при подключении к SQL Server.
UserInstance	Возвращает или задает значение, указывающее, следует ли перенаправлять подключение из экземпляра SQL Server Express по умолчанию в экземпляр, инициированный средой выполнения, в учетной записи вызывающего объекта.
Values	Получает ICollection, содержащий значения в SqlConnectionStringBuilder.
WorkstationID	Возвращает или задает имя рабочей станции, подключающейся к SQL Server.

Методы

Add(String, Object)	Добавляет запись с указанным ключом и значением в DbConnectionStringBuilder. (Унаследовано от DbConnectionStringBuilder)
Clear()	Очищает содержимое экземпляра SqlConnectionStringBuilder.
ClearPropertyDescriptors()	Очищает коллекцию объектов PropertyDescriptor в связанном DbConnectionStringBuilder. (Унаследовано от DbConnectionStringBuilder)
ContainsKey(String)	Определяет, содержит ли SqlConnectionStringBuilder определенный ключ.
Equals(Object)	Определяет, равен ли указанный объект текущему объекту. (Унаследовано от Object)
EquivalentTo(DbConnectionStringBuilder)	Сравнивает сведения о подключении в этом объекте DbConnectionStringBuilder с сведениями о соединении в предоставленном объекте. (Унаследовано от DbConnectionStringBuilder)
GetHashCode()	Служит хэш-функцией по умолчанию. (Унаследовано от Object)
GetProperties(Hashtable)	Заполняет предоставленный Hashtable сведениями обо всех свойствах этого DbConnectionStringBuilder. (Унаследовано от DbConnectionStringBuilder)
GetType()	Возвращает Type текущего экземпляра. (Унаследовано от Object)
MemberwiseClone()	Создает неглубокую копию текущей Object. (Унаследовано от Object)
Remove(String)	Удаляет запись с указанным ключом из экземпляра SqlConnectionStringBuilder.
ShouldSerialize(String)	Указывает, существует ли указанный ключ в этом SqlConnectionStringBuilder экземпляре.
ToString()	Возвращает строку подключения, связанную с этой DbConnectionStringBuilder. (Унаследовано от DbConnectionStringBuilder)
TryGetValue(String, Object)	Извлекает значение, соответствующее предоставленному ключу из этой SqlConnectionStringBuilder.

Явные реализации интерфейса

ICollection.CopyTo(Array, Int32)	Копирует элементы ICollection в Array, начиная с определенного индекса Array. (Унаследовано от DbConnectionStringBuilder)
ICollection.IsSynchronized	Возвращает значение, указывающее, синхронизирован ли доступ к ICollection (потокобезопасный). (Унаследовано от DbConnectionStringBuilder)
ICollection.SyncRoot	Получает объект, который можно использовать для синхронизации доступа к ICollection. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetAttributes()	Возвращает коллекцию настраиваемых атрибутов для этого экземпляра компонента. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetClassName()	Возвращает имя класса этого экземпляра компонента. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetComponentName()	Возвращает имя этого экземпляра компонента. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetConverter()	Возвращает преобразователь типов для этого экземпляра компонента. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultEvent()	Возвращает событие по умолчанию для этого экземпляра компонента. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultProperty()	Возвращает свойство по умолчанию для этого экземпляра компонента. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEditor(Type)	Возвращает редактор указанного типа для этого экземпляра компонента. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents()	Возвращает события для этого экземпляра компонента. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents(Attribute[])	Возвращает события для этого экземпляра компонента, используя указанный массив атрибутов в качестве фильтра. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties()	Возвращает свойства для этого экземпляра компонента. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties(Attribute[])	Возвращает свойства для этого экземпляра компонента с помощью массива атрибутов в качестве фильтра. (Унаследовано от DbConnectionStringBuilder)
ICustomTypeDescriptor.GetPropertyOwner(PropertyDescriptor)	Возвращает объект, содержащий свойство, описанное указанным дескриптором свойства. (Унаследовано от DbConnectionStringBuilder)
IDictionary.Add(Object, Object)	Добавляет элемент с предоставленным ключом и значением в объект IDictionary. (Унаследовано от DbConnectionStringBuilder)
IDictionary.Contains(Object)	Определяет, содержит ли объект IDictionary элемент с указанным ключом. (Унаследовано от DbConnectionStringBuilder)
IDictionary.GetEnumerator()	Возвращает объект IDictionaryEnumerator для объекта IDictionary. (Унаследовано от DbConnectionStringBuilder)
IDictionary.Item[Object]	Возвращает или задает элемент с указанным ключом. (Унаследовано от DbConnectionStringBuilder)
IDictionary.Remove(Object)	Удаляет элемент с указанным ключом из объекта IDictionary. (Унаследовано от DbConnectionStringBuilder)
IEnumerable.GetEnumerator()	Возвращает перечислитель, который выполняет итерацию по коллекции. (Унаследовано от DbConnectionStringBuilder)

Методы расширения

Cast<TResult>(IEnumerable)	Приведение элементов IEnumerable к указанному типу.
OfType<TResult>(IEnumerable)	Фильтрует элементы IEnumerable на основе указанного типа.
AsParallel(IEnumerable)	Включает параллелизацию запроса.
AsQueryable(IEnumerable)	Преобразует IEnumerable в IQueryable.

См. также раздел

• строк подключения (ADO.NET)
• обзора ADO.NET