SqlConnection Classe

Definição

Representa uma conexão com um banco de dados do SQL Server. Essa classe não pode ser herdada.

public ref class SqlConnection sealed : System::Data::Common::DbConnection, ICloneable
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, IDisposable
public sealed class SqlConnection : 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, IDisposable
type SqlConnection = class
    inherit DbConnection
    interface ICloneable
type SqlConnection = class
    inherit DbConnection
type SqlConnection = class
    inherit Component
    interface IDbConnection
    interface IDisposable
    interface ICloneable
type SqlConnection = class
    inherit DbConnection
    interface IDbConnection
    interface ICloneable
    interface IDisposable
Public NotInheritable Class SqlConnection
Inherits DbConnection
Implements 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, IDisposable
Herança
SqlConnection
Herança
Herança
Implementações

Exemplos

O exemplo a seguir cria um SqlCommand e um SqlConnection. A SqlConnection origem é aberta e definida como a SqlCommandConnection do . Em seguida, o exemplo chama ExecuteNonQuery. Para fazer isso, é ExecuteNonQuery passada uma cadeia de conexão e uma cadeia de caracteres de consulta que é uma instrução INSERT SQL Transact. A conexão é fechada automaticamente quando o código sai do bloco de uso.

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

Comentários

Um SqlConnection objeto representa uma sessão exclusiva para uma fonte de dados SQL Server. Com um sistema de banco de dados cliente/servidor, ele é equivalente a uma conexão de rede com o servidor. SqlConnectioné usado junto com SqlDataAdapter e SqlCommand para aumentar o desempenho ao se conectar a um banco de dados Microsoft SQL Server. Para todos os produtos de SQL Server de terceiros e outras fontes de dados compatíveis com OLE DB, use OleDbConnection.

Quando você cria uma instância de SqlConnection, todas as propriedades são definidas como seus valores iniciais. Para obter uma lista desses valores, consulte o SqlConnection construtor.

Consulte ConnectionString uma lista das palavras-chave em uma cadeia de conexão.

Se o SqlConnection escopo ficar fora do escopo, ele não será fechado. Portanto, você deve fechar explicitamente a conexão chamando Close ou Dispose. Close e Dispose são funcionalmente equivalentes. Se o valor Pooling do pool de conexões for definido true como ou yes, a conexão subjacente será retornada de volta ao pool de conexões. Por outro lado, se Pooling estiver definido como false ou no, a conexão subjacente com o servidor será realmente fechada.

Observação

Eventos de logon e logout não serão gerados no servidor quando uma conexão for procurada de ou retornada para o pool de conexões, porque a conexão não é fechada realmente quando é retornada para o pool de conexões. Para obter mais informações, consulte Pool de Conexões do SQL Server (ADO.NET).

Para garantir que as conexões estejam sempre fechadas, abra a conexão dentro de um using bloco, conforme mostrado no fragmento de código a seguir. Isso garante que a conexão seja fechada automaticamente quando o código sair do bloco.

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.
    }

Observação

Para implantar aplicativos de alto desempenho, você deve usar o pool de conexões. Ao usar o .NET Framework Provedor de Dados para SQL Server, você não precisa habilitar o pool de conexões porque o provedor gerencia isso automaticamente, embora você possa modificar algumas configurações. Para obter mais informações, consulte Pool de Conexões do SQL Server (ADO.NET).

Se um SqlException for gerado pelo método que executa um SqlCommand, ele SqlConnection permanecerá aberto quando o nível de gravidade for 19 ou menos. Quando o nível de gravidade é 20 ou maior, o servidor normalmente fecha o SqlConnection. No entanto, o usuário pode reabrir a conexão e continuar.

Um aplicativo que cria uma instância do SqlConnection objeto pode exigir que todos os chamadores diretos e indiretos tenham permissão suficiente para o código definindo demandas de segurança declarativas ou imperativas. SqlConnection faz demandas de segurança usando o SqlClientPermission objeto. Os usuários podem verificar se seu código tem permissões suficientes usando o SqlClientPermissionAttribute objeto. Usuários e administradores também podem usar o Caspol.exe (Code Access Security Policy Tool) para modificar a política de segurança nos níveis de máquina, usuário e empresa. Para obter mais informações, confira Segurança no .NET. Para obter um exemplo que demonstra como usar as demandas de segurança, consulte Segurança de Acesso ao Código e ADO.NET.

Para obter mais informações sobre como lidar com mensagens informativas e de aviso do servidor, consulte Eventos de Conexão. Para obter mais informações sobre SQL Server erros do mecanismo e mensagens de erro, consulte Mecanismo de Banco de Dados Eventos e Erros.

Cuidado

Você pode forçar o TCP em vez da memória compartilhada. Você pode fazer isso prefixando tcp: para o nome do servidor na cadeia de conexão ou pode usar localhost.

Construtores

SqlConnection()

Inicializa uma nova instância da classe SqlConnection.

SqlConnection(String)

Inicializa uma nova instância da classe SqlConnection quando recebe uma cadeia de caracteres que contém a cadeia de conexão.

SqlConnection(String, SqlCredential)

Inicializa uma nova instância da classe SqlConnection que recebeu uma cadeia de conexão, que não usa Integrated Security = true e um objeto SqlCredential que contém a ID de usuário e senha.

Propriedades

AccessToken

Obtém ou define o token de acesso para a conexão.

CanCreateBatch

Obtém um valor que indica se esta instância DbConnection é compatível com a classe DbBatch.

(Herdado de DbConnection)
CanRaiseEvents

Obtém um valor que indica se o componente pode acionar um evento.

(Herdado de Component)
ClientConnectionId

A ID de conexão da tentativa de conexão mais recente, independentemente de a tentativa ter tido êxito ou ter falhado.

ColumnEncryptionKeyCacheTtl

Obtém ou define a vida útil para entradas de chave de criptografia de coluna no cache de chaves de criptografia de coluna para o recurso Always Encrypted. O valor padrão é 2 horas. 0 significa absolutamente nenhum cache.

ColumnEncryptionQueryMetadataCacheEnabled

Obtém ou define um valor que indica se o cache de metadados da consulta está habilitado (true) ou não (false) em consultas parametrizadas executadas em bancos de dados habilitados para Always Encrypted. O valor padrão é true.

ColumnEncryptionTrustedMasterKeyPaths

Permite que você defina uma lista de caminhos confiáveis de chave para um servidor de banco de dados. Se, durante o processamento de uma consulta de aplicativo, o driver receber um caminho de chave que não constar na lista, a consulta falhará. Esta propriedade fornece proteção adicional contra ataques de segurança que envolvem um SQL Server comprometido fornecendo falsos caminhos principais, que podem levar a vazar credenciais de repositório de chaves.

ConnectionString

Obtém ou define a cadeia de caracteres usada para abrir um banco de dados do SQL Server.

ConnectionTimeout

Obtém o tempo de espera (em segundos) durante a tentativa de estabelecimento da conexão antes que a tentativa seja terminada e um erro seja gerado.

Container

Obtém o IContainer que contém o Component.

(Herdado de Component)
Credential

Obtém ou define o objeto SqlCredential para essa conexão.

Credentials
Database

Obtém o nome do banco de dados atual ou o banco de dados a ser usado após uma conexão ser aberta.

DataSource

Obtém o nome da instância do SQL Server à qual se conectar.

DbProviderFactory

Obtém o DbProviderFactory para este DbConnection.

(Herdado de DbConnection)
DesignMode

Obtém um valor que indica se o Component está no modo de design no momento.

(Herdado de Component)
Events

Obtém a lista de manipuladores de eventos que estão anexados a este Component.

(Herdado de Component)
FireInfoMessageEventOnUserErrors

Obtém ou define a propriedade FireInfoMessageEventOnUserErrors.

PacketSize

Obtém o tamanho (em bytes) de pacotes de rede usados para se comunicar com uma instância do SQL Server.

ServerVersion

Obtém uma cadeia de caracteres que contém a versão da instância do SQL Server à qual o cliente está conectado.

Site

Obtém ou define o ISite do Component.

(Herdado de Component)
State

Indica o estado do SqlConnection durante a operação de rede mais recente realizada na conexão.

StatisticsEnabled

Quando definido como true, permite a coleta de estatísticas para a conexão atual.

WorkstationId

Obtém uma cadeia de caracteres que identifica o cliente do banco de dados.

Métodos

BeginDbTransaction(IsolationLevel)

Quando substituído em uma classe derivada, inicia uma transação de banco de dados.

(Herdado de DbConnection)
BeginDbTransactionAsync(IsolationLevel, CancellationToken)

Inicia de maneira assíncrona uma transação de banco de dados.

(Herdado de DbConnection)
BeginTransaction()

Inicia uma transação de banco de dados.

BeginTransaction(IsolationLevel)

Inicia uma transação de banco de dados com o nível de isolamento especificado.

BeginTransaction(IsolationLevel, String)

Inicia uma transação de banco de dados com o nível de isolamento e nome de transação especificados.

BeginTransaction(String)

Inicia uma transação de banco de dados com o nome da transação especificado.

BeginTransactionAsync(CancellationToken)

Inicia de maneira assíncrona uma transação de banco de dados.

(Herdado de DbConnection)
BeginTransactionAsync(IsolationLevel, CancellationToken)

Inicia de maneira assíncrona uma transação de banco de dados.

(Herdado de DbConnection)
ChangeDatabase(String)

Altera o banco de dados atual para um SqlConnection aberto.

ChangeDatabaseAsync(String, CancellationToken)

Troca de forma assíncrona o banco de dados atual por uma conexão aberta.

(Herdado de DbConnection)
ChangePassword(String, SqlCredential, SecureString)

Altera a senha do SQL Server para o usuário indicado no objeto SqlCredential.

ChangePassword(String, String)

Altera a senha do SQL Server do usuário indicado na cadeia de conexão para a nova senha fornecida.

ClearAllPools()

Esvazia o pool de conexões.

ClearPool(SqlConnection)

Esvazia o pool de conexões associado à conexão especificada.

Close()

Fecha a conexão com o banco de dados. Esse é o método preferencial de fechamento de uma conexão aberta.

CloseAsync()

Fecha de maneira assíncrona a conexão com o banco de dados.

(Herdado de DbConnection)
CreateBatch()

Retorna uma nova instância da classe do provedor que implementa a classe DbBatch .

(Herdado de DbConnection)
CreateCommand()

Cria e retorna um objeto SqlCommand associado ao SqlConnection.

CreateDbBatch()

Quando substituído em uma classe derivada, retorna uma nova instância da classe do provedor que implementa a DbBatch classe.

(Herdado de DbConnection)
CreateDbCommand()

Quando substituído em uma classe derivada, cria e retorna um objeto DbCommand associado à conexão atual.

(Herdado de DbConnection)
CreateObjRef(Type)

Cria um objeto que contém todas as informações relevantes necessárias para gerar um proxy usado para se comunicar com um objeto remoto.

(Herdado de MarshalByRefObject)
Dispose()

Realiza tarefas definidas pelo aplicativo associadas à liberação ou à redefinição de recursos não gerenciados.

(Herdado de DbConnection)
Dispose()

Libera todos os recursos usados pelo Component.

(Herdado de Component)
Dispose(Boolean)

Libera os recursos não gerenciados usados pelo DbConnection e opcionalmente libera os recursos gerenciados.

(Herdado de DbConnection)
Dispose(Boolean)

Libera os recursos não gerenciados usados pelo Component e opcionalmente libera os recursos gerenciados.

(Herdado de Component)
DisposeAsync()

Descarta de forma assíncrona o objeto da conexão.

(Herdado de DbConnection)
EnlistDistributedTransaction(ITransaction)

Inscreve-se na transação especificada como uma transação distribuída.

EnlistTransaction(Transaction)

Inscreve-se na transação especificada como uma transação distribuída.

EnlistTransaction(Transaction)

Inscreve-se na transação especificada.

(Herdado de DbConnection)
Equals(Object)

Determina se o objeto especificado é igual ao objeto atual.

(Herdado de Object)
GetHashCode()

Serve como a função de hash padrão.

(Herdado de Object)
GetLifetimeService()
Obsoleto.

Recupera o objeto de serviço de tempo de vida atual que controla a política de ciclo de vida para esta instância.

(Herdado de MarshalByRefObject)
GetSchema()

Retorna informações de esquema para a fonte de dados deste SqlConnection. Para obter mais informações sobre o esquema, consulte Coleções de esquema do SQL Server.

GetSchema()

Retorna informações de esquema para a fonte de dados deste DbConnection.

(Herdado de DbConnection)
GetSchema(String)

Retorna informações de esquema para a fonte de dados deste SqlConnection usando a cadeia de caracteres especificada para o nome do esquema.

GetSchema(String)

Retorna informações de esquema para a fonte de dados deste DbConnection usando a cadeia de caracteres especificada para o nome do esquema.

(Herdado de DbConnection)
GetSchema(String, String[])

Retorna informações de esquema para a fonte de dados desse SqlConnection usando a cadeia de caracteres especificada para o nome do esquema e a matriz de cadeia de caracteres especificada para os valores de restrição.

GetSchema(String, String[])

Retorna informações de esquema para a fonte de dados desse DbConnection usando a cadeia de caracteres especificada para o nome do esquema e a matriz de cadeia de caracteres especificada para os valores de restrição.

(Herdado de DbConnection)
GetSchemaAsync(CancellationToken)

Essa é uma versão assíncrona de GetSchema(). Provedores devem substituir com uma implementação apropriada. Opcionalmente, o cancellationToken pode ser respeitado. A implementação padrão invoca a chamada GetSchema() síncrona e retorna uma tarefa concluída. A implementação padrão retornará uma tarefa cancelada se já tiver passado um cancellationToken cancelado. Exceções geradas por GetSchema() serão comunicadas por meio da propriedade Exceção de Tarefa retornada.

(Herdado de DbConnection)
GetSchemaAsync(String, CancellationToken)

Essa é a versão assíncrona de GetSchema(String). Provedores devem substituir com uma implementação apropriada. Opcionalmente, o cancellationToken pode ser respeitado. A implementação padrão invoca a chamada GetSchema(String) síncrona e retorna uma tarefa concluída. A implementação padrão retornará uma tarefa cancelada se já tiver passado um cancellationToken cancelado. Exceções geradas por GetSchema(String) serão comunicadas por meio da propriedade Exceção de Tarefa retornada.

(Herdado de DbConnection)
GetSchemaAsync(String, String[], CancellationToken)

Essa é a versão assíncrona de GetSchema(String, String[]). Provedores devem substituir com uma implementação apropriada. Opcionalmente, o cancellationToken pode ser respeitado. A implementação padrão invoca a chamada GetSchema(String, String[]) síncrona e retorna uma tarefa concluída. A implementação padrão retornará uma tarefa cancelada se já tiver passado um cancellationToken cancelado. Exceções geradas por GetSchema(String, String[]) serão comunicadas por meio da propriedade Exceção de Tarefa retornada.

(Herdado de DbConnection)
GetService(Type)

Retorna um objeto que representa um serviço fornecido pelo Component ou pelo seu Container.

(Herdado de Component)
GetType()

Obtém o Type da instância atual.

(Herdado de Object)
InitializeLifetimeService()
Obsoleto.

Obtém um objeto de serviço de tempo de vida para controlar a política de tempo de vida para essa instância.

(Herdado de MarshalByRefObject)
MemberwiseClone()

Cria uma cópia superficial do Object atual.

(Herdado de Object)
MemberwiseClone(Boolean)

Cria uma cópia superficial do objeto MarshalByRefObject atual.

(Herdado de MarshalByRefObject)
OnStateChange(StateChangeEventArgs)

Aciona o evento StateChange.

(Herdado de DbConnection)
Open()

Abre uma conexão de banco de dados com as configurações de propriedade especificadas pelo ConnectionString.

OpenAsync()

Uma versão assíncrona de Open(), que abre uma conexão de banco de dados com as configurações especificadas pelo ConnectionString. Esse método invoca o método virtual OpenAsync(CancellationToken) com CancellationToken.None.

(Herdado de DbConnection)
OpenAsync(CancellationToken)

Uma versão assíncrona de Open(), que abre uma conexão de banco de dados com as configurações de propriedade especificadas pelo ConnectionString. O token de cancelamento pode ser usado para solicitar que a operação seja abandonada antes de expirar o tempo limite da conexão. Exceções serão propagadas por meio da tarefa retornada. Se o tempo limite de conexão sem se conectar com êxito, a tarefa retornada será marcada como com falha com uma exceção. A implementação retorna uma tarefa sem bloquear o thread de chamada para conexões em grupo e não agrupada.

OpenAsync(CancellationToken)

Essa é a versão assíncrona de Open(). Provedores devem substituir com uma implementação apropriada. Opcionalmente, o token de cancelamento pode ser respeitado.

A implementação padrão invoca a chamada Open() síncrona e retorna uma tarefa concluída. A implementação padrão retornará uma tarefa cancelada se já tiver passado um cancellationToken cancelado. Exceções geradas por Open serão comunicadas por meio da propriedade Exceção de Tarefa retornada.

Não invoque outros métodos e propriedades do objeto DbConnection até a Tarefa retornada ser concluída.

(Herdado de DbConnection)
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)

Registra os provedores de repositório de chaves de criptografia de coluna.

ResetStatistics()

Se a coleta de estatísticas estiver habilitada, todos os valores serão redefinidos para zero.

RetrieveStatistics()

Retorna uma coleção de estatísticas de pares nome-valor no momento em que o método é chamado.

ToString()

Retorna uma cadeia de caracteres que representa o objeto atual.

(Herdado de Object)
ToString()

Retorna um String que contém o nome do Component, se houver. Esse método não deve ser substituído.

(Herdado de Component)

Eventos

Disposed

Ocorre quando o componente é disposto por uma chamada ao método Dispose().

(Herdado de Component)
InfoMessage

Ocorre quando o SQL Server retorna um aviso ou uma mensagem informativa.

StateChange

Ocorre quando o estado da conexão é alterado.

StateChange

Ocorre quando o estado da conexão é alterado.

(Herdado de DbConnection)

Implantações explícitas de interface

ICloneable.Clone()

Cria um novo objeto que é uma cópia da instância atual.

IDbConnection.BeginTransaction()

Inicia uma transação de banco de dados.

IDbConnection.BeginTransaction()

Inicia uma transação de banco de dados.

(Herdado de DbConnection)
IDbConnection.BeginTransaction(IsolationLevel)

Inicia uma transação de banco de dados com o valor IsolationLevel especificado.

IDbConnection.BeginTransaction(IsolationLevel)

Inicia uma transação de banco de dados com o nível de isolamento especificado.

(Herdado de DbConnection)
IDbConnection.CreateCommand()

Cria e retorna um objeto Command associado à conexão.

IDbConnection.CreateCommand()

Cria e retorna um objeto DbCommand associado à conexão atual.

(Herdado de DbConnection)

Aplica-se a

Confira também