Microsoft. Data.SqlClient pour SQL Server

Télécharger ADO.NET

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. Il est distribué sous forme de package NuGet, évolue indépendamment du runtime .NET, et remplace System.Data.SqlClient pour le nouveau développement. Il fournit des connexions, des commandes, un traitement de résultats, des transactions, une copie en masse et des fonctionnalités spécifiques à SQL Server aux applications .NET.

Choisir votre point de départ

Base de référence de production pour Azure SQL

Utilisez cet extrait comme point de départ pour un chemin d’accès aux données Azure SQL orienté production. Il lit les noms des serveurs et des bases de données à partir de IConfiguration, donc les valeurs proviennent des fournisseurs de configuration que l’hôte configure, tels que appsettings.json, les variables d’environnement, Azure App Configuration et les paramètres soutenus par Key Vault. La configuration combine ces caractéristiques :

  • Sécurité de la couche de transport (TLS).
  • Identité managée.
  • Résilience des connexions inactives.
  • Réessai de connexion initiale via logique de réessayage configurable (CRL), avec journalisation structurée.
  • Tentative au niveau de commande pour les erreurs transitoires qui surviennent en cours de requête.
  • Récupération rapide du groupe de basculement.
  • Appels asynchrones qui acceptent un jeton d’annulation.

Pour une meilleure sécurité et pour supporter la configuration à travers les environnements, gardez les informations de connexion en dehors de votre code. En production, stockez les informations de connexion dans le système de configuration de votre application, et utilisez Azure Key Vault pour les valeurs sensibles. Pour plus d’informations, consultez Protéger les informations de connexion.

L’extrait C# dans cet article omet using les directives et les enveloppes de classe pour plus de concision.

Le snippet suppose un projet ciblant les versions .NET 8 ou ultérieures et fait référence aux packages Microsoft.Data.SqlClient et Microsoft.Data.SqlClient.Extensions.Azure version 7.1.1. L’hôte, tel que le .NET Generic Host ou ASP.NET Core, fournit le ILogger et le IConfiguration, et la configuration fournit le nom du serveur dans Sql:Server et le nom de la base de données dans Sql:Database.

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

La méthode renvoie le nom de la base de données à laquelle elle s'est connectée et enregistre Connected to database <database>. Lorsqu’une nouvelle tentative a lieu, il consigne aussi un avertissement par nouvelle tentative, à l’exception de l’exception qui l’a déclenchée.

Comment fonctionne chaque partie de l’extrait de code :

  • Cibles : Tout point d’accès SQL Moteur de base de données configuré pour l’authentification Microsoft Entra : Azure SQL Database, Azure SQL Managed Instance, base de données SQL dans Microsoft Fabric, et SQL Server 2022 et versions ultérieures sur Machines virtuelles Azure ou avec Azure Arc.
  • Encrypt = SqlConnectionEncryptOption.Strict: Sélectionne le chiffrement TDS 8.0. Il nécessite SQL Server 2022 et versions ultérieures, Azure SQL Database, Azure SQL Managed Instance, ou une base de données SQL dans Microsoft Fabric. À utiliser SqlConnectionEncryptOption.Mandatory pour les serveurs plus anciens.
  • ActiveDirectoryManagedIdentity: Fonctionne uniquement lorsqu’une identité gérée est disponible, comme Azure App Service, Azure Functions ou une machine virtuelle Azure. Pour le développement local, utilisez SqlAuthenticationMethod.ActiveDirectoryDefault, qui tente la connexion Azure CLI, la connexion Visual Studio et d’autres sources d’informations d’identification. Ne pas le mettre en production car sonder chaque source ralentit la connexion. Pour plus d’informations, voir Utiliser l’authentification par défaut.
  • MultiSubnetFailover = true: Tente des connexions TCP à toutes les adresses IP résolues en parallèle et utilise la première connexion qui réussit, évitant ainsi la marche séquentielle lente par IP. Configurez-le pour Azure SQL Database, Azure SQL Managed Instance, base de données SQL dans Microsoft Fabric, écouteurs de groupes de disponibilité et instances de cluster de basculement. C’est sans danger sur des cibles à IP unique. Il n’est pas pris en charge pour les instances nommées, les protocoles autres que TCP, les instances avec plus de 64 adresses IP, ni la mise en miroir de bases de données, qui est obsolète. Utilisez plutôt les groupes de disponibilité Always On. Pour plus d’informations, voir Haute disponibilité et reprise après sinistre et Désactivation de la résolution IP réseau transparente.
  • ConnectRetryCount = 3 et ConnectRetryInterval = 10: Le pilote retente les échecs transitoires admissibles pendant Open(), et reconnecte une connexion inactive interrompue à la commande suivante. Le nombre par défaut est de 1. Trois tentatives espacées de 10 secondes dépassent la durée d’une reconfiguration prolongée ou d’un basculement. Le pilote passe de 1 à 2 uniquement lorsque le nom du serveur se termine dans un domaine Azure SQL connu, comme .database.windows.net, donc un alias DNS personnalisé obtient 1.
  • openRetry: Assigné à SqlConnection.RetryLogicProvider, il ajoute un backoff exponentiel autour de Open(). Le pilote arrête ses tentatives internes à l’expiration ConnectTimeout, donc le pire scénario avant que OpenAsync ne lève une exception est de cinq tentatives allant jusqu’à 30 secondes chacune, plus le délai d’attente. Chaque tentative de reconnexion en mode inactif exécute également la politique complète openRetry, et lorsque cette politique épuise ses tentatives, la récupération en mode inactif prend fin.
  • Mise en pause automatique serverless : pour Azure SQL Database serverless, augmentez ConnectTimeout à au moins 60 secondes. Le premier Open() peut échouer avec une erreur 40613 pendant que la base de données redémarre, et openRetry tente à nouveau. Un délai d’attente côté client se manifeste par l’erreur -2, qui n’est pas réessayée, donc chaque tentative de connexion doit dépasser la durée de la reprise. Pour plus d’informations, voir Mise en pause automatique et reprise automatique.
  • commandRetry: Attachez-la uniquement à SqlCommand.RetryLogicProvider lorsque la réexécution de la commande est sûre : lectures, MERGE protégée par une clé naturelle, upserts via une procédure stockée, et autres opérations idempotentes. Il n’effectue pas de nouvelle tentative à l’intérieur d’une transaction, donc le code applicatif doit réessayer les transactions comportant plusieurs instructions. ExecuteReader et ExecuteScalar réessaient uniquement les erreurs renvoyées avant le début du premier ensemble de résultats. ExecuteNonQuery réessaie tout l’appel.
  • Liste d’erreurs transitoires : Le fait de définir TransientErrors remplace la liste intégrée. Pour l’étendre à la place, utilisez SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 et versions ultérieures).
  • Retrying Événement : Retrying se déclenche avant chaque nouvelle tentative avec le nombre de réessais, le délai suivant et les exceptions jusqu’à présent. Acheminez-le vers ILogger ou votre pipeline de télémétrie.
  • Exceptions : La méthode n’intercepte pas les exceptions. Un fournisseur épuisé lance AggregateException avec l’exception de chaque tentative. Une erreur non transitoire se propage comme l’exception initiale. L’appelant la journalise une fois avec le reste du contexte de la requête.
  • Annulation : Le CancellationToken arrête le délai d’attente du fournisseur entre les tentatives. Cela n’interrompt pas l’attente du conducteur ConnectRetryInterval pendant une seule Open tentative. Pour plus d’informations, voir Programmation asynchrone.
  • Durée de vie du fournisseur : Le fragment crée les fournisseurs de nouvelle tentative à chaque appel pour rester autonome. Dans une application, créez-les une fois et réutilisez-les.

Pour plus d’informations sur chaque partie de cette configuration, consultez :

Apprenez les tâches principales d’accès aux données

Une fois que vous vous connectez, utilisez ces articles dans l’ordre :

  1. Exécutez une commande pour choisir un format de résultat et exécutez Transact-SQL (T-SQL).
  2. Configurez les paramètres pour qu’ils correspondent au schéma de la base de données.
  3. Récupérez les données avec SqlDataReader pour traiter les lignes et plusieurs résultats.
  4. Modification des données avec des procédures stockées pour utiliser les paramètres de sortie et les valeurs de retour.
  5. Utilisez une programmation asynchrone et une annulation pour ajouter l’annulation de l’appelant et des délais d’attente bornés.
  6. Gérez les erreurs et les messages avant d’ajouter des nouvelles tentatives ou des diagnostics de production.

Principales fonctionnalités

  • Prise en charge moderne du .NET : Fonctionne sur les versions actuelles de .NET et .NET Framework. Pour la répartition par version, voir Cycle de vie du support.
  • Chiffré par défaut : connexions chiffrées TLS avec Encrypt=true comme valeur par défaut. Définir Encrypt=Strict pour le chiffrement TDS 8.0.
  • Authentification Microsoft Entra ID : connexions sans mot de passe avec identité managée, principal de service, chaîne d’informations d’identification interactive, intégrée et par défaut et flux de jeton d’accès.
  • Kerberos et NTLM : Authentification Windows intégrée pour Active Directory local et scénarios hérités.
  • Always Encrypted : chiffrement côté client pour les colonnes sensibles, avec enclaves sécurisées facultatives pour les opérations sur place.
  • Copie en masse : insertions à haut débit avec SqlBulkCopy.
  • Pool de connexions: activé par défaut. Un pool V2 à adhésion volontaire est en cours d’évaluation.
  • Résilience de connexion : Réessayages intégrés de connexion (ConnectRetryCount et ConnectRetryInterval) plus logique de réessayage configurable optionnelle pour les connexions et commandes.
  • Types de données riches sur SQL Server : datetimeoffset, sql_variant, JSON, vectoriel, spatial, XML et paramètres à valeurs de table.
  • Diagnostic : traçage des sources d’événements, compteurs de diagnostic, statistiques des fournisseurs et un guide dédié au dépannage.
  • Identité de l’application : Définir SqlConnection.RegisteredApplication pour identifier votre bibliothèque ou outil auprès de SQL Server (Microsoft.Data.SqlClient 7.1 et versions ultérieures).

Get started

Article Description
Commencez avec le pilote SqlClient Configurez un projet, créez une base de données, connectez-vous, interrogez et ajoutez la résilience des connexions.
Installer, mettre à jour et déployer Microsoft. Data.SqlClient Installez les packages NuGet, choisissez une version, mettez à jour le pilote et préparez la sortie de déploiement.
Cycle de vie de support Consultez les versions de pilotes prises en charge et les dates de prise en charge.
Migrer de System.Data.SqlClient vers Microsoft. Data.SqlClient Mettez à jour les références de paquets, les espaces de noms, la configuration et le comportement modifié des pilotes.
Espace de noms Microsoft.Data.SqlClient et compatibilité Comprenez comment SqlClient implémente ADO.NET et sa compatibilité avec System.Data.SqlClient, .NET et SQL Server.
Nouveautés chez Microsoft. Data.SqlClient Trouvez les sorties actuelles, les changements majeurs de mise à jour et les notes de sorties en amont.

Configuration et connexion

Article Description
Se connecter à une source de données Ouvrez et gérez les connexions, et réagissez aux changements d’état de la connexion.
Chaînes de connexion Configurez le comportement du serveur, de la base de données, de l’authentification, du chiffrement et des connexions.
Chiffrement et validation de certificat Configurez les connexions chiffrées et la validation des certificats serveur.
Pooling de connexions SQL Server Réutilisez efficacement les connexions physiques.
Gérer les erreurs et les messages Détectez les erreurs et recevez des messages d’information.

Authentifier et être sécurisé

Article Description
Meilleures pratiques de sécurité pour Microsoft. Data.SqlClient Examinez les conseils sur l’authentification, l’autorisation et la sécurité des applications.
Authentification Microsoft Entra Connectez-vous avec l’identité gérée, le principal de service, le mot de passe et les flux interactifs.
Protéger les informations de connexion Garde les identifiants et les paramètres de connexion hors du code de l’application.
Toujours chiffré Protège les valeurs sensibles des colonnes du système de base de données.
Always Encrypted avec enclaves sécurisées Exécutez des opérations enrichies sur des données chiffrées avec une enclave sécurisée.

Récupérer et mettre à jour les données

Article Description
Exécuter une commande Exécutez des instructions SQL paramétrées et des procédures stockées.
DataAdapters et DataReaders Diffuser en continu des jeux de résultats ou remplir des structures de données déconnectées.
Exécuter plusieurs commandes avec SqlBatch Envoyez une collection ordonnée de commandes et traitez leurs résultats.
Données de flux Transférez de grandes valeurs binaires, textuelles, XML et JSON sans mettre en mémoire tampon la valeur complète.
Transactions et accès simultané Utilisez des transactions locales et distribuées ainsi que des contrôles de concurrence concurrente.
Récupérer les informations du schéma de la base de données Découvrez les collections et restrictions de schémas.
Opérations de copie en bloc Chargez efficacement de grands ensembles de données avec SqlBulkCopy.
Paramètres de type table Envoyez plusieurs lignes à une instruction paramétrée ou à une procédure stockée.
MARS (Multiple Active Result Sets) Entrelacez plusieurs lots sur une même connexion.

Types de données

Article Description
Mappages de types de données SQL Server Mapper les types SQL Server aux types .NET et System.Data.SqlTypes.
Données JSON Envoyez et récupérez le type de données json de SQL Server.
Données vectorielles Envoyer et récupérer les valeurs vectorielles.
Données XML Lire, écrire et paramétrer les valeurs XML.
Données binaires et à grande valeur Diffusez et mettez à jour les données binaires, FILESTREAM et de grande valeur.

Fiabilité et diagnostics

Article Description
Logique de nouvelle tentative configurable Réessayez les erreurs transitoires de connexion et de commande avec des stratégies bornées.
Haute disponibilité et récupération d’urgence Connectez-vous aux écouteurs de groupe de disponibilité et aux partenaires de basculement.
Compteurs d’événements dans SqlClient Surveillez les connexions actives, les connexions du pool et d’autres métriques du pilote.
Activer la recherche de la source d’événements Capturez des événements détaillés du pilote à des fins de diagnostic.
Guide de résolution des problèmes SqlClient Diagnostiquez les problèmes courants de connexion et de pilotage.
Notifications de requête Recevez des notifications lorsque les résultats des requêtes changent.

fonctionnalités SQL Server

Article Description
Fonctionnalités de SQL Server et ADO.NET Parcourez les fonctionnalités spécifiques à SQL Server disponibles via SqlClient.
LocalDB Connectez-vous aux instances LocalDB de SQL Server Express.
Découverte et classification des données Lisez les métadonnées de classification de sensibilité à partir des ensembles de résultats.

Informations de référence et ressources

Article Description
Référence de l’API Microsoft.Data.SqlClient Parcourez la référence API .NET pour le pilote.
Commutateurs AppContext Configurez la compatibilité et le comportement de sécurité.
Dépôt GitHub Microsoft.Data.SqlClient Lisez le code source du pilote, les notes de version et les exemples.
Exemples Microsoft.Data.SqlClient Parcourez les exemples de C# pour les API de pilotes.
Dépôt .NET runtime GitHub Lisez le code source des bibliothèques du runtime .NET.

Demander une fonctionnalité

Pour demander une fonctionnalité, ouvrez un problème dans le dépôt Microsoft. Data.SqlClient GitHub.

Contenu connexe

  • Dernière mise à jour :