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. Utilisez-le pour ouvrir des connexions, exécuter des commandes, traiter des résultats, gérer des transactions, charger en masse des données et utiliser des fonctionnalités spécifiques à SQL Server issues d’applications .NET.

Choisir votre point de départ

• Pour configurer un projet et lancer votre première requête, commencez par commencer avec le pilote SqlClient.
• Pour ajouter ou mettre à jour le pilote dans un projet .NET, allez dans Installer, mettre à jour et déployer Microsoft. Data.SqlClient.
• Pour se connecter à Azure SQL avec une authentification sans mot de passe, commencez par l’authentification Microsoft Entra et les chaînes de connexion.
• Pour rendre une application existante résiliente aux pannes transitoires, allez dans Logique de réessayage configurable et Haute disponibilité et récupération après sinistre.
• Pour déplacer efficacement de gros ensembles de données, allez dans Opérations de copie en masse.
• Pour migrer depuis System.Data.SqlClient, commencez par migrer de System.Data.SqlClient vers Microsoft. Data.SqlClient.
• Pour diagnostiquer un problème de connexion ou de requête, consultez le guide de dépannage SqlClient et activez la recherche de la source d’événements.

Choisir une base de données

Créez une base de données ou connectez-vous à une base de données existante sur l’une des plateformes suivantes :

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 de la base de données à partir de IConfiguration, donc les valeurs proviennent des fournisseurs de configuration que l’hôte connecte (appsettings.jsonvariables d’environnement, Azure App Configuration, paramètres soutenus par Key Vault, etc.). La configuration combine la sécurité de la couche de transport (TLS), l’identité gérée, la résilience des connexions inactives, la réévaluation de la connexion initiale via une logique de réessayage configurable (CRL) avec journalisation structurée, une réévaluation au niveau de commande pour les erreurs transitoires déclenchées en cours de requête, et une récupération rapide par groupe de basculement.

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.

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    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 (SqlClient 5.0 and later versions; 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);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

Ce snippet cible tout point de terminaison 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 activées par Azure Arc.

Encrypt = SqlConnectionEncryptOption.Strict sélectionne le chiffrement TDS 8.0. Cela nécessite Microsoft. Data.SqlClient 5.0 et versions ultérieures, ainsi qu’un serveur supportant TDS 8.0 (SQL Server 2022 et versions ultérieures, Azure SQL Database, Azure SQL Managed Instance, et SQL database dans Microsoft Fabric). Basculez sur SqlConnectionEncryptOption.Mandatory lorsque vous vous connectez à des serveurs plus anciens.

ConnectRetryCount et ConnectRetryInterval s’appliquent lors de l’établissement initial de la connexion et de la reprise d’une connexion inactive. Lorsque ConnectRetryCount est supérieur à zéro, le conducteur essaie à nouveau de qualifier les défaillances transitoires pendant Open(). Une fois que Open() a réussi, le pilote utilise également ces paramètres pour rétablir une connexion inactive interrompue à la commande suivante. Le fournisseur openRetry assigné à SqlConnection.RetryLogicProvider ajoute une politique configurable de temporisation exponentielle à Open(). Prenez en compte les deux couches de réessayage lorsque vous définissez le nombre de réessayages et le délai d’attente de connexion.

L’événement Retrying sur chaque fournisseur se déclenche avant chaque tentative de réévaluation et affiche le nombre de réessays, le délai avant la prochaine tentative, ainsi que les exceptions observées jusqu’à présent. Acheminez-le vers ILogger ou votre pipeline de télémétrie pour garder la boucle de réessai visible en production.

Définissez MultiSubnetFailover = true lorsque la cible est Azure SQL Database, Azure SQL Managed Instance, une base de données SQL dans Microsoft Fabric, un écouteur de groupe de disponibilité ou une instance de cluster de basculement. Il sélectionne un chemin de code de connexion parallèle qui tente des connexions TCP vers toutes les adresses IP résolues en parallèle et utilise la première connexion qui réussit, évitant ainsi le lent parcours séquentiel des adresses IP qui pourrait autrement retarder ces connexions. Sur les cibles à IP unique, le réglage est sûr. MultiSubnetFailover n’est pas prise en charge lorsque vous vous connectez à une instance nommée, via un protocole autre que TCP, ou à une instance configurée avec plus de 64 adresses IP. Vous ne pouvez pas non plus l'utiliser avec le miroir de base de données, qui est obsolète dans toutes les versions supportées de SQL Server. 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.

Si la cible est Azure SQL Database serverless avec l’auto-pause activée, augmentez ConnectTimeout à au moins 60 secondes. Une base de données en pause automatique reprend dès la première Open(), et cette première Open() peut échouer en cas d’erreur 40613 pendant que la base de données reprend. L’erreur 40613 figure dans la liste intégrée des erreurs transitoires, donc openRetry effectue une nouvelle tentative. Les délais d’attente côté client se manifestent par l’erreur -2, qui ne figure pas dans cette liste ; openRetry ne permettra donc pas de récupérer un(e) Open() dont le délai expire au milieu de la reprise. La tentative de contact individuel doit être suffisamment longue pour couvrir le CV. Pour plus d’informations, voir Mise en pause automatique et reprise automatique.

La nouvelle tentative au niveau de la commande relève de la décision de l’appelant, pour chaque commande. N’attachez commandRetry à SqlCommand.RetryLogicProvider que lorsque la réexécution de la commande est sans risque : lectures, MERGE protégées par une clé naturelle, upserts via une procédure stockée et autres opérations idempotentes. Le fournisseur de commandes intégré n’effectue pas de nouvelle tentative lorsqu’une transaction est active ; les transactions comportant plusieurs instructions doivent donc faire l’objet d’une nouvelle tentative par le code de l’application, qui peut rouvrir la transaction. Le paramètre TransientErrors remplace la liste d'erreurs intégrée du pilote ; pour étendre la référence intégrée, utilisez SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft. Data.SqlClient 7.0 et versions ultérieures).

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

• Chaînes de connexion
• Authentification Microsoft Entra
• Chiffrement et validation de certificat
• Logique de nouvelle tentative configurable
• Haute disponibilité et récupération d’urgence

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éfinissez Encrypt=Strict pour le chiffrement TDS 8.0 dans Microsoft.Data.SqlClient 5.0 et versions ultérieures.
• 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.
• 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.

Get started

Configuration et connexion

Authentifier et être sécurisé

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

Types de données

Fiabilité et diagnostics

fonctionnalités SQL Server

Informations de référence et ressources

Contenu connexe

• Microsoft. Data.SqlClient sur GitHub
• Microsoft. Data.SqlClient sur NuGet
• Notes de publication
• Aperçu d’ADO.NET
• Modules de connexion pour Microsoft SQL Database