SqlConnection Класс

Определение

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

System.Data.SqlClient

Сборка:

System.Data.dll

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

public ref class SqlConnection sealed : System::Data::Common::DbConnection, ICloneable

public sealed class SqlConnection : System.Data.Common.DbConnection, ICloneable

type SqlConnection = class
    inherit DbConnection
    interface ICloneable

Public NotInheritable Class SqlConnection
Inherits DbConnection
Implements ICloneable

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

Object

MarshalByRefObject

Component

DbConnection

SqlConnection

Реализации

ICloneable

Примеры

В следующем примере производится создание объектов SqlCommand и SqlConnection. Соединение SqlConnection открыто и задано в свойстве Connection объекта SqlCommand. Затем в примере вызывается ExecuteNonQuery. Для этого ExecuteNonQuery передается sqlConnection и строка запроса, которая является инструкцией Transact-SQL INSERT. Соединение закрывается автоматически при выходе кода из блока using.

private static void CreateCommand(string queryString,
    string connectionString)
{
    using (SqlConnection connection = new SqlConnection(
               connectionString))
    {
        SqlCommand command = new SqlCommand(queryString, connection);
        command.Connection.Open();
        command.ExecuteNonQuery();
    }
}

Public Sub CreateCommand(ByVal queryString As String, _
  ByVal connectionString As String)
    Using connection As New SqlConnection(connectionString)
        Dim command As New SqlCommand(queryString, connection)
        command.Connection.Open()
        command.ExecuteNonQuery()
    End Using
End Sub

Комментарии

Объект SqlConnection представляет уникальный сеанс для источника данных SQL Server. В системе баз данных клиента или сервера это эквивалентно сетевому подключению к серверу. SqlConnection используется вместе с SqlDataAdapter и SqlCommand для повышения производительности при подключении к базе данных Microsoft SQL Server. Для всех сторонних продуктов SQL Server и других источников данных, поддерживаемых OLE DB, используйте .OleDbConnection

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

Список ConnectionString ключевых слов в строке подключения см. в этой статье.

Если объект SqlConnection выходит за пределы области, он не будет закрыт. Поэтому необходимо явно закрыть соединение, вызвав Close или Dispose. Close и Dispose функционально эквивалентны. Если значение Pooling пула подключений равно true или yes, базовое подключение возвращается обратно в пул подключений. С другой стороны, если Pooling для задано значение false или no, базовое подключение к серверу фактически закрывается.

Примечание

События входа в систему и выхода из системы не вызываются на сервере при выборке подключения из пула подключений и при возврате его в пул подключений, поскольку при возврате в пул подключений подключение фактически не закрывается. Дополнительные сведения см. в разделе Пулы подключений SQL Server (ADO.NET).

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

Using connection As New SqlConnection(connectionString)
    connection.Open()
    ' Do work here; connection closed on following line.
End Using

using (SqlConnection connection = new SqlConnection(connectionString))
    {
        connection.Open();
        // Do work here; connection closed on following line.
    }

Примечание

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

SqlException Если создается методом, выполняющим SqlCommand, SqlConnection объект остается открытым, если уровень серьезности равен 19 или меньше. Если уровень серьезности равен 20 или выше, сервер обычно закрывает SqlConnection. Тем не менее, пользователь может опять открыть подключение и продолжить работу.

Приложение, создающее экземпляр SqlConnection объекта , может требовать, чтобы все прямые и косвенные вызывающие объекты имели достаточные разрешения на доступ к коду, устанавливая декларативные или императивные требования безопасности. SqlConnection предъявляет требования к безопасности с помощью SqlClientPermission объекта . Пользователи могут убедиться, что их код имеет достаточные разрешения, используя SqlClientPermissionAttribute объект . Пользователи и администраторы также могут использовать Caspol.exe (средство политики безопасности доступа к коду) для изменения политики безопасности на уровне компьютера, пользователя и предприятия. Дополнительные сведения см. в разделе Безопасность в .NET. Пример использования требований безопасности см. в разделе Безопасность доступа к коду и ADO.NET.

Дополнительные сведения об обработке предупреждений и информационных сообщений от сервера см. в разделе События подключения. Дополнительные сведения об ошибках и сообщениях об ошибках ядра SQL Server см. в разделе События и ошибки ядра СУБД.

Внимание!

Вы можете принудительно использовать TCP вместо общей памяти. Для этого можно задать префикс tcp: к имени сервера в строке подключения или использовать localhost.

Конструкторы

SqlConnection()	Инициализирует новый экземпляр класса SqlConnection.
SqlConnection(String)	Инициализирует новый экземпляр класса SqlConnection после получения строки, содержащей строку соединения.
SqlConnection(String, SqlCredential)	Инициализирует новый экземпляр класса SqlConnection, используя строку подключения, в которой не используется Integrated Security = true, и объект SqlCredential, содержащий идентификатор пользователя и пароль.

Свойства

AccessToken	Возвращает или задает токен доступа для подключения.
CanCreateBatch	Возвращает значение, определяющее, поддерживает ли экземпляр DbConnection класс DbBatch. (Унаследовано от DbConnection)
CanRaiseEvents	Возвращает значение, показывающее, может ли компонент вызывать событие. (Унаследовано от Component)
ClientConnectionId	Идентификатор соединения последней попытки подключения, независимо от того, успешно ли выполнена попытка или завершилась ошибкой.
ColumnEncryptionKeyCacheTtl	Возвращает или задает срок жизни для записей ключей шифрования столбцов в кэше ключей шифрования столбцов для функции Always Encrypted. Значение по умолчанию — 2 часа. 0 означает отсутствие кэширования.
ColumnEncryptionQueryMetadataCacheEnabled	Возвращает или задает значение, которое указывает, включено ли кэширование метаданных запроса (True) или нет (False) для параметризованных запросов к базам данных с поддержкой функции Always Encrypted. Значение по умолчанию — true.
ColumnEncryptionTrustedMasterKeyPaths	Позволяет задать список доверенных путей ключа для сервера базы данных. Если при обработке запроса приложения драйвер получает путь к разделу, которого нет в списке, запрос завершится ошибкой. Это свойство обеспечивает дополнительную защиту от атак на систему безопасности, включающих предоставление скомпрометированным SQL Server фиктивных путей ключа, что может привести к утечке учетных данных хранилища ключей.
ConnectionString	Получает или задает строку, используемую для открытия базы данных SQL Server.
ConnectionTimeout	Возвращает значение времени ожидания (в секундах) при попытке установления подключения, по истечении которого процедура завершается и генерируется ошибка.
Container	Возвращает объект IContainer, который содержит коллекцию Component. (Унаследовано от Component)
Credential	Возвращает или задает объект SqlCredential для этого подключения.
Database	Получает имя текущей базы данных или базы данных, которая будет использоваться после открытия подключения.
DataSource	Получает имя экземпляра SQL Server, к которому осуществляется подключение.
DbProviderFactory	Получает объект DbProviderFactory для данного элемента DbConnection. (Унаследовано от DbConnection)
DesignMode	Возвращает значение, указывающее, находится ли данный компонент Component в режиме конструктора в настоящее время. (Унаследовано от Component)
Events	Возвращает список обработчиков событий, которые прикреплены к этому объекту Component. (Унаследовано от Component)
FireInfoMessageEventOnUserErrors	Возвращает или задает свойство FireInfoMessageEventOnUserErrors.
PacketSize	Получает размер сетевых пакетов (в байтах), используемых при взаимодействии с экземпляром SQL Server.
ServerVersion	Получает строку, содержащую версию экземпляра SQL Server, к которому подключается клиент.
Site	Получает или задает ISite объекта Component. (Унаследовано от Component)
State	Отображает состояние SqlConnection во время последней сетевой операции, выполненной по подключению.
StatisticsEnabled	Когда задано значение true, разрешает сбор статистических сведений для текущего подключения.
WorkstationId	Получает строку, определяющую клиента базы данных.

Методы

BeginDbTransaction(IsolationLevel)	При переопределении в производном классе запускает транзакцию в базе данных. (Унаследовано от DbConnection)
BeginDbTransactionAsync(IsolationLevel, CancellationToken)	Асинхронно запускает транзакцию в базе данных. (Унаследовано от DbConnection)
BeginTransaction()	Начинает транзакцию базы данных.
BeginTransaction(IsolationLevel)	Начинает транзакцию базы данных с указанным уровнем изоляции.
BeginTransaction(IsolationLevel, String)	Начинает транзакцию базы данных с указанным уровнем изоляции и именем транзакции.
BeginTransaction(String)	Начинает транзакцию базы данных с указанным уровнем изоляции.
BeginTransactionAsync(CancellationToken)	Асинхронно начинает транзакцию базы данных. (Унаследовано от DbConnection)
BeginTransactionAsync(IsolationLevel, CancellationToken)	Асинхронно начинает транзакцию базы данных. (Унаследовано от DbConnection)
ChangeDatabase(String)	Осуществляет смену текущей базы данных для открытого соединения SqlConnection.
ChangeDatabaseAsync(String, CancellationToken)	Асинхронно изменяет текущую базу данных для открытого подключения. (Унаследовано от DbConnection)
ChangePassword(String, SqlCredential, SecureString)	Изменяет пароль SQL Server для пользователя, указанного в объекте SqlCredential.
ChangePassword(String, String)	Заменяет пароль SQL Server для пользователя, указанного в строке подключения, заданным новым паролем.
ClearAllPools()	Очищает пул подключений.
ClearPool(SqlConnection)	Очищает пул подключений, связанный с заданным подключением.
Close()	Закрывает соединение с базой данных. Рекомендуется использовать этот метод для закрытия любого открытого подключения.
CloseAsync()	Асинхронно закрывает подключение к базе данных. (Унаследовано от DbConnection)
CreateBatch()	Возвращает новый экземпляра класса поставщика, реализующий класс DbBatch. (Унаследовано от DbConnection)
CreateCommand()	Создает и возвращает объект SqlCommand, связанный с SqlConnection.
CreateDbBatch()	При переопределении в производном классе возвращает новый экземпляр класса поставщика, который реализует DbBatch класс . (Унаследовано от DbConnection)
CreateDbCommand()	При переопределении в производном классе создает и возвращает объект DbCommand, связанный с текущим подключением. (Унаследовано от DbConnection)
CreateObjRef(Type)	Создает объект, который содержит всю необходимую информацию для создания прокси-сервера, используемого для взаимодействия с удаленным объектом. (Унаследовано от MarshalByRefObject)
Dispose()	Выполняет определяемые приложением задачи, связанные с удалением, высвобождением или сбросом неуправляемых ресурсов. (Унаследовано от DbConnection)
Dispose(Boolean)	Освобождает неуправляемые ресурсы, используемые объектом DbConnection, а при необходимости освобождает также управляемые ресурсы. (Унаследовано от DbConnection)
DisposeAsync()	Асинхронно размещает объект подключения. (Унаследовано от DbConnection)
EnlistDistributedTransaction(ITransaction)	Выполняет присоединение указанной транзакции как распределенной транзакции.
EnlistTransaction(Transaction)	Выполняет присоединение указанной транзакции как распределенной транзакции.
Equals(Object)	Определяет, равен ли указанный объект текущему объекту. (Унаследовано от Object)
GetHashCode()	Служит хэш-функцией по умолчанию. (Унаследовано от Object)
GetLifetimeService()	Извлекает объект обслуживания во время существования, который управляет политикой времени существования данного экземпляра. (Унаследовано от MarshalByRefObject)
GetSchema()	Возвращает сведения схемы для источника данных этого объекта SqlConnection. Дополнительные сведения о схеме см. в разделе Коллекции схемы SQL Server.
GetSchema(String)	Возвращает сведения о схеме для источника данных этого объекта SqlConnection, используя указанную строку в качестве имени схемы.
GetSchema(String, String[])	Возвращает сведения о схеме для источника данных этого объекта SqlConnection, используя указанную строку в качестве имени схемы и указанный массив строк для значений ограничений.
GetSchemaAsync(CancellationToken)	Это асинхронная версия метода GetSchema(). Поставщики должны выполнить переопределение с помощью соответствующей реализации. При необходимости можно учитывать cancellationToken. Реализация по умолчанию вызывает синхронный метод GetSchema() и возвращает выполненную задачу. Реализация по умолчанию возвращает отмененную задачу, если ей передается уже отмененный cancellationToken. Исключения, создаваемые GetSchema(), будут связаны через возвращаемое свойство исключения задачи. (Унаследовано от DbConnection)
GetSchemaAsync(String, CancellationToken)	Это асинхронная версия метода GetSchema(String). Поставщики должны выполнить переопределение с помощью соответствующей реализации. При необходимости можно учитывать cancellationToken. Реализация по умолчанию вызывает синхронный метод GetSchema(String) и возвращает выполненную задачу. Реализация по умолчанию возвращает отмененную задачу, если ей передается уже отмененный cancellationToken. Исключения, создаваемые GetSchema(String), будут связаны через возвращаемое свойство исключения задачи. (Унаследовано от DbConnection)
GetSchemaAsync(String, String[], CancellationToken)	Это асинхронная версия метода GetSchema(String, String[]). Поставщики должны выполнить переопределение с помощью соответствующей реализации. При необходимости можно учитывать cancellationToken. Реализация по умолчанию вызывает синхронный метод GetSchema(String, String[]) и возвращает выполненную задачу. Реализация по умолчанию возвращает отмененную задачу, если ей передается уже отмененный cancellationToken. Исключения, создаваемые GetSchema(String, String[]), будут связаны через возвращаемое свойство исключения задачи. (Унаследовано от DbConnection)
GetService(Type)	Возвращает объект, представляющий службу, предоставляемую классом Component или классом Container. (Унаследовано от Component)
GetType()	Возвращает объект Type для текущего экземпляра. (Унаследовано от Object)
InitializeLifetimeService()	Получает объект службы времени существования для управления политикой времени существования для этого экземпляра. (Унаследовано от MarshalByRefObject)
MemberwiseClone()	Создает неполную копию текущего объекта Object. (Унаследовано от Object)
MemberwiseClone(Boolean)	Создает неполную копию текущего объекта MarshalByRefObject. (Унаследовано от MarshalByRefObject)
OnStateChange(StateChangeEventArgs)	Вызывает событие StateChange. (Унаследовано от DbConnection)
Open()	Открывает подключение к базе данных со значениями свойств, определяемыми объектом ConnectionString.
OpenAsync()	Асинхронная версия Open(), которая открывает соединение с базой данных с параметрами, указанными ConnectionString. Этот метод вызывает виртуальный метод OpenAsync(CancellationToken) с CancellationToken.None. (Унаследовано от DbConnection)
OpenAsync(CancellationToken)	Асинхронная версия Open(), которая открывает соединение с базой данных с параметрами свойства, указанными в строке ConnectionString. Чтобы запросить отмену операции до истечения времени ожидания соединения, можно использовать токен отмены. Исключения будут распространяться с помощью возвращаемой задачи. Если время ожидания соединения истекло без успешного подключения, возвращаемая задача будет помечена как сбойная с исключением. Реализация возвращает задачу без блокировки вызывающего потока как для соединений, помещенных в пул, так и соединений вне пула.
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	Регистрирует поставщиков хранилища ключей шифрования столбцов.
ResetStatistics()	Если сбор статистики разрешен, все значения сбрасываются в нуль.
RetrieveStatistics()	Возвращает коллекцию пар имя-значение статистических данных на момент вызова метода.
ToString()	Возвращает объект String, содержащий имя Component, если оно есть. Этот метод не следует переопределять. (Унаследовано от Component)

События

Disposed	Возникает при удалении компонента путем вызова метода Dispose(). (Унаследовано от Component)
InfoMessage	Возникает, когда SQL Server возвращает предупреждение или информационное сообщение.
StateChange	Возникает при изменении состояния подключения. (Унаследовано от DbConnection)

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

ICloneable.Clone()	Создает новый объект, являющийся копией текущего экземпляра.
IDbConnection.BeginTransaction()	Начинает транзакцию базы данных. (Унаследовано от DbConnection)
IDbConnection.BeginTransaction(IsolationLevel)	Начинает транзакцию базы данных с указанным уровнем изоляции. (Унаследовано от DbConnection)
IDbConnection.CreateCommand()	Создает и возвращает объект DbCommand, связанный с текущим подключением. (Унаследовано от DbConnection)

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

• Подключение к источнику данных в ADO.NET
• SQL Server и ADO.NET
• Общие сведения об ADO.NET