Microsoft. Data.SqlClient per SQL Server

Scarica ADO.NET

Microsoft. Data.SqlClient è il provider di dati .NET supportato per SQL Server, database SQL di Azure, Istanza gestita di SQL di Azure, Azure Synapse Analytics e database SQL in Microsoft Fabric. È distribuito come pacchetto NuGet, si evolve indipendentemente dal runtime .NET e viene sostituito System.Data.SqlClient per nuovi sviluppi. Usalo per aprire connessioni, eseguire comandi, elaborare risultati, gestire transazioni, caricare dati in massa e utilizzare funzionalità specifiche di SQL Server dalle applicazioni .NET.

Scegliere il punto di partenza

Baseline di produzione per Azure SQL

Usa questo frammento come punto di partenza per un percorso di accesso ai dati Azure SQL orientato alla produzione. Legge i nomi dei server e del database da IConfiguration, quindi i valori provengono dai fornitori di configurazione che l'host collega (appsettings.jsonvariabili di ambiente, Configurazione app di Azure, impostazioni supportate da Key Vault, e così via). La configurazione combina Transport Layer Security (TLS), identità gestita, resilienza della connessione inattiva, ritenti di connessione iniziale tramite logica di ritentazione configurabile (CRL) con logging strutturato, ritenti a livello di comando per errori transitori che si lanciano durante la query e rapido recupero del gruppo di failover.

Per una maggiore sicurezza e per supportare la configurazione tra ambienti, tieni le informazioni di connessione fuori dal tuo codice. In produzione, memorizza le informazioni di connessione nel sistema di configurazione della tua applicazione e usa Azure Key Vault per i valori sensibili. Per altre informazioni, vedere Proteggere le informazioni di connessione.

Il frammento su C# in questo articolo omette using direttive e involucri di classe per brevità.

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 any target; 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;
    }
}

Questo frammento di codice è ottimizzato per i gruppi di failover di database SQL di Azure e Istanza gestita di SQL di Azure.

Encrypt = SqlConnectionEncryptOption.Strict seleziona la crittografia TDS 8.0. Serve Microsoft. Data.SqlClient 5.0 e versioni successive e un server che supporta TDS 8.0 (SQL Server 2022 e versioni successive, database SQL di Azure, Istanza gestita di SQL di Azure e database SQL in Microsoft Fabric). Torna a SqlConnectionEncryptOption.Mandatory quando ti connetti ai server più vecchi.

ConnectRetryCount e ConnectRetryInterval abilitare la resilienza della connessione inattiva: dopo Open() il successo, il driver riconnette trasparentmente una connessione idle interrotta al comando successivo. Non riprovano l'iniziale Open(). I tentativi di connessione iniziale provengono dal openRetry provider assegnato a SqlConnection.RetryLogicProvider. Le due caratteristiche sono complementari.

L'evento Retrying su ciascun provider si attiva prima di ogni tentativo di ritentativi e riporta il conteggio dei ritentativi, il ritardo prima del tentativo successivo e le eccezioni osservate finora. Instradalo verso ILogger o la tua pipeline di telemetria per mantenere visibile il ciclo di ritenti in produzione.

Impostato MultiSubnetFailover = true per qualsiasi target SQL Server. Seleziona un percorso di codice parallel-connect che completa l'accesso con il primo endpoint responsivo, evitando la lenta camminata sequenziale per IP che altrimenti potrebbe bloccare la connessione a database SQL di Azure, Istanza gestita di SQL di Azure, database SQL in Microsoft Fabric, ascoltatori di gruppi di disponibilità e istanze di cluster di failover. Sui bersagli a singolo IP, l'impostazione è sicura. Per maggiori informazioni, vedi Alta disponibilità e disaster recovery e Disabilitazione della risoluzione IP trasparente di rete.

Se il target è database SQL di Azure serverless con auto-pausa attivata, aumenta ConnectTimeout a almeno 60 secondi. Un database in pausa automatica riprende il primo Open(), e il riprendimento può durare da 30 a 60 secondi o più. I timeout lato client appaiono come errori -2, che non è nella lista di errori transitori integrata, quindi openRetry non salveranno un Open() timeout che si scade a metà ripresa. Il tentativo di contatto individuale deve essere abbastanza lungo da coprire il curriculum.

Il ritentativo a livello di comando è una decisione del chiamante, per comando. Attacca commandRetry solo SqlCommand.RetryLogicProvider quando riprodurre il comando è sicuro: lettura, MERGE protetto da una chiave naturale, sovrasta tramite una procedura memorizzata e altre operazioni idempotenti. Il provider di comandi integrato salta il ritentativo quando una transazione è attiva, quindi le transazioni multi-istruzione devono essere riprovate tramite codice applicativo che può riaprire la transazione. Impostazione TransientErrors sostituisce la lista di errori integrata del driver; per estendere la base integrata, usa SqlConfigurableRetryFactory.BaselineTransientErrors invece (Microsoft. Data.SqlClient 7.0 e successive).

Per altre informazioni su ogni parte di questa configurazione, vedere:

Funzionalità principali

  • Supporto moderno per .NET: Funziona sulle versioni attuali di .NET e .NET Framework. Per la suddivisione per versione, vedi ciclo di vita del supporto.
  • Criptato di default: connessioni TLS crittografate con Encrypt=true come predefinito. Impostato Encrypt=Strict per la crittografia TDS 8.0 su Microsoft. Data.SqlClient 5.0 e successive.
  • Autenticazione di Microsoft Entra ID: connessioni senza password con identità gestita, entità servizio, autenticazione interattiva, autenticazione integrata, catena di credenziali predefinita e flussi di token di accesso.
  • Kerberos e NTLM: autenticazione di Windows integrata per Active Directory locale e scenari legacy.
  • Always Encrypted: crittografia lato client per colonne sensibili, con enclave sicure facoltative per operazioni eseguite sul posto.
  • Copia in massa: inserti ad alta produttività con SqlBulkCopy.
  • Resilienza della connessione: Tentativi di connessione integrati (ConnectRetryCount e ConnectRetryInterval) più logica di ritentazione configurabile opt-in per connessioni e comandi.
  • Tipi di dati SQL Server ricchi: datetimeoffset, sql_variant, JSON, vettoriale, spaziale, XML e parametri a valori tabella.
  • Diagnostica: tracciamento delle sorgenti degli eventi, contatori diagnostici, statistiche dei fornitori e una guida dedicata alla risoluzione dei problemi.

Get started

Article Description
Introduzione al driver SqlClient Configura un progetto, crea un database, connetti, interroga e aggiungi resilienza alla connessione.
Panoramica del driver SqlClient Scopri come Microsoft. Data.SqlClient si inserisce in ADO.NET.
Scarica Microsoft. Data.SqlClient Installa il pacchetto NuGet e cerca le versioni sorgente.
Ciclo di vita del supporto Rivedi le versioni dei driver supportati e le date di supporto.
Microsoft. Spazio dei nomi Data.SqlClient Migra da System.Data.SqlClient e rivedi le differenze nello spazio dei nomi.

Configurazione e connessione

Article Description
Connessione a un'origine dati Apri e gestisci le connessioni a SQL Server e Azure SQL.
Stringhe di connessione Configura server, database, autenticazione, crittografia e comportamento delle connessioni.
Crittografia e convalida di certificati Configurare connessioni criptate e validazione dei certificati server.
Pooling di connessioni SQL Server Riutilizza le connessioni fisiche in modo efficiente.
Eventi di connessione Rispondi allo stato della connessione e ai messaggi informativi.

Autenticazione e sicurezza

Article Description
Sicurezza di SQL Server Esamina le linee guida sull'autenticazione, l'autorizzazione e la sicurezza delle applicazioni.
Autenticazione Microsoft Entra Connettiti con identità gestita, main principal, password e flussi interattivi.
Proteggere le informazioni di connessione Tieni le credenziali e le impostazioni di connessione fuori dal codice dell'applicazione.
Sempre criptato Proteggere i valori sensibili delle colonne dal sistema di database.
Always Encrypted con enclave protette Esegui operazioni arricchite su dati criptati con un enclave sicuro.

Recupero e aggiornamento dei dati

Article Description
Comandi e parametri Esegui istruzioni SQL parametrizzate e stored procedure.
DataAdapter e DataReader Insiemi di risultati di flusso o popolazione di strutture dati disconnesse.
Transazioni e concorrenza Usa transazioni locali e distribuite e controlli di concorrenza.
Recupero delle informazioni dello schema del database Scopri le collezioni di schemi e le restrizioni.
Operazioni di copia di massa Caricare grandi set di dati in modo efficiente con SqlBulkCopy.
Parametri con valori di tabella Invia più righe a un'istruzione parametrizzata o a una procedura memorizzata.
Programmazione asincrona Usa operazioni asincrone di connessione, comandi e dati.
MARS (Multiple Active Result Sets) Intercalare più lotti su una sola connessione.

Tipi di dati

Article Description
Mappature dei tipi di dati ADO.NET Mappare i tipi di runtime del linguaggio comune ai tipi provider e SQL Server.
Tipi di dati SQL Server Lavora con valori e System.Data.SqlTypes tipi specifici di SQL Server.
Dati JSON Invia e recupera il tipo di dato SQL Serverjson.
Dati vettoriali Invia e recupera i valori dei vettori.
Dati XML Leggere, scrivere e parametrizzare i valori XML.
Dati binari e di grande valore Trasmetti e aggiorna dati binari, FILESTREAM e di grande valore.

Affidabilità e diagnostica

Article Description
Logica di ripetizione dei tentativi configurabile Riprova i fallimenti di connessione e comando transitori con policy limitate.
Disponibilità elevata e ripristino di emergenza Connettiti con ascoltatori di gruppi di disponibilità e partner di failover.
Contatori diagnostici Monitora le connessioni attive, le connessioni in pool e altre metriche dei driver.
Abilita il tracciamento delle sorgenti eventi Registra eventi dettagliati dei conducenti per la diagnosi.
Data tracciamento Tracciare le operazioni ADO.NET e l'accesso ai dati.
Guida alla risoluzione dei problemi di SqlClient Diagnostica i problemi comuni di connessione e driver.
Notifiche di query Ricevi notifiche quando i risultati delle query cambiano.

Caratteristiche di SQL Server

Article Description
Funzionalità di SQL Server e ADO.NET Sfoglia le funzionalità specifiche di SQL Server disponibili tramite SqlClient.
DB locale Connettiti alle istanze LocalDB di SQL Server Express.
Individuazione e classificazione dei dati Leggi i metadati di classificazione della sensibilità dai set di risultati.

Informazioni di riferimento e risorse

Article Description
Microsoft. Riferimento API Data.SqlClient Consulta il riferimento API .NET per il driver.
Commutatori AppContext Configura compatibilità e comportamento di sicurezza.
Trova ulteriori informazioni su SqlClient Trova codice sorgente, supporto e risorse della comunità.

Contenuti correlati

  • Last updated on