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. Fornisce connessioni, comandi, elaborazione dei risultati, transazioni, copia in massa e funzionalità specifiche per SQL Server alle 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 del server e del database da IConfiguration, quindi i valori provengono dai provider di configurazione che l'host collega, come appsettings.json, variabili di ambiente, Configurazione app di Azure e impostazioni supportate da Key Vault. La configurazione combina queste caratteristiche:

  • Sicurezza del Livello di Trasporto (TLS).
  • Identità gestita.
  • Resilienza della connessione inattiva.
  • Ritentazione di connessione iniziale tramite logica di ritentazione configurabile (CRL), con logging strutturato.
  • Ritentazione a livello di comando per errori transitori che si verificano a metà della query.
  • Ripristino rapido del gruppo di failover.
  • Chiamate asincrone che accettano un token di cancellazione.

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à.

Il frammento presuppone un progetto che mira a versioni .NET 8 o successive e fa riferimento ai pacchetti Microsoft.Data.SqlClient e Microsoft.Data.SqlClient.Extensions.Azure 7.1.1. L'host, come il .NET Generic Host o ASP.NET Core, fornisce il ILogger e il IConfiguration, e la configurazione fornisce il nome del server in Sql:Server e il nome del database in 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;
}

Il metodo restituisce il nome del database a cui è connesso e scrive nel log Connected to database <database>. Quando avviene un nuovo tentativo, viene anche registrato un avviso per ogni tentativo, con l'eccezione che lo ha attivato.

Come funziona ogni parte del frammento:

  • Target: Qualsiasi endpoint SQL motore di database configurato per l'autenticazione Microsoft Entra: database SQL di Azure, Istanza gestita di SQL di Azure, database SQL in Microsoft Fabric, e SQL Server 2022 e versioni successive su Macchine virtuali di Azure o abilitato da Azure Arc.
  • Encrypt = SqlConnectionEncryptOption.Strict: Seleziona la crittografia TDS 8.0. Richiede SQL Server 2022 e versioni successive, database SQL di Azure, Istanza gestita di SQL di Azure o database SQL in Microsoft Fabric. Usa SqlConnectionEncryptOption.Mandatory per server più vecchi.
  • ActiveDirectoryManagedIdentity: Funziona solo quando è disponibile un'identità gestita, come Servizio app di Azure, Funzioni di Azure o una macchina virtuale Azure. Per lo sviluppo locale, usa SqlAuthenticationMethod.ActiveDirectoryDefault, che prova la interfaccia della riga di comando di Azure, il login di Visual Studio e altre fonti di credenziali. Non usarlo in produzione perché sondare ogni sorgente rallenta la connessione. Per maggiori informazioni, vedi Usa l'autenticazione predefinita.
  • MultiSubnetFailover = true: Tenta connessioni TCP a tutti gli indirizzi IP risolti in parallelo e utilizza la prima connessione che riesce, evitando la lenta scansione sequenziale degli IP. Impostalo per 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. È sicuro su target con un solo IP. Non è supportata per istanze nominate, protocolli diversi da TCP, istanze con più di 64 indirizzi IP, o mirroring del database, che è obsoleto. 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.
  • ConnectRetryCount = 3 e ConnectRetryInterval = 10: Il driver ritenta gli errori transitori idonei durante Open(), e riconnette una connessione inattiva interrotta al comando successivo. Il conteggio predefinito è 1. Tre tentativi a distanza di 10 secondi durano più a lungo di una riconfigurazione più lunga o di un failover più lungo. Il driver porta 1 a 2 solo quando il nome del server termina in un dominio Azure SQL noto, come .database.windows.net, quindi un alias DNS personalizzato rimane a 1.
  • openRetry: Assegnato a SqlConnection.RetryLogicProvider, aggiunge un backoff esponenziale attorno a Open(). Il driver interrompe i suoi tentativi interni quando ConnectTimeout scade, quindi il peggior caso prima che OpenAsync generi un'eccezione è di cinque tentativi fino a 30 secondi ciascuno, più il backoff. Ogni tentativo di riconnessione inattiva esegue anche l'intero openRetry criterio, e quando questo criterio esaurisce i suoi tentativi, il recupero inattivo termina.
  • Auto-pausa serverless: Per database SQL di Azure serverless, imposta ConnectTimeout ad almeno 60 secondi. Il primo Open() può fallire con errore 40613 mentre il database riprende a funzionare e openRetry riprova. Un timeout lato client appare come errore -2, che non viene ritentato, quindi ogni tentativo di connessione deve durare più della ripresa. Per ulteriori informazioni, vedi Pausa automatica e ripresa automatica.
  • commandRetry: Collegalo a SqlCommand.RetryLogicProvider solo quando riprodurre il comando è sicuro: letture, MERGE protetto da una chiave naturale, operazioni di upsert tramite una procedura memorizzata e altre operazioni idempotenti. Salta il ritentativo all'interno di una transazione, quindi il codice applicativo deve riprovare le transazioni multi-statement. ExecuteReader e ExecuteScalar ritentano solo gli errori restituiti prima che inizi il primo set di risultati. ExecuteNonQuery ritenta l'intera chiamata.
  • Lista errori transitori: l'impostazione TransientErrors sostituisce la lista integrata. Per estenderlo, usa SqlConfigurableRetryFactory.BaselineTransientErrors invece (Microsoft. Data.SqlClient 7.0 e versioni successive).
  • Retrying Evento: Retrying si attiva prima di ogni ritentativo con il conteggio dei ritenti, il ritardo successivo e le eccezioni finora. Instradalo verso ILogger o verso la tua pipeline di telemetria.
  • Eccezioni: Il metodo non cattura eccezioni. Un provider esaurito genera AggregateException con l'eccezione di ciascun tentativo. Un errore non transitorio si propaga come eccezione originale. Il chiamante lo registra una volta insieme al resto del contesto della richiesta.
  • Cancellazione: Il CancellationToken interrompe l'attesa del fornitore tra un tentativo e l'altro. Non interrompe l'attesa del conducente ConnectRetryInterval durante un singolo Open tentativo. Per maggiori informazioni, vedi Programmazione asincrona.
  • Durata del provider: Il snippet crea i provider di retry ad ogni chiamata per rimanere autonomi. In un'applicazione, createli una volta e riutilizzateli.

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

Impara i compiti principali di accesso ai dati

Dopo esserti connesso, usa questi articoli in ordine:

  1. Esegui un comando per scegliere un formato del risultato ed eseguire Transact-SQL (T-SQL).
  2. Configura i parametri per corrispondere al contratto del database.
  3. Recupera i dati con SqlDataReader per elaborare righe e risultati multipli.
  4. Modifica i dati con stored procedure per utilizzare parametri di output e valori restituiti.
  5. Usa la programmazione asincrona e l'annullamento per aggiungere l'annullamento del chiamante e timeout limitati.
  6. Gestisci errori e messaggi prima di aggiungere retentativi o diagnostiche di produzione.

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. Impostare Encrypt=Strict per la crittografia TDS 8.0.
  • 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.
  • Pooling di connessioni: attivato di default. Un pool V2 opt-in è in fase di valutazione.
  • 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.
  • Identità dell'applicazione: Imposta SqlConnection.RegisteredApplication per identificare la tua libreria o strumento su SQL Server (Microsoft. Data.SqlClient 7.1 e versioni successive).

Get started

Article Description
Inizia con il driver SqlClient Configura un progetto, crea un database, connetti, interroga e aggiungi resilienza alla connessione.
Installare, aggiornare e distribuire Microsoft. Data.SqlClient Installa i pacchetti NuGet, scegli una versione, aggiorna il driver e prepara l'output del deployment.
Ciclo di vita del supporto Rivedi le versioni dei driver supportati e le date di supporto.
Migra da System.Data.SqlClient a Microsoft. Data.SqlClient Aggiornare i riferimenti dei pacchetti, i namespace, la configurazione e modificare il comportamento dei driver.
Spazio dei nomi Microsoft.Data.SqlClient e compatibilità Comprendi come SqlClient implementa ADO.NET e la sua compatibilità con System.Data.SqlClient, .NET e SQL Server.
Novità in Microsoft. Data.SqlClient Trova le uscite attuali, i principali cambiamenti di aggiornamento e le note di rilascio a monte.

Configurazione e connessione

Article Description
Connessione a un'origine dati Apri e gestisci le connessioni, e rispondi ai cambiamenti dello stato della connessione.
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.
Gestire errori e messaggi Rileva errori e ricevi messaggi informativi.

Autenticazione e sicurezza

Article Description
Migliori pratiche di sicurezza per Microsoft.Data.SqlClient Esamina le linee guida sull'autenticazione, l'autorizzazione e la sicurezza delle applicazioni.
Autenticazione Microsoft Entra Connettiti usando identità gestita, service 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 avanzate su dati crittografati con un'enclave sicura.

Recupero e aggiornamento dei dati

Article Description
Esegui un comando Eseguire istruzioni SQL parametrizzate e procedure memorizzate.
DataAdapter e DataReader Trasmettere set di risultati o popolare strutture di dati disconnesse.
Esegui più comandi con SqlBatch Invia una raccolta ordinata di comandi e elabora i loro risultati.
Dati in streaming Trasferire valori grandi di binari, testo, XML e JSON senza bufferare il valore completo.
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.
MARS (Multiple Active Result Sets) Intercalare più lotti su una sola connessione.

Tipi di dati

Article Description
Mappatura dei tipi di dati di SQL Server Mappare i tipi di SQL Server nei tipi .NET e System.Data.SqlTypes.
Dati JSON Invia e recupera il tipo di dato json di SQL Server.
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 degli eventi in SqlClient Monitora le connessioni attive, le connessioni del pool e altre metriche dei driver.
Abilita il tracciamento dell'origine evento Registra eventi dettagliati dei conducenti per la diagnosi.
Guida alla risoluzione dei problemi di SqlClient Individua i problemi comuni di connessione e dei driver.
Notifiche delle 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
Informazioni di riferimento sulle API Microsoft.Data.SqlClient Consulta il riferimento API .NET per il driver.
switch di AppContext Configura compatibilità e comportamento di sicurezza.
repository GitHub di Microsoft.Data.SqlClient Leggi il codice sorgente del driver, le note di rilascio e gli esempi.
Esempi di Microsoft.Data.SqlClient Consulta gli esempi di C# per le API dei driver.
Repository .NET runtime GitHub Leggi il sorgente delle librerie runtime .NET.

Richiedere una funzionalità

Per richiedere una funzionalità, apri un problema nel repository Microsoft. Data.SqlClient GitHub.

Contenuti correlati

  • Ultimo aggiornamento: