Migrer de System.Data.SqlClient vers Microsoft. Data.SqlClient

Microsoft. Data.SqlClient est le fournisseur pris en charge pour les nouvelles fonctionnalités de SQL Server dans les applications .NET. Il préserve le modèle de programmation ADO.NET utilisé par System.Data.SqlClient, mais les paquets, espaces de noms, valeurs par défaut et certains types publics diffèrent.

Considérez la migration comme une mise à jour du fournisseur, pas seulement comme un remplacement d’espace de noms.

Planifier la migration

Avant de changer de code :

1. Enregistrez les versions des services .NET, System.Data.SqlClientSQL Server et Microsoft SQL que l’application supporte.

2. Répertorier les modes d’authentification, les mots-clés des chaînes de connexion, les certificats personnalisés, les fournisseurs Always Encrypted, la configuration DbProviderFactories, les types définis par l’utilisateur dans SQL Server et l’utilisation de System.Data.SqlTypes.

3. Exécutez les tests actuels de l’application et enregistrez une référence pour le comportement de connexion, requête, transaction, réessai et performance.

4. Rechercher les références de paquets directes et transitifs :

   dotnet list package --include-transitive
   

Migrez une application ou une bibliothèque d’accès partagé à la fois. Ne passez pas d'objets spécifiques au fournisseur entre le code qui utilise System.Data.SqlClient encore et celui qui utilise Microsoft.Data.SqlClient.

Remplacez le paquet

Supprimez une référence explicite System.Data.SqlClient au paquet, si elle est présente :

dotnet remove package System.Data.SqlClient

Ajouter Microsoft. Data.SqlClient :

dotnet add package Microsoft.Data.SqlClient

Si Microsoft. Data.SqlClient 7.0 ou une version ultérieure utilise un mode d’authentification Microsoft Entra fourni par le pilote, ajoutez également :

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

Pour la sélection des versions et des paquets, voir Installer, mettre à jour et déployer Microsoft. Data.SqlClient.

Mettre à jour les espaces de noms

Remplacez l’espace de noms principal du fournisseur :

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

Mettre à jour les noms entièrement qualifiés, les alias, le code généré, les enregistrements d’injection de dépendances, les chaînes de réflexion, la configuration et les doubles de test qui font référence à System.Data.SqlClient.

Ne remplacez pas les espaces de noms généraux System.Data ou System.Data.Common. Microsoft.Data.SqlClientcontinue d’utiliser des types ADO.NET tels que CommandType, DbType, IsolationLevel, DataTable, DbConnection, et DbCommand de ces espaces de noms.

Certains types spécifiques à SQL Server sont déplacés vers d’autres espaces de noms Microsoft.Data :

Dans Microsoft.Data.SqlClient la version 5.0 et ultérieure, d’autres types d’exécution du langage commun (CLR) de SQL Server restent dans Microsoft.SqlServer.Server. Mettez à jour chaque type à partir des erreurs du compilateur et de la référence de l’API Microsoft.Data.SqlClient, au lieu de remplacer l’intégralité de l’espace de noms.

Mise à jour de la configuration du framework .NET

Une demande qui résout les prestataires à travers DbProviderFactories pourrait nécessiter un enregistrement de fournisseur dans 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>

Mettre à jour le code qui demande le nom invariant du fournisseur :

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

N’ajoutez pas cette configuration lorsque l’application crée SqlConnection directement et n’utilise DbProviderFactoriespas .

Réviser le chiffrement et la validation des certificats

Microsoft. Data.SqlClient utilise des paramètres par défaut plus sécurisés que System.Data.SqlClient.

Ne définissez pas Encrypt=false ou TrustServerCertificate=true comme solution générale de migration. Configurez un certificat auquel le client a confiance et utilisez un nom de serveur correspondant au certificat. À utiliser TrustServerCertificate=true uniquement pour des environnements de développement contrôlés où la validation n’est pas possible.

La modification apportée à SqlConnectionEncryptOption est compatible au niveau du code source pour les affectations courantes grâce à des conversions implicites, mais elle constitue une rupture de compatibilité binaire. Recompilez chaque assembly qui accède à SqlConnectionStringBuilder.Encrypt.

Pour plus d’informations, consultez Chiffrement et validation de certificat.

Réviser les chaînes de connexion

Microsoft. Data.SqlClient ajoute des mots-clés et des alias que System.Data.SqlClient ne reconnaît pas. Par exemple, il accepte des alias avec des espaces tels que Application Intent et Multi Subnet Failover.

Ne construis pas une chaîne de connexion avec Microsoft.Data.SqlClient.SqlConnectionStringBuilder puis ne la transmets pas à System.Data.SqlClient. Lors d’une migration par étapes, veillez à garder chaque générateur de chaîne de connexion associé au fournisseur correspondant.

Examinez les mots-clés authentification, chiffrement, réessayage, basculement et certificats en fonction de la syntaxe des chaînes de connexion.

Examiner le comportement des paramètres

Paramètres de date et d’heure du test explicitement :

Spécifiez SqlDbType, longueur, précision et échelle pour des paramètres où l’inférence de type SQL Server peut modifier les plans de requête ou le comportement de conversion. Ne l’utilisez AddWithValue pas comme raccourci de migration lorsque le type de base de données est connu.

Vérifier les références des fournisseurs transitifs

La suppression directe d’un paquet ne garantit pas que System.Data.SqlClient a disparu. Run:

dotnet list package --include-transitive

Si les deux prestataires restent :

1. Identifiez le package qui inclut System.Data.SqlClient.
2. Mettez à jour ou remplacez cette dépendance quand possible.
3. Gardez les types spécifiques au fournisseur à l’intérieur de la limite de dépendance lorsque les deux doivent rester.
4. Utilisez des alias explicites dans les espaces de noms uniquement comme aide temporaire. Ne passez pas de connexion, de transaction, de paramètre ou de lecteur d’un fournisseur à l’autre.

Prêtez une attention particulière aux bibliothèques de types CLR de SQL Server et aux anciens frameworks d’accès aux données qui exposent des types System.Data.SqlClient dans leurs API publiques.

Examiner le comportement de la mondialisation

.NET Framework et les versions de .NET antérieures à .NET 5 utilisent la globalisation NLS (National Language Support) sur Windows. Les versions actuelles de .NET utilisent par défaut les Composants Internationaux pour Unicode (ICU) sur Windows, Linux et macOS.

Cette différence de temps d’exécution peut modifier certaines SqlString comparaisons. SQL Server utilise le comportement de comparaison NLS. Si les comparaisons côté SqlString client doivent correspondre au comportement des serveurs, testez les valeurs affectées et examinez la mondialisation et les soins intensifs. Une application peut utiliser NLS au lieu de l’ICU lorsque cela est nécessaire.

Le mode insensible à la globalisation n’est pas pris en charge par Microsoft.Data.SqlClient.

Valider l’application migrée

Construisez et testez sur chaque framework cible et système d’exploitation supporté.

Valider :

• Restauration du paquet et sortie publiée.
• Authentification SQL, authentification intégrée Windows et authentification Microsoft Entra utilisées par l’application.
• Négociation TLS, validation de certificats et analyse de chaîne de connexion.
• Regroupement de connexion et rafraîchissement des jetons d’accès.
• Types de paramètres, valeurs nulles, précision, échelle, date et comportement temporel.
• Transactions, annulation, délais d’attente, réessais et basculement.
• Always Encrypted, types CLR de SQL Server, copie en bloc, notifications de requêtes et autres fonctionnalités spécifiques au fournisseur utilisées par l’application.
• Journalisation, compteurs, traçage et gestion des exceptions.

Effectuez des requêtes représentatives sur toutes les versions prises en charge du moteur de base de données. Une compilation réussie ne valide pas la sécurité de la connexion, les dépendances à l’exécution ou les conversions de données.

Contenu connexe

• Espace de noms Microsoft.Data.SqlClient et compatibilité
• Microsoft. Notes de version et mises à jour de Data.SqlClient
• Aide-mémoire de portage dans le dépôt SqlClient
• Référence de l’API Microsoft.Data.SqlClient