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

Microsoft. O Data.SqlClient é o fornecedor suportado para novas funcionalidades do SQL Server em aplicações .NET. 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 fornecedor, não apenas como uma substituição do namespace.

Planear a migração

Antes de mudar o código:

Regista as versões dos serviços .NET, System.Data.SqlClientSQL Server e Microsoft SQL que a aplicação suporta.
Inventariar modos de autenticação, palavras-chave da cadeia de ligação, certificados personalizados, provedores do Always Encrypted, configuração de DbProviderFactories, tipos definidos pelo utilizador do SQL Server e utilização de System.Data.SqlTypes.
Execute os testes atuais da aplicação e registe uma referência para o comportamento de ligação, consulta, transação, nova tentativa e desempenho.
Pesquise referências de pacotes diretas e transitivas:
```
dotnet list package --include-transitive
```

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

Substituir 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 Microsoft.Data.SqlClient 7.0 ou posterior utilizar um modo de autenticação Microsoft Entra fornecido pelo controlador, adicione também:

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 implementar Microsoft. Data.SqlClient.

Atualizar namespaces

Substituir o espaço de nomes do fornecedor principal:

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

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

Não substituas os espaços de nomes gerais System.Data ou System.Data.Common. Microsoft.Data.SqlClientcontinua a usar tipos ADO.NET como CommandType, DbType, IsolationLevel, DataTable, DbConnection, , e DbCommand desses namespaces.

Alguns tipos específicos do SQL Server mudam-se para outros Microsoft.Data namespaces:

Tipo	Espaço de nomes 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`

Em Microsoft.Data.SqlClient 5.0 e versões posteriores, os outros tipos CLR do SQL Server permanecem em Microsoft.SqlServer.Server. Atualize cada tipo com base nos erros do compilador e na referência da API Microsoft.Data.SqlClient, em vez de substituir o espaço de nomes completo.

Atualização da configuração do framework .NET

Uma aplicação que resolva fornecedores através de DbProviderFactories poderá necessitar de um registo de fornecedor 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 fornecedor:

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

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

Revisão da encriptação e validação de certificados

Microsoft. Data.SqlClient usa valores predefinidos mais seguros do que System.Data.SqlClient.

Comportamento	System.Data.SqlClient	Microsoft.Data.SqlClient
Encriptação padrão	`Encrypt=false`	`Encrypt=true` A partir da versão 4.0
Validação de certificado do servidor	Valida o certificado apenas quando a encriptação do cliente está ativada	A partir da versão 2.0, valida o certificado de acordo com `TrustServerCertificate` quando o servidor força a encriptação, mesmo que `Encrypt=false`
Encriptação rigorosa	Não suportado	`Encrypt=Strict` a partir da versão 5.0 para servidores compatíveis com TDS 8.0
Tipo `SqlConnectionStringBuilder.Encrypt`	`bool`	`SqlConnectionEncryptOption` a partir da versão 5.0

Não defina Encrypt=false ou TrustServerCertificate=true como uma solução genérica para 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 alteração para SqlConnectionEncryptOption é compatível ao nível do código-fonte em atribuições comuns por meio de conversões implícitas, mas constitui uma incompatibilidade binária. Recompile todas as assemblies que acedem a SqlConnectionStringBuilder.Encrypt.

Para mais detalhes, consulte Encriptação e validação de certificados.

Revisar cadeias de ligação

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

Não construas uma cadeia de ligação com Microsoft.Data.SqlClient.SqlConnectionStringBuilder e depois a passes para System.Data.SqlClient. Durante uma migração faseada, mantenha cada cadeia de ligação builder emparelhado com o seu fornecedor.

Verifique as palavras-chave de autenticação, encriptação, novas tentativas, failover e certificado em relação à sintaxe da cadeia de ligação.

Rever o comportamento do parâmetro

Teste explicitamente os parâmetros de data e hora:

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

Especifique SqlDbType, comprimento, precisão e escala para parâmetros em que a inferência de tipo no SQL Server possa alterar os planos de consulta ou o comportamento de conversão. Não uses AddWithValue como atalho de migração quando o tipo de base de dados for conhecido.

Verifique referências de fornecedores transitivos

A remoção direta de um pacote não garante que System.Data.SqlClient tenha sido removido. Corrida:

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 os tipos específicos do fornecedor dentro da fronteira de dependência quando ambos tiverem de ser mantidos.
Use nomes explícitos apenas como ajuda temporária. Não passe uma ligação, transação, parâmetro ou leitor de um fornecedor para outro.

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

Rever o comportamento da globalização

As versões do .NET Framework e .NET anteriores ao .NET 5 utilizam a globalização do National Language Support (NLS) no Windows. As versões atuais do .NET utilizam por defeito Componentes Internacionais para Unicode (ICU) em Windows, Linux e macOS.

Esta diferença de tempo de execução pode alterar algumas SqlString comparações. O SQL Server utiliza o comportamento de comparação do NLS. Se as comparações no lado SqlString do cliente tiverem de coincidir com o comportamento do servidor, teste os valores afetados e consulte Globalização e ICU. Uma aplicação pode usar NLS em vez de UCI quando necessário.

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

Validar a aplicação migrada

Compile e teste em cada plataforma de destino e sistema operativo suportados.

Validar:

Restauração de pacotes e resultado publicado.
Autenticação SQL, autenticação integrada no Windows e autenticação Microsoft Entra utilizada pela aplicação.
Negociação TLS, validação de certificados e análise da cadeia de ligação.
Agrupamento de ligações e atualização do token de acesso.
Tipos de parâmetros, valores nulos, precisão, escala, data e comportamento temporal.
Transações, cancelamentos, tempos limite, novas tentativas e ativação pós-falha.
Always Encrypted, tipos CLR do SQL Server, cópia em massa, notificações de consulta e outras funcionalidades específicas do fornecedor de dados utilizadas pela aplicação.
Registo, contadores, rastreio e gestão de exceções.

Execute consultas representativas em todas as versões suportadas do motor de base de dados. Uma compilação bem-sucedida não valida a segurança da ligaçã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