SqlConnection Classe

Definição

Espaço de Nomes:: System.Data.SqlClient

Assemblagem:: System.Data.dll

Importante

Algumas informações dizem respeito a um produto pré-lançado que pode ser substancialmente modificado antes de ser lançado. A Microsoft não faz garantias, de forma expressa ou implícita, em relação à informação aqui apresentada.

Representa uma ligação a uma base de dados do SQL Server. Esta 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 seguinte cria um SqlCommand e um SqlConnection. O SqlConnection é aberto e definido como o Connection para o SqlCommand. O exemplo chama ExecuteNonQueryentão . Para isso, o ExecuteNonQuery recebe um SqlConnection e uma string de consulta que é uma instrução Transact-SQL INSERT. A ligação é encerrada 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

Observações

Um objeto SqlConnection representa uma sessão única para uma fonte de dados SQL Server. Num sistema de base de dados cliente/servidor, é equivalente a uma ligação de rede ao servidor. SqlConnection é usado em conjunto com SqlDataAdapter e SqlCommand para aumentar o desempenho ao ligar a um base de dados do Microsoft SQL Server. Para todos os produtos de SQL Server de terceiros e outras fontes de dados suportadas por OLE DB, use OleDbConnection.

Quando cria uma instância de SqlConnection, todas as propriedades são definidas para os seus valores iniciais. Para obter uma lista desses valores, consulte o SqlConnection construtor.

Consulte ConnectionString para uma lista das palavras-chave de um cadeia de ligação.

Se sair SqlConnection do âmbito, não será fechado. Portanto, deve fechar explicitamente a ligação chamando Close ou Dispose. Close e Dispose são funcionalmente equivalentes. Se o valor Pooling do pool de ligação for definido para true ou yes, a ligação subjacente é devolvida ao pool de ligações. Por outro lado, se Pooling for definido para false ou no, a ligação subjacente ao servidor é realmente fechada.

Note

Os eventos de login e logout não serão gerados no servidor quando uma conexão for buscada ou retornada ao pool de conexões, porque a conexão não será realmente fechada quando for retornada ao pool de conexões. Para obter mais informações, consulte Pool de conexões do SQL Server (ADO.NET).

Para garantir que as ligações estão sempre fechadas, abra a ligação dentro de um using bloco, como mostrado no seguinte fragmento de código. Ao fazê-lo, a ligação é automaticamente encerrada quando o código sai 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 implementar aplicações de alto desempenho, deve usar pooling de ligações. Quando utiliza o .NET Framework Data Provider for SQL Server, não precisa de ativar o pooling de conexões porque o fornecedor gere isto automaticamente, embora possa modificar algumas definições. Para obter mais informações, consulte Pool de conexões do SQL Server (ADO.NET).

Se a SqlException for gerado pelo método que executa a SqlCommand, permanece SqlConnection aberto quando o nível de gravidade é 19 ou inferior. Quando o nível de gravidade é 20 ou superior, o servidor normalmente fecha o SqlConnection. No entanto, o utilizador pode reabrir a ligação e continuar.

Uma aplicação 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 exigências de segurança declarativas ou imperativas. SqlConnection faz exigências de segurança usando o SqlClientPermission objeto. Os utilizadores podem verificar se o seu código tem permissões suficientes usando o SqlClientPermissionAttribute objeto. Utilizadores e administradores também podem usar o Caspol.exe (Ferramenta de Política de Segurança de Acesso ao Código) para modificar políticas de segurança a nível da máquina, do utilizador e da empresa. Para obter mais informações, consulte Segurança no .NET. Para um exemplo que demonstra como usar exigências de segurança, veja Code Access Security e ADO.NET.

Para mais informações sobre como lidar com mensagens de aviso e informativas do servidor, consulte Eventos de Ligação. Para mais informações sobre erros do motor SQL Server e mensagens de erro, consulte Database Engine Eventos e Erros.

Caution

Podes forçar TCP em vez de memória partilhada. Podes fazer isso prefixando tcp: ao nome do servidor na cadeia de ligação ou podes usar localhost.

Construtores

Name	Description
SqlConnection()	Inicializa uma nova instância da SqlConnection classe.
SqlConnection(String, SqlCredential)	Inicializa uma nova instância da classe SqlConnection dada uma cadeia de ligação, que não utiliza `Integrated Security = true` e um objeto SqlCredential que contém o ID de utilizador e a palavra-passe.
SqlConnection(String)	Inicializa uma nova instância da classe SqlConnection quando recebe uma cadeia que contém a cadeia de ligação.

Propriedades

Name	Description
AccessToken	Obtém ou define o token de acesso para a ligação.
CanRaiseEvents	Obtém um valor que indica se o componente pode gerar um evento. (Herdado de Component)
ClientConnectionId	O ID da ligação da tentativa de ligação mais recente, independentemente de a tentativa ter sido bem-sucedida ou falhada.
ColumnEncryptionKeyCacheTtl	Obtém ou define o tempo de vida para entradas de chave de encriptação de colunas na cache de chave de encriptação de colunas para a funcionalidade Always Crypted . O valor padrão é 2 horas. 0 significa que não há cache nenhum.
ColumnEncryptionQueryMetadataCacheEnabled	Recebe ou define um valor que indica se o cache de metadados de consulta está ativado (verdadeiro) ou não (falso) para consultas parametrizadas que correm contra bases de dados ativadas pelo Always Crypted . O valor predefinido é true.
ColumnEncryptionTrustedMasterKeyPaths	Permite definir uma lista de caminhos de chaves de confiança para um servidor de base de dados. Se, durante o processamento de uma consulta de aplicação, o driver receber um caminho de chave que não está na lista, a consulta falhará. Esta propriedade oferece proteção adicional contra ataques de segurança que envolvam um SQL Server comprometido a fornecer caminhos de chave falsos, o que pode levar à fuga de credenciais de armazenamento de chaves.
ConnectionString	Obtém ou define a string usada para abrir uma base de dados do SQL Server.
ConnectionTimeout	Obtém o tempo de espera (em segundos) enquanto tentam estabelecer uma ligação antes de terminar 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 esta ligação.
Database	Obtém o nome da base de dados atual ou da base de dados a ser usada após a abertura de uma ligação.
DataSource	Obtém o nome da instância do SQL Server à qual se deve ligar.
DbProviderFactory	Recebe o DbProviderFactory por isto DbConnection. (Herdado de DbConnection)
DesignMode	Obtém um valor que indica se o Component está atualmente em modo de design. (Herdado de Component)
Events	Obtém a lista de gestores de eventos que estão ligados a isto Component. (Herdado de Component)
FireInfoMessageEventOnUserErrors	Obtém ou definem a FireInfoMessageEventOnUserErrors propriedade.
PacketSize	Obtém o tamanho (em bytes) dos pacotes de rede usados para comunicar com uma instância do SQL Server.
ServerVersion	Obtém uma string que contém a versão da instância do SQL Server à qual o cliente está ligado.
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 ligação.
StatisticsEnabled	Quando definido para `true`, permite a recolha de estatísticas para a ligação atual.
WorkstationId	Recebe uma cadeia que identifica o cliente da base de dados.

Métodos

Name	Description
BeginDbTransaction(IsolationLevel)	Quando é sobreposto numa classe derivada, inicia uma transação de base de dados. (Herdado de DbConnection)
BeginTransaction()	Inicia uma transação na base de dados.
BeginTransaction(IsolationLevel, String)	Inicia uma transação de base de dados com o nível de isolamento e o nome da transação especificados.
BeginTransaction(IsolationLevel)	Inicia uma transação de base de dados com o nível de isolamento especificado.
BeginTransaction(String)	Inicia uma transação na base de dados com o nome da transação especificado.
ChangeDatabase(String)	Altera a base de dados atual para um .SqlConnection
ChangePassword(String, SqlCredential, SecureString)	Altera a palavra-passe SQL Server do utilizador indicada no objeto SqlCredential.
ChangePassword(String, String)	Altera a palavra-passe do SQL Server para o utilizador indicada na cadeia de ligação para a nova palavra-passe especificada.
ClearAllPools()	Esvazia o pool de ligações.
ClearPool(SqlConnection)	Esvazia o pool de ligação associado à ligação especificada.
Close()	Fecha a ligação à base de dados. Este é o método preferido para fechar qualquer ligação aberta.
CreateCommand()	Cria e devolve um SqlCommand objeto associado ao SqlConnection.
CreateDbCommand()	Quando sobreposto numa classe derivada, cria e devolve um DbCommand objeto associado à ligação atual. (Herdado de DbConnection)
CreateObjRef(Type)	Cria um objeto que contém toda a informação relevante necessária para gerar um proxy usado para comunicar com um objeto remoto. (Herdado de MarshalByRefObject)
Dispose()	Liberta todos os recursos utilizados pelo Component. (Herdado de Component)
Dispose(Boolean)	Liberta os recursos não geridos usados pelo Component e opcionalmente liberta os recursos geridos. (Herdado de Component)
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.
Equals(Object)	Determina se o objeto especificado é igual ao objeto atual. (Herdado de Object)
GetHashCode()	Serve como função de hash predefinida. (Herdado de Object)
GetLifetimeService()	Recupera o objeto de serviço de tempo de vida atual que controla a política de vida útil neste caso. (Herdado de MarshalByRefObject)
GetSchema()	Devolve informação de esquema para a fonte de dados deste SqlConnection. Para mais informações sobre scheme, consulte SQL Server Schema Collections.
GetSchema(String, String[])	Devolve a informação do esquema para a fonte de dados desta SqlConnection usando a cadeia especificada para o nome do esquema e o array de cadeias especificado para os valores de restrição.
GetSchema(String)	Devolve a informação do esquema para a fonte de dados desta SqlConnection usando a cadeia especificada para o nome do esquema.
GetService(Type)	Devolve 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()	Obtém-se um objeto de serviço vitalício para controlar a apólice vitalícia neste caso. (Herdado de MarshalByRefObject)
MemberwiseClone()	Cria uma cópia superficial do atual Object. (Herdado de Object)
MemberwiseClone(Boolean)	Cria uma cópia superficial do objeto atual MarshalByRefObject . (Herdado de MarshalByRefObject)
OnStateChange(StateChangeEventArgs)	Eleva o StateChange evento. (Herdado de DbConnection)
Open()	Abre uma ligação à base de dados com as definições de propriedade especificadas pelo ConnectionString.
OpenAsync()	Uma versão assíncrona de Open(), que abre uma ligação à base de dados com as definições especificadas pelo ConnectionString. Este método invoca o método OpenAsync(CancellationToken) virtual com CancellationToken.None. (Herdado de DbConnection)
OpenAsync(CancellationToken)	Uma versão assíncrona de Open(), que abre uma ligação à base de dados com as definições de propriedades especificadas pelo ConnectionString. O token de cancelamento pode ser usado para pedir que a operação seja abandonada antes do tempo de extinção da ligação. As exceções serão propagadas através da Tarefa devolvida. Se o tempo de expiração da ligação passar sem que a ligação seja bem-sucedida, a Tarefa devolvida será marcada como falhada com uma Exceção. A implementação devolve uma Tarefa sem bloquear o thread de chamada tanto para ligações em pool como para não pooled.
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	Regista os fornecedores de armazenamento de chaves de encriptação da coluna.
ResetStatistics()	Se a recolha de estatísticas estiver ativada, todos os valores são reiniciados para zero.
RetrieveStatistics()	Devolve uma coleção de pares de nomes-valores de estatísticas no momento em que o método é chamado.
ToString()	Devolve a String contendo o nome do Component, se existir. Este método não deve ser ultrapassado. (Herdado de Component)

evento

Name	Description
Disposed	Ocorre quando o componente é eliminado por uma chamada ao Dispose() método. (Herdado de Component)
InfoMessage	Ocorre quando o SQL Server devolve um aviso ou mensagem informativa.
StateChange	Ocorre quando o estado da ligação muda.
StateChange	Ocorre quando o estado da ligação muda. (Herdado de DbConnection)

Implementações de Interface Explícita

Name	Description
ICloneable.Clone()	Cria um novo objeto que é uma cópia da instância atual.
IDbConnection.BeginTransaction()	Inicia uma transação de base de dados.
IDbConnection.BeginTransaction()	Inicia uma transação de base de dados. (Herdado de DbConnection)
IDbConnection.BeginTransaction(IsolationLevel)	Inicia uma transação de base de dados com o valor especificado IsolationLevel .
IDbConnection.BeginTransaction(IsolationLevel)	Inicia uma transação de base de dados com o nível de isolamento especificado. (Herdado de DbConnection)
IDbConnection.CreateCommand()	Cria e devolve um objeto Command associado à ligação.
IDbConnection.CreateCommand()	Cria e devolve um DbCommand objeto associado à ligação atual. (Herdado de DbConnection)

Aplica-se a

Ver também

Comentários

Esta página foi útil?