Microsoft. Data.SqlClient namespace e compatibilidade

O Microsoft.Data.SqlClient namespace contém o fornecedor de dados .NET suportado para bases de dados compatíveis com SQL Server. Começou por ser uma derivação de System.Data.SqlClient e mantém o modelo de programação familiar do ADO.NET, ao mesmo tempo que disponibiliza novas funcionalidades do SQL Server independentemente do runtime do .NET.

Use Microsoft.Data.SqlClient para novos desenvolvimentos.

Instalar e importar o namespace

Adicione o pacote NuGet:

dotnet add package Microsoft.Data.SqlClient

Importar o namespace:

using Microsoft.Data.SqlClient;

A maioria das aplicações utiliza SqlConnection, SqlCommand, SqlParameter, SqlDataReader, e SqlTransaction. Para a superfície pública completa, consulte a referência da API Microsoft. Data.SqlClient.

Relação com o ADO.NET

ADO.NET é o modelo de acesso a dados incorporado no .NET. Define abstrações independentes do fornecedor no namespace System.Data.Common, e a Microsoft.Data.SqlClient fornece as implementações concretas.

Abstração ADO.NET Tipo SqlClient Purpose
DbConnection SqlConnection Abre uma ligação lógica a uma base de dados.
DbCommand SqlCommand Executa texto Transact-SQL (T-SQL) ou um procedimento armazenado.
DbParameter SqlParameter Envia um valor digitado separadamente do texto do comando.
DbDataReader SqlDataReader Transmite em fluxo as linhas de resultados a partir do servidor.
DbTransaction SqlTransaction Agrupa comandos numa única transação que faz commit ou reverte como unidade.
DbDataAdapter SqlDataAdapter Preenche e atualiza objetos DataSet e DataTable desconectados.
DbBatch SqlBatch Envia vários comandos num único lote nas plataformas de destino suportadas.

Microsoft.Data.SqlClient também fornece APIs específicas do SQL Server, tais como:

  • SqlBulkCopy
  • SqlConnectionStringBuilder
  • SqlConfigurableRetryFactory
  • SqlDependency
  • Autenticação, encriptação e suporte de tipos de dados específicos do SQL Server

Programe com base nas abstrações do ADO.NET quando uma biblioteca tiver de suportar múltiplos fornecedores de bases de dados. Utilize os tipos SqlClient quando uma aplicação tem como alvo o SQL Server e necessita de funcionalidades específicas do fornecedor de dados, como autenticação Microsoft Entra, Always Encrypted, cópia em massa, parâmetros com valor de tabela ou lógica de retentativa configurável. Mantenha o código específico do fornecedor atrás de um limite de acesso aos dados se o resto da aplicação tiver de permanecer independente do fornecedor.

Acesso com e sem ligação

Acesso conectado mantém uma ligação aberta enquanto um comando é executado e enquanto a aplicação lê os seus resultados. Um pedido típico segue esta sequência:

  1. Cria uma SqlConnection a partir de uma cadeia de ligação e abre-a.
  2. Criar um SqlCommand e adicionar valores a SqlParameter.
  3. Execute o comando.
  4. Processe um valor escalar, uma contagem de linhas afetadas ou um SqlDataReader.
  5. Elimina o leitor, o comando e a ligação.

Use o acesso conectado para a maioria das APIs web, serviços, trabalhadores e aplicações de linha de comandos. SqlDataReader transmite linhas em fluxo e normalmente consome menos memória do que carregar todo o resultado para um DataSet.

O acesso desconectado utiliza SqlDataAdapter para copiar dados para uma DataSet ou DataTable em memória. A aplicação pode fechar a ligação enquanto lê ou altera os dados em memória, e depois reconectar-se para submeter atualizações. Usa-o para ligação de dados, relações e restrições em memória, edições offline que reconcilia mais tarde, ou uma aplicação existente construída em torno de DataAdapters. Para novos serviços orientados a pedidos, comece com SqlCommand e SqlDataReader.

Vida útil do objeto e concorrência

Abra e descarte um SqlConnection para cada unidade de trabalho. O pooling de ligações reutiliza a ligação física subjacente, por isso não mantenhas uma ligação global aberta durante toda a vida útil de uma aplicação. Elimine ligações, comandos, leitores, transações e objetos de cópia em massa rapidamente. No código assíncrono, use await using para tipos que implementam IAsyncDisposable no framework de destino, como SqlConnection e SqlDataReader em .NET, e using comum para tipos que implementam apenas IDisposable, como SqlBulkCopy.

SqlConnection, SqlCommand, SqlDataReader, e SqlTransaction não suportam o uso simultâneo de múltiplas threads. Atribua a cada operação concorrente a sua própria ligação e recorra ao agrupamento de ligações. Múltiplos Conjuntos de Resultados Ativos (MARS) permitem mais do que um conjunto ativo de resultados numa ligação, mas não torna os objetos SqlClient seguros para threads.

Relação com System.Data.SqlClient

System.Data.SqlClienté o fornecedor mais antigo que vem com o .NET Framework e versões anteriores de .NET. Microsoft.Data.SqlClient Utiliza muitos dos mesmos nomes de tipos, mas tem pacotes, namespaces, predefinições, funcionalidades e políticas de suporte diferentes.

Não faça referência a ambos os fornecedores no novo código da aplicação. Tipos com o mesmo nome dos dois pacotes não são intercambiáveis. Um System.Data.SqlClient.SqlConnection, por exemplo, não pode ser passado onde um Microsoft.Data.SqlClient.SqlConnection é exigido.

A migração normalmente começa por adicionar o Microsoft.Data.SqlClient pacote e alterar as referências do namespace, mas também deve rever a encriptação da ligação, parâmetros, configuração, dependências transitivas e comportamento em tempo de execução. Siga a migração de System.Data.SqlClient para Microsoft.Data.SqlClient antes de implementar.

Compatibilidade de versões

A versão do pacote de drivers é independente da versão .NET da aplicação e da versão do motor da base de dados. Verifica os três:

Component O que verificar
Microsoft.Data.SqlClient A linha de lançamento é suportada e contém as funcionalidades que a sua aplicação utiliza.
.NET ou .NET Framework A aplicação visa um runtime suportado por essa versão do driver.
Base de dados compatível com SQL Server A versão do driver suporta a versão da base de dados e o servidor suporta qualquer funcionalidade de protocolo solicitada, como o TDS 8.0.

Para matrizes atuais, veja ciclo de vida do suporte ao driver SqlClient.

Alterações específicas da versão

As versões de drivers podem adicionar APIs, mover dependências opcionais e alterar valores de segurança por definição. Revise as alterações antes de cada atualização menor ou maior.

Os exemplos incluem:

  • A versão 4.0 alterou Encrypt para assumir por predefinição true.
  • A versão 5.0 introduziu SqlConnectionEncryptOption e Encrypt=Strict para o TDS 8.0.
  • A versão 5.2 introduziu SqlBatch para versões modernas do .NET suportadas.
  • A versão 7.0 moveu a autenticação Microsoft Entra fornecida pelo driver para Microsoft.Data.SqlClient.Extensions.Azure.

Consulte Novidades no Microsoft.Data.SqlClient para obter ligações para as notas de versão e um resumo da atualização.

Algumas funcionalidades usam tipos fora do namespace principal ou pacotes opcionais.

Espaço de nomes ou pacote Purpose
Microsoft.Data.SqlClient.Server Implementações SqlClient de SqlDataRecord e SqlMetaData.
Microsoft.Data.SqlTypes Tipos específicos de SqlClient, como SqlFileStream, SqlJson, e SqlVector<T>.
Microsoft.Data.SqlClient.Diagnostics Payloads de eventos de diagnóstico fortemente tipados.
Microsoft.Data.SqlClient.Extensions.Azure Autenticação do Microsoft Entra fornecida por controladores para a versão 7.0 e versões posteriores.
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider Integração com Azure Key Vault para Always Encrypted.

Não infiras os requisitos do pacote apenas a partir de um namespace. Consulte o artigo principal e as informações sobre dependências do pacote NuGet para a versão do driver que utiliza.

Conteúdo relacionado

  • Última atualização a