SqlConnection Classe
Definição
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::Data::Common::DbConnection, ICloneablepublic sealed class SqlConnection : System.Data.Common.DbConnection, ICloneabletype SqlConnection = class
inherit DbConnection
interface ICloneablePublic NotInheritable Class SqlConnection
Inherits DbConnection
Implements ICloneable- Herança
-
SqlConnection
- Implementações
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.
using System;
using System.Data;
using Microsoft.Data.SqlClient;
namespace SqlCommand_ExecuteNonQuery
{
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();
}
}
}
}
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.
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 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.
}
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 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 |
| 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. |
| AccessTokenCallback |
Obtém ou define o retorno de chamada do token de acesso para a conexão. |
| CanCreateBatch |
Obtém um valor que indica se essa SqlConnection instância dá suporte à DbBatch classe. |
| 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. |
| CommandTimeout |
Obtém o tempo de espera padrão (em segundos) antes de encerrar a tentativa de executar um comando e gerar um erro. O padrão é 30 segundos. |
| 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 ao tentar estabelecer uma conexão antes de encerrar a tentativa e gerar um erro. |
| 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. |
| 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. |
| RetryLogicProvider |
Obtém ou define um valor que especifica o SqlRetryLogicBaseProvider objeto associado a esse comando. |
| ServerProcessId |
Obtém a ID do processo do servidor (SPID) da conexão ativa. |
| ServerVersion |
Obtém uma cadeia de caracteres que contém a versão da instância do SQL Server à qual o cliente está conectado. |
| SspiContextProvider |
Obtém ou define a SspiContextProvider instância para personalizar o contexto SSPI. Se não for definido, o padrão para a plataforma será usado. |
| State |
Indica o estado da operação de SqlConnection rede mais recente executada na conexão. |
| StatisticsEnabled |
Quando definido como , habilita a |
| WorkstationId |
Obtém uma cadeia de caracteres que identifica o cliente de banco de dados. |
Métodos
| Nome | Description |
|---|---|
| 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 SQL Server para o usuário indicado no 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 para fechar qualquer conexão aberta. |
| CreateCommand() |
Cria e retorna um SqlCommand objeto associado ao SqlConnection. |
| 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. |
| 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. |
| Open() |
Abre uma conexão de banco de dados com as configurações de propriedade especificadas pelo ConnectionString. |
| Open(SqlConnectionOverrides) |
Abre uma conexão de banco de dados com as configurações de propriedade especificadas pelo ConnectionString. |
| 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. |
| OpenAsync(SqlConnectionOverrides, 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. Essa função só deve ser chamada uma vez em um aplicativo. Isso faz uma cópia superficial do dicionário para que o aplicativo não possa alterar a lista de provedores personalizados depois que ele tiver sido definido. Os provedores internos de repositórios de chaves mestras de coluna que estão disponíveis para o Repositório de Certificados do Windows, a CNG Store e a CSP estão pré-registrados. |
| RegisterColumnEncryptionKeyStoreProvidersOnConnection(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>) |
Registra os provedores de repositório de chaves de criptografia na SqlConnection instância. Se essa função tiver sido chamada, todos os provedores registrados usando os métodos estáticos RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>) serão ignorados. Essa função pode ser chamada mais de uma vez. Isso faz uma cópia superficial do dicionário para que o aplicativo não possa alterar a lista de provedores personalizados depois que ele tiver sido definido. |
| ResetStatistics() |
Se a coleta de estatísticas estiver habilitada, todos os valores serão redefinidos para zero. |
| RetrieveInternalInfo() |
Retorna uma coleção de pares de valor de nome de propriedades internas no momento em que o método é chamado. |
| RetrieveStatistics() |
Retorna uma coleção de estatísticas de par de valor de nome no momento em que o método é chamado. |
Eventos
| Nome | Description |
|---|---|
| InfoMessage |
Ocorre quando SQL Server retorna um aviso ou mensagem informativa. |
Implantações explícitas de interface
| Nome | Description |
|---|---|
| ICloneable.Clone() |
Cria um novo objeto que é uma cópia da instância atual. |