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

Microsoft. Data.SqlClient implementa tipos independentes do fornecedor a partir de System.Data.Common, incluindo DbConnection, DbCommand, DbDataReader, e DbTransaction. Também fornece APIs específicas para o SQL Server, tais como:

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

Para orientações sobre a escolha de APIs independentes do fornecedor ou específicas de SqlClient, consulte a arquitetura ADO.NET com a Microsoft. Data.SqlClient.

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

  • Last updated on