SqlConnection Класс

Определение

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

Microsoft.Data.SqlClient

Сборка:

Microsoft.Data.SqlClient.dll

Пакет:

Microsoft.Data.SqlClient v5.2.0

Представляет подключение к базе данных 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

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

DbConnection

SqlConnection

Реализации

ICloneable

Примеры

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

using System;
using System.Data;
using Microsoft.Data.SqlClient;

namespace SqlCommandCS
{
    class Program
    {
        static void Main()
        {
            string str = "Data Source=(local);Initial Catalog=Northwind;"
                + "Integrated Security=SSPI";
            string qs = "SELECT OrderID, CustomerID FROM dbo.Orders;";
            CreateCommand(qs, str);
        }
        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();
            }
        }
    }
}

Комментарии

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

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

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

Если объект SqlConnection выходит из область, он не будет закрыт. Поэтому необходимо явно закрыть подключение, вызвав или CloseDispose. 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	Возвращает или задает токен доступа для подключения.
AccessTokenCallback	Возвращает или задает обратный вызов маркера доступа для подключения.
ClientConnectionId	Идентификатор соединения последней попытки подключения, независимо от того, успешно ли выполнена попытка или завершилась ошибкой.
ColumnEncryptionKeyCacheTtl	Возвращает или задает срок жизни для записей ключей шифрования столбцов в кэше ключей шифрования столбцов для функции Always Encrypted. Значение по умолчанию — 2 часа. 0 означает отсутствие кэширования.
ColumnEncryptionQueryMetadataCacheEnabled	Возвращает или задает значение, которое указывает, включено ли кэширование метаданных запроса (True) или нет (False) для параметризованных запросов к базам данных с поддержкой функции Always Encrypted. Значение по умолчанию — true.
ColumnEncryptionTrustedMasterKeyPaths	Позволяет задать список доверенных путей ключа для сервера базы данных. Если при обработке запроса приложения драйвер получает путь к разделу, которого нет в списке, запрос завершится ошибкой. Это свойство обеспечивает дополнительную защиту от атак на систему безопасности, включающих предоставление скомпрометированным SQL Server фиктивных путей ключа, что может привести к утечке учетных данных хранилища ключей.
CommandTimeout	Возвращает время ожидания по умолчанию (в секундах) перед завершением попытки выполнения команды и созданием ошибки. По умолчанию это 30 секунд.
ConnectionString	Получает или задает строку, используемую для открытия базы данных SQL Server.
ConnectionTimeout	Получает время ожидания при попытке установки подключения, по истечении которого попытка подключения завершается и создается ошибка.
Credential	Возвращает или задает объект SqlCredential для этого подключения.
Database	Получает имя текущей базы данных или базы данных, которая будет использоваться после открытия подключения.
DataSource	Получает имя экземпляра SQL Server, к которому осуществляется подключение.
FireInfoMessageEventOnUserErrors	Возвращает или задает свойство FireInfoMessageEventOnUserErrors.
PacketSize	Получает размер сетевых пакетов (в байтах), используемых при взаимодействии с экземпляром SQL Server.
RetryLogicProvider	Получает или задает значение, указывающее объект SqlRetryLogicBaseProvider, связанный с данной командой.
ServerProcessId	Возвращает идентификатор процесса сервера (SPID) активного подключения.
ServerVersion	Получает строку, содержащую версию экземпляра SQL Server, к которому подключается клиент.
State	Отображает состояние SqlConnection во время последней сетевой операции, выполненной по подключению.
StatisticsEnabled	Когда задано значение true, разрешает сбор статистических сведений для текущего подключения.
WorkstationId	Получает строку, определяющую клиента базы данных.

Методы

BeginTransaction()	Начинает транзакцию базы данных.
BeginTransaction(IsolationLevel)	Начинает транзакцию базы данных с указанным уровнем изоляции.
BeginTransaction(IsolationLevel, String)	Начинает транзакцию базы данных с указанным уровнем изоляции и именем транзакции.
BeginTransaction(String)	Начинает транзакцию базы данных с указанным уровнем изоляции.
ChangeDatabase(String)	Осуществляет смену текущей базы данных для открытого соединения SqlConnection.
ChangePassword(String, SqlCredential, SecureString)	Изменяет пароль SQL Server для пользователя, указанного в объекте SqlCredential.
ChangePassword(String, String)	Заменяет пароль SQL Server для пользователя, указанного в строке подключения, заданным новым паролем.
ClearAllPools()	Очищает пул подключений.
ClearPool(SqlConnection)	Очищает пул подключений, связанный с заданным подключением.
Close()	Закрывает соединение с базой данных. Рекомендуется использовать этот метод для закрытия любого открытого подключения.
CreateCommand()	Создает и возвращает объект SqlCommand, связанный с SqlConnection.
GetSchema()	Возвращает сведения схемы для источника данных этого объекта SqlConnection. Дополнительные сведения о схеме см. в разделе Коллекции схемы SQL Server.
GetSchema(String)	Возвращает сведения о схеме для источника данных этого объекта SqlConnection, используя указанную строку в качестве имени схемы.
GetSchema(String, String[])	Возвращает сведения о схеме для источника данных этого объекта SqlConnection, используя указанную строку в качестве имени схемы и указанный массив строк для значений ограничений.
Open()	Открывает подключение к базе данных со значениями свойств, определяемыми объектом ConnectionString.
Open(SqlConnectionOverrides)	Открывает подключение к базе данных со значениями свойств, определяемыми объектом ConnectionString.
OpenAsync(CancellationToken)	Асинхронная версия Open(), которая открывает соединение с базой данных с параметрами свойства, указанными в строке ConnectionString. Чтобы запросить отмену операции до истечения времени ожидания соединения, можно использовать токен отмены. Исключения будут распространяться с помощью возвращаемой задачи. Если время ожидания соединения истекло без успешного подключения, возвращаемая задача будет помечена как сбойная с исключением. Реализация возвращает задачу без блокировки вызывающего потока как для соединений, помещенных в пул, так и соединений вне пула.
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	Регистрирует поставщиков хранилища ключей шифрования столбцов. Эта функция должна вызываться в приложении только один раз. Это выполняет неглубокое копирование словаря, чтобы приложение не могло изменить настраиваемый список поставщиков после его настройки. Встроенные поставщики хранилища главных ключей для столбцов, доступные для хранилища сертификатов Windows, хранилища CNG и CSP, зарегистрированы изначально.
RegisterColumnEncryptionKeyStoreProvidersOnConnection(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	Регистрирует поставщиков хранилища ключей шифрования в экземпляре SqlConnection . Если эта функция была вызвана, все поставщики, зарегистрированные с помощью статических RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>) методов, будут игнорироваться. Эту функцию можно вызывать несколько раз. Это выполняет неглубокое копирование словаря, чтобы приложение не могло изменить настраиваемый список поставщиков после его настройки.
ResetStatistics()	Если сбор статистики разрешен, все значения сбрасываются в нуль.
RetrieveInternalInfo()	Возвращает коллекцию пар значений имен с внутренними свойствами на момент вызова метода .
RetrieveStatistics()	Возвращает коллекцию пар имя-значение статистических данных на момент вызова метода.

События

InfoMessage

Возникает, когда SQL Server возвращает предупреждение или информационное сообщение.

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

ICloneable.Clone()

Создает новый объект, являющийся копией текущего экземпляра.