Migra da System.Data.SqlClient a Microsoft. Data.SqlClient

Microsoft. Data.SqlClient è il fornitore supportato per le nuove funzionalità di SQL Server nelle applicazioni .NET. Preserva il modello di programmazione ADO.NET usato da System.Data.SqlClient, ma i pacchetti, i namespace, i valori predefiniti e alcuni tipi pubblici differiscono.

Tratta la migrazione come un aggiornamento del provider, non solo come una semplice sostituzione dello spazio dei nomi.

Pianificare la migrazione

Prima di cambiare codice:

  1. Registra le versioni dei servizi .NET, System.Data.SqlClientSQL Server e Microsoft SQL supportati dall'applicazione.

  2. Modalità di autenticazione dell'inventario, parole chiave della stringa di connessione, certificati personalizzati, provider Always Encrypted, configurazione di DbProviderFactories, tipi definiti dall'utente in SQL Server e utilizzo di System.Data.SqlTypes.

  3. Esegui i test attuali dell'applicazione e salva una base per il comportamento di connessione, interrogazione, transazione, ritentativi e prestazioni.

  4. Cerca riferimenti di pacchetti diretti e transitivi:

    dotnet list package --include-transitive

Migra una libreria di accesso dati condivisa o applicazione alla volta. Non passare oggetti specifici del provider tra codice che ancora usa System.Data.SqlClient e codice che usa Microsoft.Data.SqlClient.

Sostituisci il pacchetto

Rimuovere un riferimento esplicito System.Data.SqlClient al packaging, se presente:

dotnet remove package System.Data.SqlClient

Aggiungi Microsoft. Data.SqlClient:

dotnet add package Microsoft.Data.SqlClient

Se Microsoft. Data.SqlClient 7.0 o successiva utilizza una modalità di autenticazione Microsoft Entra fornita dal driver, aggiungi anche:

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

Per la selezione di versione e pacchetto, vedi Installa, aggiorna e distribuisci Microsoft. Data.SqlClient.

Aggiornare namespace

Sostituire il namespace principale del fornitore:

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

Aggiorna i nomi completi, gli alias, il codice generato, le registrazioni per l'inserimento delle dipendenze, le stringhe usate per il meccanismo di riflessione, la configurazione e i sostituti di test che fanno riferimento a System.Data.SqlClient.

Non sostituire i namespace generali System.Data o System.Data.Common. Microsoft.Data.SqlClientcontinua a usare tipi ADO.NET come CommandType, DbType, IsolationLevel, DataTable, DbConnection, e DbCommand da quei namespace.

Alcuni tipi specifici di SQL Server si spostano in altri Microsoft.Data namespace:

TIPO Namespace precedente Spazio dei nomi 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

Nella Microsoft.Data.SqlClient versione 5.0 e successiva, altri tipi di runtime del common language (CLR) di SQL Server rimangono in Microsoft.SqlServer.Server. Aggiorna ogni tipo in base agli errori del compilatore e alla documentazione di riferimento dell'API Microsoft.Data.SqlClient, anziché sostituire l'intero namespace.

Aggiorna la configurazione del framework .NET

Un'applicazione che individua i provider tramite DbProviderFactories potrebbe richiedere la registrazione di un provider in App.config o 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>

Codice di aggiornamento che richiede il nome invariante del provider:

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

Non aggiungere questa configurazione quando l'applicazione crea SqlConnection direttamente e non utilizza DbProviderFactories.

Revisionare la crittografia e la validazione dei certificati

Microsoft. Data.SqlClient utilizza valori predefiniti più sicuri rispetto a System.Data.SqlClient.

Behavior System.Data.SqlClient Microsoft.Data.SqlClient
Crittografia predefinita Encrypt=false Encrypt=true A partire dalla versione 4.0
Convalida certificato del server Valida il certificato solo quando la crittografia client è abilitata A partire dalla versione 2.0, il certificato viene validato in base a TrustServerCertificate quando il server impone la crittografia, anche se Encrypt=false
Crittografia rigorosa Non supportato Encrypt=Strict a partire dalla versione 5.0 per server compatibili TDS 8.0
SqlConnectionStringBuilder.Encrypt tipo bool SqlConnectionEncryptOption A partire dalla versione 5.0

Non impostare Encrypt=false o TrustServerCertificate=true come soluzione generale per la migrazione. Configura un certificato di cui il client si fida e usa un nome server che corrisponda al certificato. Usa TrustServerCertificate=true solo per ambienti di sviluppo controllati dove la validazione non è possibile.

La modifica di SqlConnectionEncryptOption è compatibile a livello di codice sorgente nelle assegnazioni più comuni tramite conversioni implicite, ma introduce una rottura della compatibilità binaria. Ricompila ogni assembly che accede a SqlConnectionStringBuilder.Encrypt.

Per i dettagli, vedere Crittografia e convalida di certificati.

Revisiona le stringhe di connessione

Microsoft. Data.SqlClient aggiunge parole chiave e alias che System.Data.SqlClient non riconosce. Ad esempio, accetta alias con spazi come Application Intent e Multi Subnet Failover.

Non costruire una stringa di connessione con Microsoft.Data.SqlClient.SqlConnectionStringBuilder e poi passarla a System.Data.SqlClient. Durante una migrazione graduale, mantieni ogni generatore di stringhe di connessione associato al relativo provider.

Verifica le parole chiave di autenticazione, crittografia, nuovo tentativo, failover e dei certificati in base alla sintassi delle stringhe di connessione.

Esamina il comportamento dei parametri

Testare esplicitamente i parametri di data e ora:

Parametro Comportamento di System.Data.SqlClient Comportamento di Microsoft.Data.SqlClient
DbType.Time con valore DateTime Accetta il valore Usa un TimeSpan valore
DbType.Date con valore DateTime Può inviare componenti di data e ora Tronca le componenti temporali

Specifica SqlDbType, lunghezza, precisione e scala per parametri in cui l'inferenza di tipo SQL Server può modificare i piani di query o il comportamento di conversione. Non usarla AddWithValue come scorciatoia per la migrazione quando il tipo di database è noto.

Controlla le referenze dei fornitori transitivi

La rimozione diretta di un pacchetto non garantisce che System.Data.SqlClient venga rimosso. Corri!

dotnet list package --include-transitive

Se entrambi i fornitori rimangono:

  1. Identifica il pacchetto che include System.Data.SqlClient.
  2. Aggiorna o sostituisci quella dipendenza quando possibile.
  3. Mantenere i tipi specifici del fornitore all'interno del confine della dipendenza quando entrambi devono essere mantenuti.
  4. Usa pseudonimi espliciti solo come aiuto temporaneo. Non passare una connessione, transazione, parametro o lettore da un fornitore all'altro.

Presta particolare attenzione alle librerie CLR di tipo SQL Server e ai vecchi framework di accesso ai dati che espongono System.Data.SqlClient tipi nelle loro API pubbliche.

Rivedi il comportamento della globalizzazione

Le versioni di .NET Framework e .NET precedenti a .NET 5 utilizzano la globalizzazione National Language Support (NLS) su Windows. Le versioni attuali di .NET utilizzano di default International Components for Unicode (ICU) su Windows, Linux e macOS.

Questa differenza nel runtime può influire su alcuni confronti SqlString. SQL Server utilizza il comportamento di confronto NLS. Se i confronti sul lato SqlString client devono corrispondere al comportamento del server, verifica i valori interessati e consulta Globalizzazione e ICU. Un'applicazione può utilizzare NLS invece della terapia intensiva quando necessario.

La modalità invariante alla globalizzazione non è supportata da Microsoft. Data.SqlClient.

Valida l'applicazione migrata

Compila ed esegui i test su ogni framework di destinazione e sistema operativo supportato.

Convalidare:

  • Ripristino del pacchetto e risultato pubblicato.
  • Autenticazione SQL, autenticazione integrata Windows e autenticazione Microsoft Entra utilizzate dall'applicazione.
  • Negoziazione TLS, convalida dei certificati e analisi sintattica della stringa di connessione.
  • Pooling delle connessioni e aggiornamento del token di accesso.
  • Tipi di parametri, valori nulli, precisione, scala, data e comportamento temporale.
  • Transazioni, cancellazioni, timeout, nuovi tentativi e failover.
  • Always Encrypted, tipi CLR di SQL Server, copia in blocco, notifiche delle query e altre funzionalità specifiche del provider utilizzate dall'applicazione.
  • Registrazione, contatori, tracciamento e gestione delle eccezioni.

Esegui query rappresentative su ogni versione supportata del motore di database. Una compilazione di successo non convalida la sicurezza della connessione, le dipendenze a runtime o le conversioni di dati.

Contenuti correlati

  • Last updated on