SqlConnection Classe

Definição

Namespace:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Pacote:

Microsoft.Data.SqlClient v5.2.0

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

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 cadeia de conexão 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.

using System;
using System.Data;
using Microsoft.Data.SqlClient;

namespace SqlCommandCS
{
    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 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 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 .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 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.
AccessTokenCallback	Obtém ou define o retorno de chamada do token de acesso para a conexão.
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.
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 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.
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.
RetryLogicProvider	Obtém ou define um valor que especifica o objeto SqlRetryLogicBaseProvider associado a este comando.
ServerProcessId	Obtém a SPID (ID de processo do servidor) 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.
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

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.
ChangeDatabase(String)	Altera o banco de dados atual para um SqlConnection aberto.
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.
CreateCommand()	Cria e retorna um objeto SqlCommand associado ao SqlConnection.
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.
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 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.
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 de 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 de 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 valores de nome de propriedades internas no momento em que o método é chamado.
RetrieveStatistics()	Retorna uma coleção de estatísticas de pares nome-valor no momento em que o método é chamado.

Eventos

InfoMessage

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

Implantações explícitas de interface

ICloneable.Clone()

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