SqlConnection Classe

Referência

Definição

Namespace:: System.Data.SqlClient

Assembly:: System.Data.SqlClient.dll

Assembly:: System.Data.dll

Assemblies:: netstandard.dll, System.Data.SqlClient.dll

Pacote:: System.Data.SqlClient v4.8.6

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 do SQL Server. Essa classe não pode ser herdada.

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

Herança: Object

DbConnection
SqlConnection

Herança: Object

MarshalByRefObject

Component

DbConnection
SqlConnection

Herança: Object

MarshalByRefObject

Component
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 para o SqlCommand. Em seguida, o exemplo chama ExecuteNonQuery. Para fazer isso, é 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 do 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 do 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 uma 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 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.

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 Provedor de Dados do .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 severidade for 19 ou menos. Quando o nível de severidade é 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 erros e mensagens de erro do mecanismo do SQL Server, 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: 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.
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

Compartilhar via