SqlConnection.ConnectionString Свойство

Определение

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

System.Data.SqlClient

Сборка:

System.Data.SqlClient.dll

Пакет:

System.Data.SqlClient v4.8.6

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

public:
 virtual property System::String ^ ConnectionString { System::String ^ get(); void set(System::String ^ value); };

public override string ConnectionString { get; set; }

member this.ConnectionString : string with get, set

Public Overrides Property ConnectionString As String

Значение свойства

String

Строка подключения, включающая имя источника базы данных и другие параметры, необходимые для установки исходного подключения. Значение по умолчанию - пустая строка.

Исключения

ArgumentException

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

Примеры

В следующем примере создается SqlConnection и задается ConnectionString свойство перед открытием подключения.

private static void OpenSqlConnection()
{
    string connectionString = GetConnectionString();

    using (SqlConnection connection = new SqlConnection())
    {
        connection.ConnectionString = connectionString;

        connection.Open();

        Console.WriteLine("State: {0}", connection.State);
        Console.WriteLine("ConnectionString: {0}",
            connection.ConnectionString);
    }
}

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

Private Sub OpenSqlConnection()
    Dim connectionString As String = GetConnectionString()

    Using connection As New SqlConnection()

        connection.ConnectionString = connectionString

        connection.Open()

        Console.WriteLine("State: {0}", connection.State)
        Console.WriteLine("ConnectionString: {0}", _
            connection.ConnectionString)
    End Using
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 "Data Source=MSSQL1;Database=AdventureWorks;" _
      & "Integrated Security=true;"
End Function

Комментарии

объект ConnectionString похож на строку подключения OLE DB, но не идентичен. В отличие от OLE DB или ADO, возвращаемая строка подключения совпадает с строкой, заданной ConnectionStringпользователем , за вычетом сведений о безопасности, если для параметра Сохранить сведения о безопасности задано false значение (по умолчанию). Поставщик данных платформа .NET Framework для SQL Server не сохраняет и не возвращает пароль в строке подключения, если для параметра Сохранить сведения для защиты не задано значение true.

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

"Persist Security Info=False;Integrated Security=true;Initial Catalog=Northwind;server=(local)"

Используйте новый SqlConnectionStringBuilder для создания допустимых строк подключения во время выполнения. Дополнительные сведения см. в статье Connection String Builders (Построители строк подключения).

Присваивать значение свойству ConnectionString можно только тогда, когда соединение закрыто. Многие из значений строки подключения имеют соответствующие свойства, доступные только для чтения. Если задана строка подключения, эти свойства обновляются, за исключением случаев обнаружения ошибки. В этом случае ни одно из свойств не обновляется. SqlConnection свойства возвращают только те параметры, которые содержатся в ConnectionString.

Чтобы подключиться к локальному компьютеру, укажите "(local)" для сервера. Если имя сервера не указано, будет предпринята попытка подключения к экземпляру по умолчанию на локальном компьютере.

При сбросе ConnectionString при закрытом подключении сбрасываются все значения строки подключения (и связанные свойства), включая пароль. Например, если задать строку подключения, включающую "Database= AdventureWorks", а затем сбросить строку подключения в "Data Source=myserver;Integrated Security=true", то свойству Database больше не присваивается значение "AdventureWorks".

Строка подключения анализируется сразу после установки. Если при синтаксическом анализе обнаруживаются ошибки в синтаксисе, создается исключение среды выполнения, например ArgumentException, . Другие ошибки можно найти только при попытке открыть подключение.

Базовый формат строки подключения включает ряд пар "ключевое слово-значение", разделенных точкой с запятой. Знак равенства (=) соединяет каждое ключевое слово и его значение. Чтобы включить значения, содержащие точку с запятой, одинарные или двойные кавычки, значение должно быть заключено в двойные кавычки. Если значение содержит как точку с запятой, так и символ двойной кавычки, значение можно заключить в одинарные кавычки. Одинарные кавычки также полезны, если значение начинается с символа двойной кавычки. И наоборот, двойную кавычку можно использовать, если значение начинается с одной кавычки. Если значение содержит как одинарные, так и двойные кавычки, символ кавычек, используемый для заключения значения, должен удваивать каждый раз, когда оно встречается в значении.

Чтобы включить предыдущие или конечные пробелы в строковое значение, значение должно быть заключено в одинарные кавычки или двойные кавычки. Любые начальные или конечные пробелы вокруг целочисленных, логических или перечисляемых значений игнорируются, даже если они заключены в кавычки. Однако пробелы в ключевом слове или значении строкового литерала сохраняются. Одинарные или двойные кавычки можно использовать в строке подключения без использования разделителей (например, Data Source= my'Server или Data Source= my"Server), если только символ кавычек не является первым или последним символом в значении.

В ключевых словах регистр не учитывается.

В следующей таблице перечислены допустимые имена для значений ключевых слов в ConnectionString.

Ключевое слово	Значение по умолчанию	Описание
Addr	Н/Д	Синоним источника данных.
Адрес	Н/Д	Синоним источника данных.
Приложение	Н/Д	Синоним имени приложения.
Имя приложения	Н/Д	Имя приложения или поставщик данных SQLClient .NET, если имя приложения не указано. Имя приложения может содержать не более 128 символов.
ApplicationIntent	ReadWrite	Объявляет тип рабочей нагрузки приложения при соединении с сервером. Возможные значения: ReadOnly и ReadWrite. Пример: ApplicationIntent=ReadOnly Дополнительные сведения о поддержке SqlClient для групп доступности Always On см. в разделе Поддержка SqlClient для высокого уровня доступности и аварийного восстановления.
Asynchronous Processing -или- Async	"false"	При trueзначении включает поддержку асинхронных операций. Допустимые значения: true, false, yes и no. Это свойство игнорируется начиная с платформа .NET Framework 4.5. Дополнительные сведения о поддержке асинхронного программирования в SqlClient см. в разделе Асинхронное программирование.
AttachDBFilename -или- Расширенные свойства -или- Исходное имя файла	Н/Д	Имя файла базы данных-источника, включая полный путь к присоединяемой базе данных. Свойство AttachDBFilename поддерживается только для первичных файлов данных, имеющих расширение MDF. Если в строке подключения указано значение ключа AttachDBFileName, база данных присоединяется и становится базой данных по умолчанию для подключения. Если этот ключ не указан и база данных была ранее подключена, база данных не будет повторно подключена. Ранее присоединенная база данных будет использоваться в качестве базы данных по умолчанию для подключения. Если этот ключ указан вместе с ключом AttachDBFileName, значение этого ключа будет использоваться в качестве псевдонима. Однако если имя уже используется в другой подключенной базе данных, подключение завершится ошибкой. Путь может быть абсолютным или относительным с помощью строки подстановки DataDirectory. Если используется DataDirectory, файл базы данных должен находиться в подкаталоге каталога, на который указывает строка подстановки. Примечание: Имена путей удаленного сервера, HTTP и UNC не поддерживаются. Имя базы данных должно быть указано с помощью ключевого слова database (или одного из его псевдонимов), как показано ниже: "AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase" Если файл журнала находится в том же каталоге, что и файл данных, а при прикреплении первичного файла данных было использовано ключевое слово «database», будет выдана ошибка. В этом случае следует удалить файл журнала. После прикрепления базы данных будет автоматически создан новый файл журнала на основе физического пути.
Аутентификация	Н/Д	Метод проверки подлинности, используемый для подключения к База данных SQL с помощью проверки подлинности Azure Active Directory. Допустимые значения: Интегрированная служба Active Directory, пароль Active Directory, пароль SQL.
Настройка шифрования столбца	Н/Д	Включает или отключает Always Encrypted функциональные возможности подключения.
Время ожидания соединения -или- Connection Timeout -или- Время ожидания	15	Продолжительность (в секундах) ожидания подключения к серверу перед завершением попытки и созданием ошибки. Допустимые значения больше или равны 0 и меньше или равны 2147483647. При открытии подключения к базе данных Azure SQL установите время ожидания подключения равным 30 секундам.
Время существования подключения -или- Load Balance Timeout	0	Если соединение возвращается в пул, время его создания сравнивается с текущим временем и соединение уничтожается, если этот промежуток времени (в секундах) превышает значение, заданное параметром Connection Lifetime. Эта возможность полезна в кластеризованных конфигурациях для принудительной балансировки нагрузки между выполняющимся сервером и сервером, только что переведенным в оперативный режим. Значение нуля (0) приводит к тому, что у подключений в пуле будет максимальное время ожидания подключения.
ConnectRetryCount	1	Управляет количеством попыток повторного подключения после того, как клиент определит сбой бездействующего подключения. Допустимые значения: от 0 до 255. Значение по умолчанию — 1. 0 означает, что не пытаться повторно подключиться (отключить устойчивость подключения). Дополнительные сведения об устойчивости подключения см . в статьях Параметры SqlConnection .NET для повторных попыток подключения и Техническая статья Устойчивость бездействующего подключения.
ConnectRetryInterval	10	Указывает время между каждой попыткой повтора подключения (ConnectRetryCount). Допустимые значения: от 1 до 60 секунд (по умолчанию = 10), применяемые после первой попытки повторного подключения. При обнаружении нарушенного подключения клиент немедленно пытается повторно подключиться; Это первая попытка повторного подключения, которая выполняется только в том случае, если значение ConnectRetryCount больше 0. Если первая попытка повторного подключения завершается сбоем и значение ConnectRetryCount больше 1, клиент ожидает ConnectRetryInterval, чтобы опробовать вторую и последующие попытки повторного подключения. Дополнительные сведения об устойчивости подключения см . в статьях Параметры SqlConnection .NET для повторных попыток подключения и Техническая статья Устойчивость бездействующего подключения.
Контекстное соединение	"false"	trueЗначение , если необходимо установить внутрипроцессное подключение к SQL Server.
Current Language -или- Язык	Н/Д	Задает язык, используемый для предупреждений или сообщений об ошибках сервера базы данных. Имя языка может содержать не более 128 символов.
Источник данных -или- Сервер -или- Адрес -или- Addr -или- Сетевой адрес	Н/Д	Имя или сетевой адрес экземпляра SQL Server, к которому нужно подключиться. Номер порта можно указать после имени сервера: server=tcp:servername, portnumber При указании локального экземпляра всегда используйте (local). Чтобы принудительно применить протокол, добавьте один из следующих префиксов: np:(local), tcp:(local), lpc:(local) Начиная с платформа .NET Framework 4.5, вы также можете подключиться к базе данных LocalDB следующим образом: server=(localdb)\\myInstance Дополнительные сведения о LocalDB см. в статье Поддержка SqlClient для LocalDB. Источник данных должен использовать формат TCP или формат именованных каналов. Формат TCP выглядит следующим образом: — tcp:<имя> узла\<имя экземпляра> — tcp:<имя> узла,< номер порта TCP/IP> Формат TCP должен начинаться с префикса "tcp:", за которым следует экземпляр базы данных, как указано в имени узла и имени экземпляра. Этот формат неприменим при подключении к базе данных Azure SQL. Tcp автоматически выбирается для подключений к базе данных Azure SQL, если протокол не указан. Имя узла должно быть указано одним из следующих способов: — NetBIOSName — IPv4Address — IPv6Address Имя экземпляра используется для разрешения на определенный номер порта TCP/IP, на котором размещен экземпляр базы данных. Кроме того, можно указать номер порта TCP/IP напрямую. Если имя экземпляра и номер порта отсутствуют, используется экземпляр базы данных по умолчанию. Формат именованных каналов выглядит следующим образом: - np:\\<имя> узла\pipe\<имя_канала> Формат именованных каналов должен начинаться с префикса "np:", за которым следует имя именованного канала. Имя узла должно быть указано одним из следующих способов: — NetBIOSName — IPv4Address — IPv6Address Имя канала используется для идентификации экземпляра базы данных, к которому будет подключено приложение платформа .NET Framework. Если указано значение сетевого ключа, не следует указывать префиксы "tcp:" и "np:". Примечание: Вы можете принудительно использовать TCP вместо общей памяти, указав префикс tcp: к имени сервера в строке подключения или с помощью localhost.
Шифрование	"false"	При trueSQL Server использует шифрование SSL для всех данных, отправляемых между клиентом и сервером, если на сервере установлен сертификат. Допустимые значения: true, false, yes и no. Дополнительные сведения см. в статье Синтаксис строки подключения. Начиная с платформа .NET Framework 4.5, если TrustServerCertificate имеет значение false и Encrypt true, имя сервера (или IP-адрес) в SQL SERVER SSL-сертификате должно точно соответствовать имени сервера (или IP-адресу), указанному в строке подключения. В противном случае соединение не будет установлено.
Enlist	'true'	trueуказывает, что пул подключений SQL Server автоматически заверяет соединение в контексте текущей транзакции потока создания.
Failover Partner	Н/Д	Имя сервера партнера по отработки отказа, на котором настроено зеркальное отображение базы данных. Если этот ключ имеет значение "", то должен быть указан исходный каталог , а его значение не должно быть "". Имя сервера может содержать не более 128 символов. Если указать партнера по отработки отказа, но сервер-партнер по отработки отказа не настроен для зеркального отображения базы данных, а сервер-источник (указанный с помощью ключевого слова Server) недоступен, подключение завершится ошибкой. Если указать партнера по отработки отказа и сервер-источник не настроен для зеркального отображения базы данных, подключение к серверу-источнику (указанному с помощью ключевого слова Server) будет выполнено успешно, если сервер-источник доступен.
Initial Catalog -или- База данных	Н/Д	Имя базы данных. Имя базы данных может содержать не более 128 символов.
Встроенные функции безопасности -или- Trusted_Connection	"false"	При falseзначении идентификатор пользователя и пароль указываются в соединении. При trueзначении для проверки подлинности используются текущие учетные данные учетной записи Windows. Распознанные значения: true, false, yes, noи sspi (настоятельно рекомендуется), что эквивалентно true. Если указаны идентификатор пользователя и пароль, а для встроенной безопасности задано значение true, идентификатор пользователя и пароль будут игнорироваться, а также будет использоваться встроенная безопасность. SqlCredential— более безопасный способ указать учетные данные для подключения, использующего проверку подлинности SQL Server (Integrated Security=false).
Max Pool Size	100	Максимальное количество подключений, разрешенных в пуле. Допустимые значения больше или равны 1. Значения, которые меньше минимального размера пула , приводят к ошибке.
Min Pool Size	0	Минимальное количество подключений, разрешенных в пуле. Допустимые значения больше или равны 0. Ноль (0) в этом поле означает, что минимальные подключения изначально не открываются. Значения, превышающие максимальный размер пула , приводят к ошибке.
MultipleActiveResultSets	"false"	При trueзначении приложение может поддерживать несколько активных результирующих наборов (MARS). При falseзначении приложение должно обработать или отменить все результирующие наборы из одного пакета, прежде чем оно сможет выполнить любой другой пакет в этом соединении. Распознаются значения true и false. Дополнительные сведения см. в разделе Несколько активных результирующих наборов (MARS).
MultiSubnetFailover	FALSE	Всегда указывайте multiSubnetFailover=True при подключении к прослушивателю группы доступности группы доступности SQL Server 2012 (или более поздней версии) или экземпляра отказоустойчивого кластера SQL Server 2012 (или более поздней версии). multiSubnetFailover=True настраивает SqlClient для ускорения обнаружения активного сервера и подключения к ней. Возможные значения: Yes и No, True и False или 1 и 0. Пример: MultiSubnetFailover=True Значение по умолчанию — False. Дополнительные сведения о поддержке SqlClient для групп доступности Always On см. в статье Поддержка sqlClient для обеспечения высокого уровня доступности и аварийного восстановления.
Network Library -или- Сеть -или- Net	Н/Д	Сетевая библиотека, используемая для подключения к экземпляру SQL Server. Допустимые значения: dbnmpntw (именованные каналы) dbmsrpcn (Multiprotocol, Windows RPC) dbmsadsn (Apple Talk) dbmsgnet (VIA) dbmslpcn (общая память) dbmsspxn (IPX/SPX) dbmssocn (TCP/IP) Dbmsvinn (Баньян Вайнс) Соответствующая сетевая библиотека DLL должна быть установлена на системе, с которой устанавливается соединение. Если сеть не указана и используется локальный сервер (например, "." или "(local)"), используется общая память. В этом примере сетевой библиотекой является Win32 Winsock TCP/IP (dbmssocn), а портом соединения — 1433. Network Library=dbmssocn;Data Source=000.000.000.000,1433;
Packet Size	8000	Размер в байтах сетевых пакетов, используемых для связи с экземпляром SQL Server. Размер пакета может быть больше или равен 512 и меньше или равен 32768.
Пароль -или- PWD	Н/Д	Пароль для входа в учетную запись SQL Server. Не рекомендуется. Для поддержания высокого уровня безопасности настоятельно рекомендуется использовать ключевое Integrated Security слово или Trusted_Connection . SqlCredential— это более безопасный способ указать учетные данные для подключения, использующего проверку подлинности SQL Server. Пароль должен содержать не более 128 символов.
Сохранять сведения о безопасности -или- PersistSecurityInfo	"false"	Если задано значение false или no (настоятельно рекомендуется), конфиденциальные сведения о безопасности, такие как пароль, не возвращаются в составе подключения, если подключение открыто или когда-либо находилось в открытом состоянии. При сбросе строки подключения сбрасываются все значения строки подключения, включая пароль. Допустимые значения: true, false, yes и no.
PoolBlockingPeriod	Auto (Автоматически)	Задает поведение периода блокировки для пула подключений. Подробности см. в свойстве PoolBlockingPeriod.
Pooling	'true'	Если для этого ключа задано значение true, все вновь созданные подключения будут добавлены в пул при закрытии приложением. При следующей попытке открыть то же подключение будет установлено из пула. Подключения считаются одинаковыми, если они имеют одинаковую строку подключения. Разные подключения имеют разные строки подключения. Значение этого ключа может быть "true", "false", "да" или "нет".
Репликация	"false"	true Значение , если репликация поддерживается с помощью подключения.
Transaction Binding	Implicit Unbind	Управляет связью соединения с прикрепленной транзакцией System.Transactions . Возможны следующие значения: Transaction Binding=Implicit Unbind; Transaction Binding=Explicit Unbind; Неявное отмена привязки приводит к отключению соединения от транзакции по завершении. После отсоединения дополнительные запросы к соединению выполняются в режиме автофиксации. Свойство System.Transactions.Transaction.Current не проверяется при выполнении запросов в то время, когда транзакция активна. После завершения транзакции дополнительные запросы выполняются в режиме автофиксации. Если система завершает транзакцию (в области блока using) до завершения последней команды, она вызывает исключение InvalidOperationException. Явная отмена привязки приводит к тому, что соединение остается присоединенным к транзакции до тех пор, пока соединение не будет закрыто или не будет вызвана явная SqlConnection.TransactionEnlist(null) привязка. Начиная с платформа .NET Framework 4, изменения в неявном отмене привязки делают явное отмену привязки устаревшим. Исключение InvalidOperationException выдается, если свойство Transaction.Current не является прикрепленной транзакцией или если прикрепленная транзакция не активна.
TransparentNetworkIPResolution	См. описание.	Если этому ключу присвоено значение true, приложение должно получить все IP-адреса для определенной записи DNS, а затем попытаться подключиться по первому адресу в списке. Если подключение не устанавливается в течение 0,5 секунды, приложение попытается параллельно подключиться по другим адресам. При получении первого ответа приложение устанавливает подключение по соответствующему IP-адресу. MultiSubnetFailover Если для ключа задано значение true, TransparentNetworkIPResolution игнорируется. Failover Partner Если ключ задан, TransparentNetworkIPResolution игнорируется. Значение этого ключа должно быть trueравно , false, yesили no. Значение yes обрабатывается так же, как и значение true. Значение no обрабатывается так же, как и значение false. Значения по умолчанию: false Когда: Подключение к базе данных Azure SQL, где источник данных заканчивается следующим: .database.chinacloudapi.cn .database.usgovcloudapi.net .database.cloudapi.de .database.windows.net Authentication Имеет значение "Active Directory Password" или "Active Directory Integrated" true — во всех остальных случаях.
TrustServerCertificate	"false"	Если задано значение true, ssl используется для шифрования канала при обходе цепочки сертификатов для проверки доверия. Если для TrustServerCertificate задано значение true , а для свойства Encrypt задано значение false, канал не шифруется. Допустимые значения: true, false, yes и no. Дополнительные сведения см. в статье Синтаксис строки подключения.
Версия системы типа	Н/Д	Строковое значение, указывающее систему типов, которую ожидает приложение. Функции, доступные клиентскому приложению, зависят от версии SQL Server и уровня совместимости базы данных. Явное указание системы типов версии СУБД, для которой было написано клиентское приложение, позволяет избежать потенциальных проблем, которые могут привести к сбою приложения при использовании другой версии SQL Server. Примечание: Невозможно задать версию системы типа для кода среды CLR, выполняющегося внутри процесса в SQL Server. Дополнительные сведения см. в статье интеграция SQL Server СРЕДЫ CLR. Возможны следующие значения: Type System Version=SQL Server 2012; Type System Version=SQL Server 2008; Type System Version=SQL Server 2005; Type System Version=Latest; Type System Version=SQL Server 2012; указывает, что приложению потребуется версия 11.0.0.0 Microsoft.SqlServer.Types.dll. Для других Type System Version параметров потребуется версия 10.0.0.0 Microsoft.SqlServer.Types.dll. Latest является устаревшим и не должен использоваться. Latest равно Type System Version=SQL Server 2008;.
User ID -или- ИД пользователя -или- Пользователь	Н/Д	Учетная запись входа SQL Server. Не рекомендуется. Для поддержания высокого уровня безопасности настоятельно рекомендуется использовать ключевые Integrated Security слова или Trusted_Connection . SqlCredential— это более безопасный способ указать учетные данные для подключения, использующего проверку подлинности SQL Server. Идентификатор пользователя должен содержать не более 128 символов.
User Instance	"false"	Значение типа , указывающее, следует ли перенаправлять подключение из экземпляра SQL Server Express по умолчанию в экземпляр, инициированный средой выполнения, работающий под учетной записью вызывающего объекта.
Идентификатор рабочей станции -или- WSID	Имя локального компьютера	Имя рабочей станции, подключающейся к SQL Server. Идентификатор должен содержать не более 128 символов.

В следующем списке содержатся допустимые имена для значений пула подключений в ConnectionString. Дополнительные сведения см. в разделе Пулы подключений SQL Server (ADO.NET).

• Время существования подключения (или время ожидания балансировщика нагрузки)

• Enlist

• Max Pool Size

• Min Pool Size

• Pooling

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

Примечание

Поставщик данных платформа .NET Framework для SQL Server использует собственный протокол для взаимодействия с SQL Server. Таким образом, он не поддерживает использование имени источника данных ODBC (DSN) при подключении к SQL Server поскольку он не добавляет слой ODBC.

Примечание

Универсальные файлы связи с данными (UDL) не поддерживаются поставщиком данных платформа .NET Framework для SQL Server.

Внимание!

В этом выпуске приложение должно соблюдать осторожность при создании строки подключения на основе введенных пользователем данных (например, при получении сведений об идентификаторе пользователя и пароле из диалогового окна и добавлении их в строку подключения). Приложение должно убедиться, что пользователь не может внедрить дополнительные параметры строки подключения в эти значения (например, ввести пароль в виде "validpassword;database=somedb" при попытке присоединиться к другой базе данных). Если необходимо создать строки подключения на основе введенных пользователем данных, используйте новый SqlConnectionStringBuilder, который проверяет строку подключения и помогает устранить эту проблему. Дополнительные сведения см. в разделе Построитель строк подключения .

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

• Управляемые поставщики ADO.NET и центр разработчиков DataSet
• Строки подключения в ADO.NET
• Объединение подключений в пул в SQL Server (ADO.NET)
• Подключение к источнику данных в ADO.NET
• Общие сведения об ADO.NET