Поделиться через


SqlConnectionStringBuilder Класс

Определение

Удобное средство, с помощью которого можно создавать используемые классом 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
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder
[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder
Public NotInheritable Class SqlConnectionStringBuilder
Inherits 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

Возвращает или задает имя приложения, связанного со строкой подключения.

AsynchronousProcessing
Устаревшие..

Является устаревшей. Возвращает или задает логическое значение, указывающее, допускается ли асинхронная обработка соединением, созданным с использованием данной строки подключения.

AttachDBFilename

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

AttestationProtocol

Возвращает или задает значение протокола аттестации.

Authentication

Возвращает или задает метод проверки подлинности, используемый для подключения к База данных SQL с помощью проверки подлинности Azure Active Directory.

ColumnEncryptionSetting

Получает или задает параметры шифрования столбца для построителя строк подключения.

CommandTimeout

Время ожидания по умолчанию (в секундах) перед завершением попытки выполнения команды и созданием ошибки. По умолчанию это 30 секунд.

ConnectionReset
Устаревшие..
Устаревшие..

Является устаревшей. Возвращает или задает логическое значение, указывающее, следует ли сбрасывать соединение при извлечении его из пула.

ConnectRetryCount

Количество повторных попыток подключения после обнаружения простоя при сбое подключения. Это должно быть целое число в диапазоне от 0 до 255. Значение по умолчанию для конечных точек, отличных от Azure, равно 1. Для конечных точек Azure SQL значение по умолчанию — 2. Начиная с версии 5.x, для Azure SQL бессерверных конечных точек или конечных точек по запросу значение по умолчанию равно 5, чтобы улучшить успешное подключение для подключений к бездействующий или приостановленный экземпляр. Задайте значение 0, чтобы запретить повторное подключение при сбое подключения. Будет вызван ArgumentException, если будет задано значение вне допустимого диапазона.

ConnectRetryInterval

Количество времени (в секундах) между попытками повторного подключения после идентификации сбоя неактивного подключения. Это должно быть целое число в диапазоне от 1 до 60. Значение по умолчанию — 10 секунд.

ConnectTimeout

Получает или задает продолжительность времени ожидания подключения к серверу (в секундах) перед прекращением попытки подключения и созданием ошибки.

ContextConnection
Устаревшие..

Является устаревшей. Возвращает или задает значение, указывающее, какое следует установить соединение с SQL Server: клиент-серверное или внутрипроцессное.

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 для высокого уровня доступности и аварийного восстановления.

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

Возвращает или задает имя субъекта-службы (SPN) источника данных.

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.

Методы

Clear()

Удаляет содержимое экземпляра SqlConnectionStringBuilder.

ContainsKey(String)

Определяет, содержит ли объект SqlConnectionStringBuilder указанный ключ.

Remove(String)

Удаляет из экземпляра SqlConnectionStringBuilder запись с указанным ключом.

ShouldSerialize(String)

Указывает, существует ли заданный ключ в этом экземпляре SqlConnectionStringBuilder.

TryGetValue(String, Object)

Получает значение, соответствующее заданному ключу, из данного объекта SqlConnectionStringBuilder.

Применяется к