SqlConnection Classe

Definição

Namespace:

System.Data.SqlClient

Assembly:

System.Data.SqlClient.dll

Pacote:

System.Data.SqlClient v4.8.6

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 sealed class SqlConnection : System.Data.Common.DbConnection, ICloneable

type SqlConnection = class
    inherit DbConnection
    interface ICloneable

Public NotInheritable Class SqlConnection
Inherits DbConnection
Implements ICloneable

Herança

Object

DbConnection

SqlConnection

Implementações

ICloneable

Exemplos

O exemplo a seguir cria um SqlCommand e um SqlConnection. O SqlConnection é aberto e definido como o Connection para o SqlCommand. Em seguida, o exemplo chama ExecuteNonQuery. Para fazer isso, o ExecuteNonQuery é passado um SqlConnection e uma cadeia de caracteres de consulta que é uma instrução INSERT Transact-SQL. A conexão é fechada automaticamente quando o código sai do bloco 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

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 do Microsoft SQL Server. Para todos os produtos de SQL Server de terceiros e outras fontes de dados com suporte do OLE DB, use OleDbConnection.

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

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

Se o SqlConnection sair 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 como true 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 sejam 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 provedor de dados .NET Framework 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, o 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 (Ferramenta de Política de Segurança de Acesso ao Código) para modificar a política de segurança nos níveis do computador, do usuário e da 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 Eventos e erros do Mecanismo de Banco de Dados.

Cuidado

Você pode forçar o TCP em vez de memória compartilhada. Você pode fazer isso prefixando tcp: no nome do servidor no 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)
ClientConnectionId	A ID de conexão da tentativa de conexão mais recente, independentemente de a tentativa ter tido êxito ou ter falhado.
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.
Credential	Obtém ou define o objeto SqlCredential para essa conexão.
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)
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.
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)
Dispose()	Realiza tarefas definidas pelo aplicativo associadas à liberação ou à redefinição de recursos não gerenciados. (Herdado de DbConnection)
Dispose(Boolean)	Libera os recursos não gerenciados usados pelo DbConnection e opcionalmente libera os recursos gerenciados. (Herdado de DbConnection)
DisposeAsync()	Descarta de forma assíncrona o objeto da conexão. (Herdado de DbConnection)
EnlistTransaction(Transaction)	Inscreve-se na transação especificada como uma transação distribuída.
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)
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(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, 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.
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)
GetType()	Obtém o Type da instância atual. (Herdado de Object)
MemberwiseClone()	Cria uma cópia superficial do Object atual. (Herdado de Object)
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.
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)

Eventos

InfoMessage	Ocorre quando o SQL Server retorna um aviso ou uma mensagem informativa.
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.

Confira também

• Conectando-se a uma fonte de dados no ADO.NET
• SQL Server e ADO.NET
• Visão geral do ADO.NET