Migre do System.Data.SqlClient para a Microsoft. Data.SqlClient

Microsoft. Data.SqlClient é o provedor suportado para novos recursos do SQL Server em aplicações .NET. Ele preserva o modelo de programação ADO.NET usado por System.Data.SqlClient, mas os pacotes, namespaces, padrões e alguns tipos públicos diferem.

Trate a migração como uma atualização do provedor, não apenas como uma substituição do namespace.

Planejar a migração

Antes de mudar o código:

Registre as versões dos serviços .NET, System.Data.SqlClientSQL Server e Microsoft SQL que o aplicativo suporta.
Modos de autenticação de inventário, palavras-chave de cadeia de conexão, certificados personalizados, fornecedores Always Crypted, DbProviderFactories configuração, tipos definidos pelo usuário do SQL Server e System.Data.SqlTypes uso.
Execute os testes atuais da aplicação e salve uma linha de base para conexão, consulta, transação, retentativa e comportamento de desempenho.
Busque referências diretas e transitivas de pacotes:
```
dotnet list package --include-transitive
```

Migre uma aplicação ou biblioteca de acesso compartilhado a dados por vez. Não passe objetos específicos do provedor entre código que ainda usa System.Data.SqlClient e código que usa Microsoft.Data.SqlClient.

Troque o pacote

Remova uma referência explícita System.Data.SqlClient a um pacote, se presente:

dotnet remove package System.Data.SqlClient

Adicionar Microsoft. Data.SqlClient:

dotnet add package Microsoft.Data.SqlClient

Se a Microsoft. Data.SqlClient 7.0 ou posterior usar um modo de autenticação Microsoft Entra fornecido por driver, também adicione:

dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version <same-version-as-Microsoft.Data.SqlClient>

Para seleção de versões e pacotes, veja Instalar, atualizar e implantar Microsoft. Data.SqlClient.

Atualizar espaços de nomes

Substitua o namespace do provedor principal:

-using System.Data.SqlClient;
+using Microsoft.Data.SqlClient;

Atualize nomes totalmente qualificados, aliases, código gerado, registros de injeção de dependências, strings de reflexão, configuração e testes duplos que se referem a System.Data.SqlClient.

Não substitua o espaço geral System.Data ou System.Data.Common namespace. Microsoft.Data.SqlClientcontinua usando tipos ADO.NET como CommandType, DbType, IsolationLevel, DataTable, DbConnection, , e DbCommand desses namespaces.

Alguns tipos específicos do SQL Server migram para outros Microsoft.Data namespaces:

Tipo	Namespace anterior	Namespace Microsoft.Data.SqlClient
`SqlDataRecord`, `SqlMetaData`	`Microsoft.SqlServer.Server`	`Microsoft.Data.SqlClient.Server`
`SqlFileStream`	`System.Data.SqlTypes`	`Microsoft.Data.SqlTypes`
`SqlNotificationRequest`	`System.Data.Sql`	`Microsoft.Data.Sql`
`OperationAbortedException`	`System.Data`	`Microsoft.Data`

No Microsoft.Data.SqlClient 5.0 e posteriores, outros tipos de execução de linguagem comum (CLR) do SQL Server permanecem em Microsoft.SqlServer.Server. Atualize cada tipo a partir de erros do compilador e da referência à API do Microsoft. Data.SqlClient, em vez de substituir todo o namespace.

Atualizar configuração do Framework .NET

Uma aplicação que resolva prestadores por meio DbProviderFactories pode exigir um registro de prestador em App.config ou Web.config:

<configuration>
  <system.data>
    <DbProviderFactories>
      <add name="SqlClient Data Provider"
           invariant="Microsoft.Data.SqlClient"
           description=".NET data provider for SQL Server"
           type="Microsoft.Data.SqlClient.SqlClientFactory, Microsoft.Data.SqlClient" />
    </DbProviderFactories>
  </system.data>
</configuration>

Código de atualização que solicita o nome invariante do provedor:

DbProviderFactory factory =
    DbProviderFactories.GetFactory("Microsoft.Data.SqlClient");

Não adicione essa configuração quando a aplicação cria SqlConnection diretamente e não usa DbProviderFactories.

Revise criptografia e validação de certificados

Microsoft. Data.SqlClient usa padrões mais seguros do que System.Data.SqlClient.

Behavior	System.Data.SqlClient	Microsoft.Data.SqlClient
Criptografia padrão	`Encrypt=false`	`Encrypt=true` A partir da versão 4.0
Validação do certificado do servidor	Valida o certificado apenas quando a criptografia do cliente está habilitada	A partir da versão 2.0, o certificado é validado de acordo com `TrustServerCertificate` quando o servidor força a criptografia, mesmo que `Encrypt=false`
Criptografia rigorosa	Sem suporte	`Encrypt=Strict` começando pela versão 5.0 para servidores compatíveis com TDS 8.0
Tipo de `SqlConnectionStringBuilder.Encrypt`	`bool`	`SqlConnectionEncryptOption` Começando pela versão 5.0

Não defina Encrypt=false ou TrustServerCertificate=true seja uma solução geral de migração. Configure um certificado em que o cliente confie e use um nome de servidor que corresponda ao certificado. TrustServerCertificate=true Use apenas em ambientes de desenvolvimento controlados onde a validação não é possível.

A mudança para SqlConnectionEncryptOption é compatível com o código-fonte em atribuições comuns por meio de conversões implícitas, mas é uma mudança que quebra binária. Recompile todo assembly que acesse SqlConnectionStringBuilder.Encrypt.

Para obter detalhes, confira Criptografia e validação de certificado.

Revise as strings de conexão

Microsoft. Data.SqlClient adiciona palavras-chave e apelidos que System.Data.SqlClient não reconhece. Por exemplo, aceita aliases com espaços como Application Intent e Multi Subnet Failover.

Não construa uma cadeia de conexão com Microsoft.Data.SqlClient.SqlConnectionStringBuilder e depois passe para System.Data.SqlClient. Durante uma migração em etapas, mantenha cada construtor de cadeia de conexão emparelhado com seu provedor.

Revise autenticação, criptografia, retentativa, failover e palavras-chave de certificado com a sintaxe da string de conexão.

Comportamento dos parâmetros de revisão

Parâmetros de data e hora do teste explicitamente:

Parâmetro	Comportamento do System.Data.SqlClient	Microsoft. Comportamento do Data.SqlClient
`DbType.Time` com um `DateTime` valor	Aceita o valor	Use um `TimeSpan` valor
`DbType.Date` com um `DateTime` valor	Pode enviar componentes de data e hora	Trunca os componentes de tempo

Especifique SqlDbType, comprimento, precisão e escala para parâmetros onde a inferência do tipo SQL Server pode alterar planos de consulta ou comportamento de conversão. Não use AddWithValue como atalho de migração quando o tipo de banco de dados for conhecido.

Verifique referências de provedores transitivos

Uma remoção direta de pacote não garante que isso System.Data.SqlClient desapareceu. Executar:

dotnet list package --include-transitive

Se ambos os prestadores permanecerem:

Identifique o pacote que traz System.Data.SqlClient.
Atualize ou substitua essa dependência sempre que possível.
Mantenha tipos específicos do provedor dentro do limite de dependência quando ambos precisam permanecer.
Use aliases explícitos de namespace apenas como uma ajuda temporária. Não passe uma conexão, transação, parâmetro ou leitor de um provedor para outro.

Preste atenção especial às bibliotecas CLR do SQL Server e frameworks antigos de acesso a dados que expõem System.Data.SqlClient tipos em suas APIs públicas.

Revise o comportamento da globalização

As versões do Framework .NET e .NET anteriores ao .NET 5 utilizam globalização por Suporte Nacional de Linguagem (NLS) no Windows. As versões atuais do .NET usam por padrão Componentes Internacionais para Unicode (ICU) em Windows, Linux e macOS.

Essa diferença de tempo de execução pode alterar algumas SqlString comparações. O SQL Server utiliza comportamento de comparação NLS. Se as comparações do lado SqlString do cliente precisarem corresponder ao comportamento do servidor, teste os valores afetados e revise a Globalização e a UTI. Uma aplicação pode usar NLS em vez de UTI quando necessário.

O modo invariante à globalização não é suportado pela Microsoft. Data.SqlClient.

Valide a aplicação migrada

Construa e teste em todos os frameworks e sistemas operacionais de alvo suportados.

Validar:

Restauração do pacote e saída publicada.
Autenticação SQL, autenticação integrada ao Windows e autenticação Microsoft Entra usadas pelo aplicativo.
Negociação TLS, validação de certificados e análise de cadeia de conexão.
Pooling de conexão e atualização do token de acesso.
Tipos de parâmetros, valores nulos, precisão, escala, data e comportamento de tempo.
Transações, cancelamentos, tempos de espera, tentativas e failover.
Sempre criptografado, tipos CLR do SQL Server, cópia em massa, notificações de consulta e outros recursos específicos do provedor usados pela aplicação.
Registro, contadores, rastreamento e tratamento de exceções.

Execute consultas representativas em todas as versões suportadas do motor de banco de dados. Uma compilação bem-sucedida não valida a segurança da conexão, dependências em tempo de execução ou conversões de dados.

Comentários

Esta página foi útil?

Last updated on 2026-09-16