SqlConnection Класс

Ссылка

Определение

Пространство имен:: System.Data.SqlClient

Сборка:: System.Data.SqlClient.dll

Сборка:: System.Data.dll

Сборки:: netstandard.dll, System.Data.SqlClient.dll

Пакет:: System.Data.SqlClient v4.8.6

Важно!

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

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

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

public ref class SqlConnection sealed : System::ComponentModel::Component, ICloneable, IDisposable, System::Data::IDbConnection

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

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

public sealed class SqlConnection : System.ComponentModel.Component, ICloneable, IDisposable, System.Data.IDbConnection

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

type SqlConnection = class
    inherit DbConnection

type SqlConnection = class
    inherit Component
    interface IDbConnection
    interface IDisposable
    interface ICloneable

type SqlConnection = class
    inherit DbConnection
    interface ICloneable

Public NotInheritable Class SqlConnection
Inherits DbConnection

Public NotInheritable Class SqlConnection
Inherits Component
Implements ICloneable, IDbConnection, IDisposable

Public NotInheritable Class SqlConnection
Inherits DbConnection
Implements ICloneable

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

DbConnection
SqlConnection

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

MarshalByRefObject

Component

DbConnection
SqlConnection

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

MarshalByRefObject

Component
SqlConnection

Реализации: IDbConnection ICloneable IDisposable

Примеры

В следующем примере производится создание объектов 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()	Освобождает все ресурсы, занятые модулем Component. (Унаследовано от Component)
Dispose(Boolean)	Освобождает неуправляемые ресурсы, используемые объектом DbConnection, а при необходимости освобождает также управляемые ресурсы. (Унаследовано от DbConnection)
Dispose(Boolean)	Освобождает неуправляемые ресурсы, используемые объектом Component, а при необходимости освобождает также управляемые ресурсы. (Унаследовано от Component)
DisposeAsync()	Асинхронно размещает объект подключения. (Унаследовано от DbConnection)
EnlistDistributedTransaction(ITransaction)	Выполняет присоединение указанной транзакции как распределенной транзакции.
EnlistTransaction(Transaction)	Выполняет присоединение указанной транзакции как распределенной транзакции.
EnlistTransaction(Transaction)	Выполняет прикрепление в указанной транзакции. (Унаследовано от DbConnection)
Equals(Object)	Определяет, равен ли указанный объект текущему объекту. (Унаследовано от Object)
GetHashCode()	Служит хэш-функцией по умолчанию. (Унаследовано от Object)
GetLifetimeService()	Устаревшие.. Извлекает объект обслуживания во время существования, который управляет политикой времени существования данного экземпляра. (Унаследовано от MarshalByRefObject)
GetSchema()	Возвращает сведения схемы для источника данных этого объекта SqlConnection. Дополнительные сведения о схеме см. в разделе Коллекции схемы SQL Server.
GetSchema()	Возвращает сведения схемы для источника данных этого объекта DbConnection. (Унаследовано от DbConnection)
GetSchema(String)	Возвращает сведения о схеме для источника данных этого объекта SqlConnection, используя указанную строку в качестве имени схемы.
GetSchema(String)	Возвращает сведения о схеме для источника данных этого объекта DbConnection, используя указанную строку в качестве имени схемы. (Унаследовано от DbConnection)
GetSchema(String, String[])	Возвращает сведения о схеме для источника данных этого объекта SqlConnection, используя указанную строку в качестве имени схемы и указанный массив строк для значений ограничений.
GetSchema(String, String[])	Возвращает сведения о схеме для источника данных этого объекта DbConnection, используя указанную строку в качестве имени схемы и указанный массив строк для значений ограничений. (Унаследовано от DbConnection)
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. Чтобы запросить отмену операции до истечения времени ожидания соединения, можно использовать токен отмены. Исключения будут распространяться с помощью возвращаемой задачи. Если время ожидания соединения истекло без успешного подключения, возвращаемая задача будет помечена как сбойная с исключением. Реализация возвращает задачу без блокировки вызывающего потока как для соединений, помещенных в пул, так и соединений вне пула.
OpenAsync(CancellationToken)	Это асинхронная версия метода Open(). Поставщики должны выполнить переопределение с помощью соответствующей реализации. При необходимости можно учитывать токен отмены. Реализация по умолчанию вызывает синхронный метод Open() и возвращает выполненную задачу. Реализация по умолчанию возвращает отмененную задачу, если ей передается уже отмененный cancellationToken. Исключения, создаваемые Open, будут связаны через возвращаемое свойство исключения задачи. Не вызывайте другие методы и свойства объекта `DbConnection` до тех пор, пока возвращаемая задача не будет завершена. (Унаследовано от DbConnection)
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	Регистрирует поставщиков хранилища ключей шифрования столбцов.
ResetStatistics()	Если сбор статистики разрешен, все значения сбрасываются в нуль.
RetrieveStatistics()	Возвращает коллекцию пар имя-значение статистических данных на момент вызова метода.
ToString()	Возвращает строку, представляющую текущий объект. (Унаследовано от Object)
ToString()	Возвращает объект String, содержащий имя Component, если оно есть. Этот метод не следует переопределять. (Унаследовано от Component)

События

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

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

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

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

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