Microsoft. Data.SqlClient per SQL Server

Scarica ADO.NET

Microsoft.Data.SqlClient è il provider di dati .NET ufficialmente supportato per SQL Server, database SQL di Azure, Istanza gestita di SQL di Azure, Azure Synapse Analytics, database SQL in Microsoft Fabric e Data Warehouse 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

• Per impostare un progetto ed eseguire la tua prima query, inizia con Inizia con il driver SqlClient.
• Per aggiungere o aggiornare il driver in un progetto .NET, vai su Installa, aggiorna e distribuisci Microsoft. Data.SqlClient.
• Per connetterti ad Azure SQL con autenticazione senza password, inizia con l'autenticazione Microsoft Entra e le stringhe di connessione.
• Per rendere un'applicazione esistente resiliente agli errori temporanei, vai a Logica di ripetizione configurabile e Disponibilità elevata e ripristino di emergenza.
• Per spostare grandi set di dati in modo efficiente, vai su Operazioni di copia in massa.
• Per migrare da System.Data.SqlClient, inizia con Migra da System.Data.SqlClient a Microsoft. Data.SqlClient.
• Per diagnosticare un problema di connessione o di domanda, vai alla guida alla risoluzione dei problemi di SqlClient e attiva il tracciamento della sorgente di eventi.

Scegliere un database

Crea un database o collegati a un database esistente su una delle seguenti piattaforme:

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), l'identità gestita, la resilienza delle connessioni inattive, i nuovi tentativi di connessione iniziale tramite logica di ripetizione configurabile (CRL) con logging strutturato, i tentativi ripetuti a livello di comando per errori transitori che si verificano durante l'esecuzione della query e il ripristino rapido 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 C# in questo articolo omette le direttive using e le dichiarazioni 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
        // 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;
    }
}

Questo snippet è destinato a qualsiasi endpoint di SQL motore di database configurato per usare l'autenticazione Microsoft Entra: database SQL di Azure, Istanza gestita di SQL di Azure, un database SQL in Microsoft Fabric e SQL Server 2022 e versioni successive in Macchine virtuali di Azure o abilitati da Azure Arc.

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

ConnectRetryCount e ConnectRetryInterval applicare durante l'avvio iniziale della connessione e il recupero della connessione inattiva. Quando ConnectRetryCount è maggiore di zero, il driver riprova a qualificare i fallimenti transitori durante Open(). Dopo che Open() è riuscito, il driver utilizza anche queste impostazioni per riconnettere una connessione inattiva interrotta al successivo comando. Il openRetry provider assegnato a SqlConnection.RetryLogicProvider aggiunge una policy di retrocesso esponenziale configurabile attorno a Open(). Tieni conto di entrambi i livelli di tentativi quando imposti il numero di tentativi e il timeout della connessione.

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. Inoltralo a ILogger o alla tua pipeline di telemetria per mantenere visibile in produzione il ciclo di tentativi ripetuti.

Impostare MultiSubnetFailover = true quando la destinazione è database SQL di Azure, Istanza gestita di SQL di Azure, un database SQL in Microsoft Fabric, un listener del gruppo di disponibilità o un'istanza del cluster di failover. Seleziona un percorso del codice per la connessione parallela che tenta connessioni TCP a tutti gli indirizzi IP risolti in parallelo e utilizza la prima connessione che va a buon fine, evitando la lenta scansione sequenziale di ciascun IP che altrimenti potrebbe mandare in stallo tali connessioni. Sui bersagli a singolo IP, l'impostazione è sicura. MultiSubnetFailover non è supportata quando ti connetti a un'istanza nominata, tramite un protocollo diverso dal TCP, o a un'istanza configurata con più di 64 indirizzi IP. Non puoi nemmeno usarlo con il mirroring del database, che è obsoleto in tutte le versioni supportate di SQL Server. Usare invece Gruppi di disponibilità Always On. Per ulteriori informazioni, vedere Alta disponibilità e ripristino di emergenza e Disabilitare la risoluzione IP di rete trasparente.

Se il target è database SQL di Azure serverless con auto-pausa attivata, aumenta ConnectTimeout a almeno 60 secondi. Un database in pausa automatica riprende al primo Open(), e questo primo Open() può fallire con errore 40613 mentre il database riprende. L'errore 40613 è nella lista di errori transitori integrata, quindi openRetry riprova. I timeout sul lato client si manifestano come errori -2, che non rientrano in quell'elenco, quindi openRetry non riuscirà a recuperare un Open() che va in timeout durante la ripresa. Il singolo tentativo di connessione deve essere sufficientemente lungo da consentire la ripresa. Per ulteriori informazioni, vedi Pausa automatica e ripresa automatica.

Per ogni comando, spetta al chiamante decidere se effettuare un nuovo tentativo. Collega commandRetry a SqlCommand.RetryLogicProvider solo quando rieseguire il comando è sicuro: letture, MERGE protette da una chiave naturale, operazioni di upsert tramite una procedura archiviata e altre operazioni idempotenti. Il provider di comandi integrato non esegue nuovi tentativi quando è attiva una transazione, quindi le transazioni con più istruzioni devono essere ritentate dal codice dell'applicazione che può riaprire la transazione. L'impostazione TransientErrors sostituisce l'elenco degli errori integrato del driver; per estendere invece la baseline integrata, utilizzare SqlConfigurableRetryFactory.BaselineTransientErrors (Microsoft.Data.SqlClient 7.0 e versioni successive).

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

• Stringhe di connessione
• Autenticazione Microsoft Entra
• Crittografia e convalida di certificati
• Logica di ripetizione dei tentativi configurabile
• Disponibilità elevata e ripristino di emergenza

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. Imposta Encrypt=Strict per la crittografia TDS 8.0 su Microsoft.Data.SqlClient 5.0 e versioni 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 integrata di Windows 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 massiva: inserimenti ad alta velocità con SqlBulkCopy.
• Resilienza della connessione: nuovi tentativi di connessione integrati (ConnectRetryCount e ConnectRetryInterval), oltre a una logica di nuovo tentativo configurabile e attivabile opzionalmente 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

Configurazione e connessione

Autenticazione e sicurezza

Recupero e aggiornamento dei dati

Tipi di dati

Affidabilità e diagnostica

Caratteristiche di SQL Server

Informazioni di riferimento e risorse

Contenuti correlati

• Microsoft. Data.SqlClient su GitHub
• Microsoft. Data.SqlClient su NuGet
• Note di rilascio
• Panoramica di ADO.NET
• Moduli di connessione per Microsoft SQL Database