SqlConnectionStringBuilder Класс

Определение

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

System.Data.SqlClient

Сборка:

System.Data.SqlClient.dll

Пакет:

System.Data.SqlClient v4.8.6

Удобное средство, с помощью которого можно создавать используемые классом 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

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

Object

DbConnectionStringBuilder

SqlConnectionStringBuilder

Примеры

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

Примечание

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

using System.Data;
using System.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";
        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(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";
    }
}

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(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"
        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(builder.ConnectionString)

        Console.WriteLine("Press Enter to finish.")
        Console.ReadLine()
    End Sub

    Private Function GetConnectionString() As String
        ' 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"
    End Function
End Module

Комментарии

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

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

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

Дескриптор свойства Item пытается вставить вредоносные записи. Например, в следующем коде свойство 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 для групп доступности Always On см. в разделе Поддержка SqlClient для высокого уровня доступности и аварийного восстановления.
ApplicationName	Возвращает или задает имя приложения, связанного со строкой подключения.
AttachDBFilename	Возвращает или задает строку, содержащую имя первичного файла данных. Оно включает полный путь к подключаемой базе данных.
BrowsableConnectionString	Возвращает или задает значение, указывающее, отображается ли свойство ConnectionString в конструкторах Visual Studio. (Унаследовано от DbConnectionStringBuilder)
ConnectionString	Возвращает или задает строку подключения, связанную с этим DbConnectionStringBuilder. (Унаследовано от DbConnectionStringBuilder)
ConnectRetryCount	Количество повторных попыток подключения после обнаружения простоя при сбое подключения. Это должно быть целое число в диапазоне от 0 до 255. Значение по умолчанию: 1. Задайте значение 0, чтобы запретить повторное подключение при сбое подключения. Будет вызван ArgumentException, если будет задано значение вне допустимого диапазона.
ConnectRetryInterval	Количество времени (в секундах) между попытками повторного подключения после идентификации сбоя неактивного подключения. Это должно быть целое число в диапазоне от 1 до 60. Значение по умолчанию — 10 секунд. Будет вызван ArgumentException, если будет задано значение вне допустимого диапазона.
ConnectTimeout	Получает или задает продолжительность времени ожидания подключения к серверу (в секундах) перед прекращением попытки подключения и созданием ошибки.
Count	Возвращает текущее количество ключей, содержащихся в свойстве ConnectionString. (Унаследовано от DbConnectionStringBuilder)
CurrentLanguage	Возвращает или задает имя записи языка SQL Server.
DataSource	Возвращает или задает имя или сетевой адрес экземпляра SQL Server, с которым устанавливается соединение.
Encrypt	Возвращает или задает логическое значение, указывающее, использует ли SQL Server шифрование SSL для всех данных, передаваемых между клиентом и сервером, если на сервере установлен сертификат.
Enlist	Возвращает или задает логическое значение, которое определяет, добавляет ли автоматически процесс SQL Server, обслуживающий пул, соединение в контекст текущей транзакции создающего ее потока.
FailoverPartner	Возвращает или задает имя или адрес сервера-участника, к которому осуществляется подключение, если сервер-источник недоступен.
InitialCatalog	Возвращает или задает имя базы данных, связанной с подключением.
IntegratedSecurity	Возвращает или задает логическое значение, определяющее способ проверки подлинности: либо при подключении указаны идентификатор пользователя и пароль (значение false), либо использованы учетные данные текущей учетной записи Windows (значение true).
IsFixedSize	Получает значение, показывающее, имеет ли объект DbConnectionStringBuilder фиксированный размер. (Унаследовано от DbConnectionStringBuilder)
IsReadOnly	Получает значение, указывающее, доступен ли объект DbConnectionStringBuilder только для чтения. (Унаследовано от DbConnectionStringBuilder)
Item[String]	Возвращает или задает значение, связанное с указанным ключом. В языке C# это свойство является индексатором.
Keys	Возвращает коллекцию ICollection, которая содержит ключи из SqlConnectionStringBuilder.
LoadBalanceTimeout	Возвращает или задает минимальное время ожидания в секундах перед уничтожением соединения, находящегося в пуле.
MaxPoolSize	Возвращает или задает максимальное количество соединений в пуле для данной строки подключения.
MinPoolSize	Возвращает или задает минимальное количество подключений в пуле для данной строки подключения.
MultipleActiveResultSets	Если указано значение true, приложение может поддерживать несколько активных наборов результатов (режим MARS). Если указано значение false, приложение должно обработать или отменить все наборы результатов из одного пакета, прежде чем выполнять любой другой пакет для данного подключения. Дополнительные сведения см. в разделе Несколько активных результирующих наборов (MARS).
MultiSubnetFailover	Если приложение подключается к Always On группе доступности (AG) или экземпляру отказоустойчивого кластера Always On в разных подсетях, параметр MultiSubnetFailover=true ускоряет обнаружение активного сервера и подключение к нему. Дополнительные сведения о поддержке SqlClient функций Always On см. в статье Поддержка Высокого уровня доступности и аварийного восстановления SqlClient.
PacketSize	Возвращает или задает размер сетевых пакетов (в байтах), используемых при взаимодействии с экземпляром SQL Server.
Password	Возвращает или задает пароль для учетной записи SQL Server.
PersistSecurityInfo	Возвращает или задает значение, указывающее, следует ли возвращать конфиденциальные сведения безопасности, такие как пароль или маркер доступа, в составе строка подключения на подключении, созданном с помощью этого SqlConnectionStringBuilder соединения после того, как это соединение когда-либо находилось в открытом состоянии.
Pooling	Возвращает или задает логическое значение, которое определяет, будет ли соединение добавлено в пул или каждое соединение будет явно открываться каждый раз, когда поступает запрос на соединение.
Replication	Возвращает или задает логическое значение, указывающее, можно ли с помощью этого соединения выполнять репликацию.
TransactionBinding	Возвращает или задает строковое значение, указывающее, как соединение поддерживает связь с прикрепленной транзакцией System.Transactions.
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.

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

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

• Строки подключения (ADO.NET)
• Общие сведения об ADO.NET