Installer, mettre à jour et déployer Microsoft. Data.SqlClient

Microsoft.Data.SqlClient est le fournisseur de données .NET pris en charge pour SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, la base de données SQL dans Microsoft Fabric et l’entrepôt de données dans Microsoft Fabric. Le pilote est distribué sous forme de packages NuGet, indépendamment du runtime .NET.

Choisissez une sortie

Utilisez une version GA prise en charge pour les applications en production.

Pour les versions actuelles des correctifs, les dates de support, les cadres cibles et la compatibilité des bases de données, voir cycle de vie du support du pilote SqlClient.

Installez le package de base

Exécutez la commande suivante depuis le répertoire contenant votre fichier projet :

dotnet add package Microsoft.Data.SqlClient

La commande sélectionne la dernière version stable compatible avec le projet. Pour fixer une version pour des builds répétables, spécifiez la version suivante :

dotnet add package Microsoft.Data.SqlClient --version <version>

Restaurez les dépendances et construisez le projet :

dotnet restore
dotnet build

Importez l’espace de noms du pilote dans C# :

using Microsoft.Data.SqlClient;

Pour les nouvelles applications, ne faites pas référence à l’ancien System.Data.SqlClient paquet ou à l’espace de noms. Pour mettre à jour une application existante, voir Migrer de System.Data.SqlClient vers Microsoft. Data.SqlClient.

Installer avec Visual Studio

1. Dans Explorateur de solutions, faites un clic droit sur le projet, puis sélectionnez Gérer les paquets NuGet.
2. Dans l’onglet Parcourir , cherchez Microsoft.Data.SqlClient.
3. Sélectionnez le package appartenant à Microsoft.
4. Sélectionnez une version stable prise en charge, puis sélectionnez Installer.

Pour plus d’informations, voir Installer et gérer les paquets dans Visual Studio.

Ajouter des forfaits optionnels

Installez des packages optionnels uniquement lorsque votre application utilise la fonctionnalité associée.

Pour l’authentification Microsoft Entra avec SqlClient 7.0 ou une version ultérieure, exécutez :

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

Le package core 7.0 n’inclut plus les dépendances d’identité Azure. À partir de la version 7.0.2, les pilotes de base et les packs compagnons utilisent des versions alignées. Utilisez la même version de Microsoft.Data.SqlClient et Microsoft.Data.SqlClient.Extensions.Azure. Les applications qui n'utilisent pas l'authentification Microsoft Entra fournie par le pilote n'ont pas besoin du package d'extension Azure. Pour la configuration de l’authentification, voir authentification Microsoft Entra.

Mettez à jour le pilote

Avant la mise à jour :

1. Lisez Découvrez les nouveautés de Microsoft.Data.SqlClient ainsi que les notes de publication sources pour chaque version concernée par la mise à jour.

2. Vérifiez les références directes et transitives des paquets de l’application.

   dotnet list package --include-transitive
   

3. Mettez à jour la référence du colis.

   dotnet add package Microsoft.Data.SqlClient --version <version>
   

4. Restaurez, construisez et exécutez les tests de l’application.

5. Test de l’établissement de connexion, de l’authentification, de la validation des certificats, du pooling de connexions, des conversions de types de données, des transactions et du comportement de réessayage sur chaque cible de base de données prise en charge.

Les sorties majeures et les mises à jour peuvent nécessiter des modifications d’application. Par exemple, la version 4.0 a activé le chiffrement par défaut, la version 5.0 a fait passer SqlConnectionStringBuilder.Encrypt de bool à SqlConnectionEncryptOption, et la version 7.0 a déplacé l’authentification Microsoft Entra fournie par le pilote dans un package distinct.

À partir de la version 7.0.2, les versions assembleur de Microsoft.Data.SqlClient.Extensions.Azure, , et Microsoft.Data.SqlClient.Internal.Logging sont passées de 1.0.0.0 à 7.0.0.0Microsoft.Data.SqlClient.Extensions.Abstractions. Les applications du cadre .NET doivent se reconstruire en fonction des paquets alignés ou ajouter des redirections de liaison. Les applications sur .NET actuel ne sont pas affectées par ce changement d'identité d'assembleur.

Comprendre les cadres cibles

Microsoft. Data.SqlClient 7.0 prend en charge les applications sur :

• .NET Framework 4.6.2 ou ultérieur sur Windows.
• .NET 8 ou versions ultérieures prises en charge pour Windows, Linux et macOS.

Le package NuGet contient également un asset de compatibilité .NET Standard 2.0 pour les bibliothèques. Une application exécutable doit cibler un runtime .NET ou .NET Framework supporté. Le fait qu’une bibliothèque cible .NET Standard n’implique pas que chaque environnement d’exécution qui la consomme soit pris en charge.

Le package restaure ses dépendances gérées et natives via NuGet. Ne copiez pas d’assemblages de pilotes individuels ni de bibliothèques SQL Network Interface (SNI) natives entre applications.

Préparer le déploiement

1. Publiez pour le même système d’exploitation et la même architecture qu’en production. Pour un déploiement dépendant du framework :

   dotnet publish --configuration Release
   

   Pour un déploiement spécifique à un environnement d’exécution :

   dotnet publish --configuration Release --runtime <runtime-identifier>
   

2. Déployer l’intégralité de la sortie de publication. Ne sélectionnez pas seulement Microsoft.Data.SqlClient.dll.

3. Confirmez que la cible dispose de l’exécution .NET requise, sauf si vous publiez une application autonome.

4. Testez la version publiée sur le système d’exploitation et l’architecture cibles.

5. Testez tous les modes d’authentification utilisés en production. L’authentification intégrée, Kerberos, les certificats, l’identité gérée et l’accès à Azure Key Vault dépendent de l’environnement de déploiement.

6. Analysez le graphique de dépendances résolues à la recherche de vulnérabilités connues et mettez à jour les lignes de paquets supportées dès que des correctifs sont disponibles.

Le mode invariant de globalisation n’est pas pris en charge. Pour les qualifications actuelles de la plateforme, voir Systèmes d’exploitation pris en charge.

Installation hors ligne du package

Téléchargez le paquet et ses dépendances depuis NuGet.org, copiez-les dans un code source interne du paquet, puis restaurez à partir de cette source. Pour garantir des compilations hors ligne reproductibles, fixez les versions des paquets et préservez l’ensemble des dépendances.

Contenu connexe

• Commencez avec le pilote SqlClient
• Nouveautés chez Microsoft. Data.SqlClient
• Cycle de vie de prise en charge du pilote SqlClient
• Versions de Microsoft.Data.SqlClient