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


SqlConnection.ConnectionString Свойство

Определение

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

public:
 virtual property System::String ^ ConnectionString { System::String ^ get(); void set(System::String ^ value); };
public:
 property System::String ^ ConnectionString { System::String ^ get(); void set(System::String ^ value); };
public override string ConnectionString { get; set; }
[System.Data.DataSysDescription("SqlConnection_ConnectionString")]
public string ConnectionString { get; set; }
[System.ComponentModel.SettingsBindable(true)]
public override string ConnectionString { get; set; }
member this.ConnectionString : string with get, set
[<System.Data.DataSysDescription("SqlConnection_ConnectionString")>]
member this.ConnectionString : string with get, set
[<System.ComponentModel.SettingsBindable(true)>]
member this.ConnectionString : string with get, set
Public Overrides Property ConnectionString As String
Public Property ConnectionString As String

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

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

Реализации

Атрибуты

Исключения

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

Примеры

В следующем примере создается 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; Встроенное значение Security=true, Database свойство больше не имеет значения AdventureWorks.

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

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

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

Ключевые слова не учитывает регистр.

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

Keyword По умолчанию Описание
Addr N/A Синоним источника данных.
Address N/A Синоним источника данных.
App N/A Синоним имени приложения.
Application Name N/A Имя приложения или поставщика данных 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
–или–
Extended Properties
–или–
Initial File Name
N/A Имя файла базы данных-источника, включая полное имя присоединенной базы данных. AttachDBFilename поддерживается только для основных файлов данных с расширением .mdf.

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

Если этот ключ не указан и если база данных была присоединена ранее, база данных не будет повторно подключена. Ранее присоединенная база данных будет использоваться в качестве базы данных по умолчанию для подключения.

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

Путь может быть абсолютным или относительным с помощью строки подстановки DataDirectory. Если используется DataDirectory, файл базы данных должен существовать в подкаталоге каталога, на который указывает строка подстановки. Примечание: Имена удаленных серверов, HTTP и UNC-путей не поддерживаются.

Имя базы данных должно быть указано с ключевым словом "база данных" (или одним из его псевдонимов), как показано в следующем:

"AttachDbFileName=&#124;DataDirectory&#124;\data\YourDB.mdf;integrated security=true;database=YourDatabase"

Ошибка возникает, если файл журнала существует в том же каталоге, что и файл данных, и ключевое слово "база данных" используется при присоединении первичного файла данных. В этом случае удалите файл журнала. После подключения базы данных новый файл журнала будет автоматически создан на основе физического пути.
Authentication N/A Метод проверки подлинности, используемый для подключения к базе данных SQL с помощью проверки подлинности Azure Active Directory.

Допустимые значения:

Интегрированная служба Active Directory, пароль Active Directory, пароль SQL.
Column Encryption Setting N/A Включает или отключает функции Always Encrypted для подключения.
Connect Timeout
–или–
Connection Timeout
–или–
Timeout
15 Длина времени (в секундах) для ожидания подключения к серверу перед завершением попытки и создания ошибки.

Допустимые значения больше или равно 0 и меньше или равно 2147483647.

При открытии подключения к базе данных SQL Azure задайте время ожидания подключения 30 секунд.
Connection Lifetime
–или–
Load Balance Timeout
0 Если соединение возвращается в пул, время его создания сравнивается с текущим временем и соединение уничтожается, если этот промежуток времени (в секундах) превышает значение, заданное параметром Connection Lifetime. Эта возможность полезна в кластеризованных конфигурациях для принудительной балансировки нагрузки между выполняющимся сервером и сервером, только что переведенным в оперативный режим.

Значение нуля (0) приводит к тому, что пуловые подключения имеют максимальное время ожидания подключения.
ConnectRetryCount 1 Определяет количество попыток повторного подключения после того, как клиент идентифицирует сбой бездействия подключения. Допустимые значения: от 0 до 255. Значение по умолчанию — 1. 0 означает, что не пытаться повторно подключиться (отключить устойчивость подключения).

Дополнительные сведения об устойчивости подключений см. в разделе параметров .NET SqlConnection для повтора подключения и технической статьи по устойчивости бездействия подключений.
ConnectRetryInterval 10 Указывает время между каждой попыткой повтора подключения (ConnectRetryCount). Допустимые значения — от 1 до 60 секунд (по умолчанию=10), примененные после первой попытки повторного подключения. При обнаружении неисправного подключения клиент немедленно пытается повторно подключиться; это первая попытка повторного подключения и возникает только в том случае, если ConnectRetryCount больше 0. Если первая попытка повторного подключения завершается ошибкой, и ConnectRetryCount больше 1, клиент ожидает connectRetryInterval, чтобы попытаться выполнить вторую и последующие попытки повторного подключения.

Дополнительные сведения об устойчивости подключений см. в разделе параметров .NET SqlConnection для повтора подключения и технической статьи по устойчивости бездействия подключений.
Context Connection 'false' Значение , если необходимо выполнить подключение в процессе к SQL Server.
Current Language
–или–
Language
N/A Задает язык, используемый для предупреждений сервера базы данных или сообщений об ошибках.

Имя языка может быть 128 символами или меньше.
Data Source
–или–
Server
–или–
Address
–или–
Addr
–или–
Network Address
N/A Имя или сетевой адрес экземпляра 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:<host name\<instance name>>
— имя tcp:<host,< номер порта TCP>/IP>

Формат TCP должен начинаться с префикса TCP:, за которым следует экземпляр базы данных, как указано именем узла и именем экземпляра. Этот формат не применяется при подключении к базе данных SQL Azure. TCP автоматически выбирается для подключений к базе данных SQL Azure, если протокол не указан.

Имя узла должно быть указано одним из следующих способов:

— NetBIOSName
— IPv4Address
— IPv6Address

Имя экземпляра используется для разрешения определенного номера порта TCP/IP, на котором размещен экземпляр базы данных. Кроме того, можно указать номер порта TCP/IP напрямую. Если имя экземпляра и номер порта отсутствуют, используется экземпляр базы данных по умолчанию.

Формат именованных каналов выглядит следующим образом:

— np:\<\host name>\pipe\pipe\<pipe name>

Формат именованных каналов должен начинаться с префикса "np:" и за ним следует именованное имя канала.

Имя узла должно быть указано одним из следующих способов:

— NetBIOSName
— IPv4Address
— IPv6Address

Имя канала используется для идентификации экземпляра базы данных, к которому будет подключено приложение .NET Framework.

Если задано значение сетевого ключа, не следует указывать префиксы "tcp:" и "np:". Примечание: Вы можете принудительно использовать TCP вместо общей памяти, префиксируя tcp: имя сервера в строке подключения или с помощью localhost.
Encrypt 'false' Когда trueSQL Server использует ssl-шифрование для всех данных, отправляемых между клиентом и сервером, если у сервера установлен сертификат. Допустимые значения: true, false, yes и no. Дополнительные сведения см. в статье Синтаксис строки подключения.

Начиная с .NET Framework 4.5, если TrustServerCertificate имеет значение false и Encrypt имеет значение true, имя сервера (или IP-адрес) в SSL-сертификате SQL Server должно точно совпадать с именем сервера (или IP-адресом), указанным в строке подключения. В противном случае попытка подключения завершится ошибкой.
Enlist 'true' true указывает, что пул подключений SQL Server автоматически заверяет подключение в текущем контексте транзакции потока создания.
Failover Partner N/A Имя сервера партнера отработки отказа, на котором настроено зеркальное отображение базы данных.

Если значение этого ключа равно "", то исходный каталог должен присутствовать, а его значение не должно быть "".

Имя сервера может иметь 128 символов или меньше.

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

Если указать партнера отработки отказа и основной сервер не настроен для зеркального отображения базы данных, подключение к основному серверу (указанному с ключевым словом "Сервер") будет выполнено успешно, если первичный сервер доступен.
Initial Catalog
–или–
Database
N/A Имя базы данных.

Имя базы данных может быть 128 символами или меньше.
Integrated Security
–или–
Trusted_Connection
'false' Когда falseидентификатор пользователя и пароль указываются в соединении. Если trueдля проверки подлинности используются текущие учетные данные учетной записи Windows.

Распознанные значения: true, false, noyesи 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 ЛОЖЬ Всегда указывайте multiSubnetFailover=True при подключении к прослушивателю группы доступности группы доступности SQL Server 2012 (или более поздней версии) или экземпляру отказоустойчивого кластера SQL Server 2012 (или более поздней версии). multiSubnetFailover=True настраивает SqlClient для ускорения обнаружения и подключения к активному серверу (в настоящее время). Возможные значения: Yes и No, True а также False1 и 0. Рассмотрим пример.

MultiSubnetFailover=True

Значение по умолчанию — False. Дополнительные сведения о поддержке SqlClient для групп доступности Always On см. в статье SqlClient Support for High Availability, аварийное восстановление.
Network Library
–или–
Network
–или–
Net
N/A Сетевая библиотека, используемая для установления подключения к экземпляру SQL Server. Допустимые значения:

dbnmpntw (именованные каналы)

dbmsrpcn (Multiprotocol, Windows RPC)

dbmsadsn (Apple Talk)

dbmsgnet (VIA)

dbmslpcn (общая память)

dbmsspxn (IPX/SPX)

dbmssocn (TCP/IP)

Dbmsvinn (Banyan Vines)

Соответствующая сетевая библиотека DLL должна быть установлена в системе, к которой вы подключаетесь. Если вы не указываете сеть и используете локальный сервер (например, "." или "(local)"), используется общая память. В этом примере сетевая библиотека — Win32 Winsock TCP/IP (dbmssocn), а 1433 — используемый порт.

Network Library=dbmssocn;Data Source=000.000.000.000,1433;
Packet Size 8 000 Размер в байтах сетевых пакетов, используемых для взаимодействия с экземпляром SQL Server.

Размер пакета может быть больше или равен 512 и меньше или равен 32768.
Password
–или–
PWD
N/A Пароль для входа в учетную запись SQL Server. Не рекомендуется. Чтобы обеспечить высокий уровень безопасности, настоятельно рекомендуется использовать Integrated Security вместо этого ключевое слово или Trusted_Connection ключевое слово. SqlCredential — это более безопасный способ указания учетных данных для подключения, использующего проверку подлинности SQL Server.

Пароль должен содержать 128 символов или меньше.
Persist Security Info
–или–
PersistSecurityInfo
'false' Если задано false значение или no (настоятельно рекомендуется), конфиденциальные сведения о безопасности, например пароль, не возвращаются как часть подключения, если подключение открыто или когда-либо находилось в открытом состоянии. Сброс строки подключения сбрасывает все значения строки подключения, включая пароль. Допустимые значения: true, false, yes и no.
PoolBlockingPeriod Auto Задает поведение блокирующего периода для пула подключений. Дополнительные сведения см PoolBlockingPeriod . в свойстве.
Pooling 'true' Если для этого ключа задано значение true, все только что созданное соединение будет добавлено в пул при закрытии приложением. При следующей попытке открыть то же подключение будет выполнено из пула.

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

Значение этого ключа может быть "true", "false", "да" или "нет".
Replication 'false' Значение , если репликация поддерживается с помощью подключения.
Transaction Binding Неявная отмена привязки Управляет связью подключения с заверяемой System.Transactions транзакцией.

Возможны следующие значения:

Transaction Binding=Implicit Unbind;

Transaction Binding=Explicit Unbind;

Неявная отмена привязки приводит к отсоединение соединения от транзакции при завершении. После отсоединения дополнительные запросы к подключению выполняются в режиме автокоммитирования. Свойство System.Transactions.Transaction.Current не проверяется при выполнении запросов во время активности транзакции. После завершения транзакции дополнительные запросы выполняются в режиме автокоммитирования.

Если система завершает транзакцию (в области с помощью блока) до завершения последней команды, она вызовет вызов InvalidOperationException.

Явная отмена привязки приводит к тому, что подключение остается присоединенным к транзакции, пока соединение не будет закрыто или явным SqlConnection.TransactionEnlist(null) образом вызывается. Начиная с .NET Framework 4, изменения в неявном отмене привязки вносят явный отменять привязку. Вызывается InvalidOperationException , если Transaction.Current не является включенной транзакцией или если включенная транзакция не активна.
TransparentNetworkIPResolution См. описание. Если задано trueзначение этого ключа, приложение требуется для получения всех IP-адресов для определенной записи DNS и попытки подключиться к первой в списке. Если подключение не установлено в течение 0,5 секунд, приложение попытается подключиться ко всем остальным параллельно. При первом ответе приложение установит соединение с IP-адресом респондента.

MultiSubnetFailover Если для ключа задано trueзначение , TransparentNetworkIPResolution игнорируется.

Failover Partner Если задан ключ, TransparentNetworkIPResolution игнорируется.

Значение этого ключа должно быть true, falseyesили no.

Значение yes обрабатывается так же, как и значение true.

Значение no обрабатывается так же, как и значение false.

Значения по умолчанию приведены ниже:

  • false Когда:

    • Подключение к базе данных SQL Azure, в которой заканчивается источник данных:

      • .database.chinacloudapi.cn
      • .database.usgovcloudapi.net
      • .database.cloudapi.de
      • .database.windows.net
    • Authentication — "Пароль Active Directory" или "Интегрированная служба Active Directory"
  • true во всех остальных случаях.
TrustServerCertificate 'false' Если задано значение true, SSL используется для шифрования канала при обходе цепочки сертификатов для проверки доверия. Если для параметра true TrustServerCertificate задано falseзначение и задано значение Encrypt, канал не шифруется. Допустимые значения: true, false, yes и no. Дополнительные сведения см. в статье Синтаксис строки подключения.
Type System Version N/A Строковое значение, указывающее систему типов, которую ожидает приложение. Функциональные возможности, доступные клиентскому приложению, зависят от версии SQL Server и уровня совместимости базы данных. Явно устанавливая версию системы типа, которую клиентское приложение было написано для предотвращения потенциальных проблем, которые могут привести к разрыву приложения, если используется другая версия SQL Server. Примечание: Системная версия типа не может быть задана для кода среды CLR, выполняющегося в процессе в SQL Server. Дополнительные сведения см. в статье sql Server Common Language Runtime Integration.

Возможны следующие значения:

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.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
–или–
UID
–или–
User
N/A Учетная запись входа SQL Server. Не рекомендуется. Чтобы обеспечить высокий уровень безопасности, настоятельно рекомендуется использовать Integrated Security вместо этого ключевые слова или Trusted_Connection ключевые слова. SqlCredential — это более безопасный способ указания учетных данных для подключения, использующего проверку подлинности SQL Server.

Идентификатор пользователя должен иметь 128 символов или меньше.
User Instance 'false' Значение, указывающее, следует ли перенаправлять подключение из экземпляра SQL Server Express по умолчанию в экземпляр, инициированный средой выполнения, в учетной записи вызывающего объекта.
Workstation ID
–или–
WSID
Имя локального компьютера Имя рабочей станции, подключающейся к SQL Server.

Идентификатор должен иметь 128 символов или меньше.

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

  • Connection Lifetime (или Load Balance Timeout)
  • Enlist
  • Max Pool Size
  • Min Pool Size
  • Pooling

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

Замечание

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

Замечание

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

Предостережение

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

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

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