namespace Microsoft.Data.SqlClient e compatibilidade

O Microsoft.Data.SqlClient namespace contém o provedor de dados .NET suportado para bancos de dados compatíveis com SQL Server. Começou como um fork de System.Data.SqlClient e mantém o modelo de programação ADO.NET familiar, ao mesmo tempo em que disponibiliza novos recursos do SQL Server independentemente do runtime do .NET.

Use Microsoft.Data.SqlClient para novo desenvolvimento.

Instale e importe o namespace

Adicione o pacote NuGet:

dotnet add package Microsoft.Data.SqlClient

Importar o namespace:

using Microsoft.Data.SqlClient;

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

Relação com o ADO.NET

ADO.NET é o modelo de acesso a dados incorporado ao .NET. Ele define abstrações independentes do provedor 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 conexão lógica para um banco 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 Os fluxos resultam em linhas para frente a partir do servidor.
DbTransaction SqlTransaction Agrupa comandos em uma única transação que é confirmada ou revertida como uma unidade.
DbDataAdapter SqlDataAdapter Preenche e atualiza objetos desconectados DataSet e DataTable.
DbBatch SqlBatch Envia vários comandos em lote nas plataformas de destino compatíveis.

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

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

Programe contra abstrações ADO.NET quando uma biblioteca precisa suportar múltiplos provedores de banco de dados. Use os tipos SqlClient quando uma aplicação tem como alvo o SQL Server e precisa de recursos específicos do provedor, como autenticação Microsoft Entra, Always Encrypted, cópia em massa, parâmetros de tabela ou lógica de retentativa configurável. Mantenha o código específico do provedor atrás de um limite de acesso aos dados se o restante da aplicação deve permanecer independente do provedor.

Acesso conectado e desconectado

O acesso conectado mantém a conexão aberta enquanto um comando é executado e enquanto o aplicativo lê seus resultados. Uma solicitação típica segue esta sequência:

  1. Crie uma SqlConnection a partir de uma cadeia de conexão e abra-a.
  2. Crie um SqlCommand e adicione SqlParameter valores.
  3. Execute o comando.
  4. Processe um valor escalar, uma contagem de linhas afetadas ou um SqlDataReader.
  5. Libere o leitor, o comando e a conexão.

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

O acesso desconectado usa SqlDataAdapter para copiar dados em um DataSet ou DataTable na memória. A aplicação pode fechar a conexão enquanto lê ou altera os dados em memória, e então se reconectar para enviar atualizações. Use isso para associação de dados, relações e restrições na memória, edições offline que você reconcilia posteriormente ou um aplicativo existente criado em torno de DataAdapters. Para novos serviços orientados a requisições, comece com SqlCommand e SqlDataReader.

Vida útil do objeto e concorrência

Abra e descarte um SqlConnection para cada unidade de trabalho. O pool de conexões reutiliza a conexão física subjacente, então não mantenha uma conexão global aberta durante toda a vida útil de uma aplicação. Descarte conexõ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 uso simultâneo de múltiplas threads. Dê a cada operação concorrente sua própria conexão e confie no pooling de conexão. Múltiplos Conjuntos de Resultados Ativos (MARS) permite mais de um conjunto de resultados ativo em uma conexão, mas não torna os objetos SqlClient seguros para uso em threads.

Relação com System.Data.SqlClient

System.Data.SqlClienté o provedor mais antigo que vem com o .NET Framework e versões anteriores de .NET. Microsoft.Data.SqlClient Usa muitos dos mesmos nomes de tipos, mas possui pacotes, namespaces, padrão, recursos e políticas de suporte diferentes.

Não faça referência a ambos os provedores 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 geralmente começa adicionando o Microsoft.Data.SqlClient pacote e alterando as referências do namespace, mas você também deve revisar a criptografia da conexão, parâmetros, configuração, dependências transitivas e comportamento em tempo de execução. Siga Migrar de System.Data.SqlClient para Microsoft.Data.SqlClient antes de implantar.

Compatibilidade entre versões

A versão do pacote de driver é independente da versão .NET da aplicação e da versão do motor de banco de dados. Confira os três:

Component O que verificar
Microsoft.Data.SqlClient A linha de lançamento é suportada e contém os recursos que seu aplicativo utiliza.
.NET ou .NET Framework O aplicativo tem como alvo um runtime suportado por essa liberação do driver.
Banco de dados compatível com SQL Server A versão do driver suporta a versão do banco de dados e o servidor suporta qualquer recurso de protocolo solicitado, como o TDS 8.0.

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

Alterações específicas à versão

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

Os exemplos incluem:

  • A versão 4.0 mudou Encrypt para padrão para true.
  • A versão 5.0 introduziu SqlConnectionEncryptOption e Encrypt=Strict para TDS 8.0.
  • A versão 5.2 introduziu SqlBatch em destinos .NET modernos compatíveis.
  • A versão 7.0 moveu a autenticação do Microsoft Entra fornecida pelo driver para Microsoft.Data.SqlClient.Extensions.Azure.

Veja O que há de novo em Microsoft.Data.SqlClient para links para as notas de versão e um resumo da atualização.

Alguns recursos usam tipos fora do namespace principal ou pacotes opcionais.

Namespace 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 diagnósticos fortemente tipados.
Microsoft.Data.SqlClient.Extensions.Azure Autenticação do Microsoft Entra fornecida pelo driver 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 infira os requisitos do pacote apenas a partir de um namespace. Consulte o artigo sobre o recurso e as informações de dependência do pacote NuGet referentes à versão do driver que você usa.

Conteúdo relacionado

  • Última atualização em