SqlConnection Classe

Definição

Namespace:: System.Data.SqlClient

Assembly:: System.Data.dll

Importante

Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

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

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.ComponentModel.Component, ICloneable, IDisposable, System.Data.IDbConnection

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

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

type SqlConnection = class
    inherit DbConnection
    interface ICloneable

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

Public NotInheritable Class SqlConnection
Inherits DbConnection
Implements ICloneable

Herança: Object

MarshalByRefObject

Component
SqlConnection

Herança: Object

MarshalByRefObject

Component

DbConnection
SqlConnection

Implementações: IDbConnection ICloneable IDisposable

Exemplos

O exemplo a seguir cria um SqlCommand e um SqlConnection. O SqlConnection é aberto e definido como o Connection .SqlCommand Em seguida, o exemplo chama ExecuteNonQuery. Para fazer isso, o ExecuteNonQuery é passado por 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 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 objeto SqlConnection 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 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 para obter uma lista das palavras-chave em um cadeia de conexão.

Se o SqlConnection escopo sair, 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 estiver 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 false como ou no, a conexão subjacente com o servidor será realmente fechada.

Note

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 SQL Server Connection Pooling (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.
    }

Note

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 SQL Server Connection Pooling (ADO.NET).

Se um SqlException for gerado pelo método que executa um SqlCommand, ele SqlConnection permanecerá aberto quando o nível de severidade 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 declarativas ou imperativas de segurança. SqlConnection faz com que as demandas de segurança usem 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 de máquina, usuário e empresa. Para obter mais informações, consulte Segurança no .NET. Para obter um exemplo que demonstra como usar demandas de segurança, consulte Segurança de Acesso ao Código e ADO.NET.

Para obter mais informações sobre como lidar com avisos e mensagens informativas 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.

Caution

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

Nome	Description
SqlConnection()	Inicializa uma nova instância da classe SqlConnection.
SqlConnection(String, SqlCredential)	Inicializa uma nova instância da SqlConnection classe dada uma cadeia de conexão, que não usa `Integrated Security = true` e um SqlCredential objeto que contém a ID de usuário e a senha.
SqlConnection(String)	Inicializa uma nova instância da SqlConnection classe quando determinada uma cadeia de caracteres que contém a cadeia de conexão.

Propriedades

Nome	Description
AccessToken	Obtém ou define o token de acesso para a conexão.
CanRaiseEvents	Obtém um valor que indica se o componente pode gerar um evento. (Herdado de Component)
ClientConnectionId	A ID de conexão da tentativa de conexão mais recente, independentemente de a tentativa ter sido bem-sucedida ou falhar.
ColumnEncryptionKeyCacheTtl	Obtém ou define o tempo de 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 nenhum cache.
ColumnEncryptionQueryMetadataCacheEnabled	Obtém ou define um valor que indica se o cache de metadados de consulta está habilitado (true) ou não (false) para consultas parametrizadas em execução 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 está na lista, a consulta falhará. Essa propriedade fornece proteção adicional contra ataques de segurança que envolvem um SQL Server comprometido fornecendo caminhos de chave falsos, o que pode levar ao vazamento de credenciais do 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) ao tentar estabelecer uma conexão antes de encerrar a tentativa e gerar um erro.
Container	Obtém o IContainer que contém o Component. (Herdado de Component)
Credential	Obtém ou define o SqlCredential objeto para essa conexão.
Database	Obtém o nome do banco de dados atual ou do banco de dados a ser usado depois que uma conexão é aberta.
DataSource	Obtém o nome da instância do SQL Server à qual se conectar.
DbProviderFactory	Obtém o DbProviderFactory para isso 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 anexados a isso Component. (Herdado de Component)
FireInfoMessageEventOnUserErrors	Obtém ou define a FireInfoMessageEventOnUserErrors propriedade.
PacketSize	Obtém o tamanho (em bytes) de pacotes de rede usados para se comunicar com uma instância de 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 da operação de SqlConnection rede mais recente executada na conexão.
StatisticsEnabled	Quando definido como , habilita a `true`coleta de estatísticas para a conexão atual.
WorkstationId	Obtém uma cadeia de caracteres que identifica o cliente de banco de dados.

Métodos

Nome	Description
BeginDbTransaction(IsolationLevel)	Quando substituído em uma classe derivada, inicia uma transação de banco de dados. (Herdado de DbConnection)
BeginTransaction()	Inicia uma transação de banco de dados.
BeginTransaction(IsolationLevel, String)	Inicia uma transação de banco de dados com o nível de isolamento e o nome da transação especificados.
BeginTransaction(IsolationLevel)	Inicia uma transação de banco de dados com o nível de isolamento especificado.
BeginTransaction(String)	Inicia uma transação de banco de dados com o nome da transação especificado.
ChangeDatabase(String)	Altera o banco de dados atual para um aberto SqlConnection.
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 para o usuário indicado na cadeia de conexão para a nova senha especificada.
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 para fechar qualquer conexão aberta.
CreateCommand()	Cria e retorna um SqlCommand objeto associado ao SqlConnection.
CreateDbCommand()	Quando substituído em uma classe derivada, cria e retorna um DbCommand objeto 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()	Libera todos os recursos usados pelo Component. (Herdado de Component)
Dispose(Boolean)	Libera os recursos não gerenciados usados pelo Component e, opcionalmente, libera os recursos gerenciados. (Herdado de Component)
EnlistDistributedTransaction(ITransaction)	Inscrição na transação especificada como uma transação distribuída.
EnlistTransaction(Transaction)	Inscrição 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 hash predefinida. (Herdado de Object)
GetLifetimeService()	Recupera o objeto de serviço de tempo de vida atual que controla a política de tempo de vida para essa instância. (Herdado de MarshalByRefObject)
GetSchema()	Retorna informações de esquema para a fonte de dados deste SqlConnection. Para obter mais informações sobre esquema, consulte SQL Server Schema Collections.
GetSchema(String, String[])	Retorna informações de esquema para a fonte de dados disso 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)	Retorna informações de esquema para a fonte de dados disso SqlConnection usando a cadeia de caracteres especificada para o nome do esquema.
GetService(Type)	Retorna um objeto que representa um serviço fornecido pelo Component ou por sua Container. (Herdado de Component)
GetType()	Obtém o Type da instância atual. (Herdado de Object)
InitializeLifetimeService()	Obtém um objeto de serviço de tempo de vida para controlar a política de tempo de vida dessa instância. (Herdado de MarshalByRefObject)
MemberwiseClone()	Cria uma cópia superficial do Objectatual. (Herdado de Object)
MemberwiseClone(Boolean)	Cria uma cópia superficial do objeto atual MarshalByRefObject . (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 , que abre uma conexão de banco de Open()dados com as configurações especificadas pelo ConnectionString. Esse método invoca o método OpenAsync(CancellationToken) virtual com CancellationToken.None. (Herdado de DbConnection)
OpenAsync(CancellationToken)	Uma versão assíncrona de , que abre uma conexão de banco de Open()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 que o tempo limite da conexão se esvaia. As exceções serão propagadas por meio da Tarefa retornada. Se o tempo limite de conexão tiver decorrido sem se conectar com êxito, a Tarefa retornada será marcada como falha com uma exceção. A implementação retorna uma Tarefa sem bloquear o thread de chamada para conexões em pool e não em pool.
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 par de valor de nome no momento em que o método é chamado.
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

Nome	Description
Disposed	Ocorre quando o componente é descartado por uma chamada para o Dispose() método. (Herdado de Component)
InfoMessage	Ocorre quando SQL Server retorna um aviso ou 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

Nome	Description
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 especificado IsolationLevel .
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 DbCommand objeto associado à conexão atual. (Herdado de DbConnection)

Aplica-se a

Confira também

Comentários

Esta página foi útil?