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 et la base de données SQL 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

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
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // 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 activent la résilience des connexions inactives : une fois Open() réussi, le pilote reconnecte de manière transparente une connexion inactive interrompue lors de la commande suivante. Ils ne réessaient pas le fichier initial Open(). Les tentatives initiales de connexion proviennent du openRetry fournisseur assigné à SqlConnection.RetryLogicProvider. Les deux caractéristiques sont complémentaires.

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 :

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

Article Description
Bien démarrer avec le pilote SqlClient Configurez un projet, créez une base de données, connectez-vous, interrogez et ajoutez la résilience des connexions.
Vue d’ensemble du pilote SqlClient Découvrez comment Microsoft. Data.SqlClient s’intègre dans ADO.NET.
Téléchargez Microsoft. Data.SqlClient Installez le paquet NuGet et trouvez les versions source.
Cycle de vie de support Consultez les versions de pilotes prises en charge et les dates de prise en charge.
Espace de noms Microsoft.Data.SqlClient Migrez depuis System.Data.SqlClient et examinez les différences d’espace de noms.

Configuration et connexion

Article Description
Se connecter à une source de données Ouvrez et gérez les connexions vers SQL Server et Azure SQL.
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.
Événements de connexion Répondez à l’état de connexion et aux messages d’information.

Authentifier et être sécurisé

Article Description
Sécurité de SQL Server 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
Commandes et paramètres 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.
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.
Programmation asynchrone Utilisez des opérations asynchrones de connexion, de commande et de données.
MARS (Multiple Active Result Sets) Entrelacez plusieurs lots sur une même connexion.

Types de données

Article Description
Correspondance des types de données ADO.NET Mappez les types courants du Common Language Runtime aux types du fournisseur et de SQL Server.
Types de données SQL Server Travailler avec des valeurs et System.Data.SqlTypes types spécifiques à SQL Server.
Données JSON Envoyez et récupérez le type de données SQL Serverjson.
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 de diagnostic 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.
Traçage des données Tracez les opérations ADO.NET et l’accès aux données.
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é.
Trouvez des informations supplémentaires sur SqlClient Trouvez le code source, le support et les ressources communautaires.

Contenu connexe

  • Last updated on