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 di codice presuppone un progetto destinato a .NET 8 o versioni successive e fa riferimento ai pacchetti Microsoft.Data.SqlClient e Microsoft.Data.SqlClient.Extensions.Azure 7.1.2. 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 di 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 abilitate 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 dove è 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 a funzionare, evitando il lento percorso sequenziale per 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 riprova a qualificare i guasti transitori durante Open(), e riconnette una connessione idle 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 intorno 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.
  • Pausa automatica serverless: per database SQL di Azure serverless, alza ConnectTimeout a 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 la riproduzione del comando è sicura: letture, MERGE protetta da una chiave naturale, operazioni di upsert tramite una stored procedure 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 riprovano solo gli errori restituiti prima dell'inizio del primo set di risultati. ExecuteNonQuery riprova l'intera chiamata.
  • Elenco errori transitori: L'impostazione TransientErrors sostituisce l'elenco integrato. Per estenderlo, usa SqlConfigurableRetryFactory.BaselineTransientErrors invece (Microsoft. Data.SqlClient 7.0 e versioni successive).
  • Retrying Evento: Retrying Si attiva prima di ogni nuovo tentativo con il conteggio dei ritentativi, il ritardo successivo e le eccezioni finora. Instradalo verso ILogger o verso la tua pipeline di telemetria.
  • Eccezioni: Il metodo non intercetta le 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: 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: lo snippet crea i provider di retry a ogni chiamata per rimanere autonomo. 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 una forma di 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 procedure memorizzate per utilizzare parametri di output e valori di ritorno.
  5. Utilizza programmazione asincrona e cancellazione per aggiungere cancellazione del chiamante e timeout limitati.
  6. Gestisci errori e messaggi prima di aggiungere tentativi 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.
  • Crittografate di default: connessioni crittografate TLS con Encrypt=true come predefinita. Impostare Encrypt=Strict per la crittografia TDS 8.0.
  • Autenticazione Microsoft Entra ID: Connessioni senza password con flussi di identità gestita, entità servizio, interattivi, integrati, catena di credenziali predefinita e token di accesso.
  • Kerberos e NTLM: autenticazione di Windows per Active Directory locale e scenari legacy.
  • Always Encrypted: crittografia lato client per colonne sensibili, con enclave sicure opzionali per operazioni in loco.
  • Copia in blocco: inserimenti ad alta velocità con SqlBulkCopy.
  • Pooling delle connessioni: Attivato di default. Un pool V2 opt-in è in fase di valutazione.
  • Resilienza delle connessioni: tentativi di connessione integrati (ConnectRetryCount e ConnectRetryInterval) più logica di ritentativo configurabile opzionale per connessioni e comandi.
  • Tipi di dati SQL Server avanzati: datetimeoffset, sql_variant, JSON, vettoriali, spaziali, XML e parametri con valori di tabella.
  • Diagnostica: tracciamento della sorgente 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.
namespace Microsoft.Data.SqlClient e compatibilità Comprendi come SqlClient implementa ADO.NET e la sua compatibilità con System.Data.SqlClient, .NET e SQL Server.
Novità di Microsoft.Data.SqlClient Trova le uscite attuali, i principali cambiamenti di aggiornamento e le note di rilascio a monte.

Configurazione e connessione

Article Description
Connettiti a una fonte 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 validazione dei certificati Configurare connessioni criptate e validazione dei certificati server.
Pooling delle connessioni SQL Server Riutilizza le connessioni fisiche in modo efficiente.
Gestisci 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.
Proteggi le informazioni di connessione Tieni le credenziali e le impostazioni di connessione fuori dal codice dell'applicazione.
Always Encrypted Proteggere i valori sensibili delle colonne dal sistema di database.
Always Encrypted with secure enclaves 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.
DataAdapters e DataReaders 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.
Trasmettere 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.
Recupera le informazioni dello schema del database Scopri le collezioni di schemi e le restrizioni.
Operazioni di copia in massa Caricare grandi set di dati in modo efficiente con SqlBulkCopy.
Parametri a valore di tabella Invia più righe a un'istruzione parametrizzata o a una procedura memorizzata.
Set di risultati attivi multipli (MARS) 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 grandi dimensioni Trasmetti e aggiorna dati binari, FILESTREAM e di grande valore.

Affidabilità e diagnostica

Article Description
Logica di retry configurabile Riprova i fallimenti di connessione e comando transitori con policy limitate.
Alta disponibilità e disaster recovery Connettiti con ascoltatori di gruppi di disponibilità e partner di failover.
Contatori eventi in SqlClient Monitora le connessioni attive, le connessioni del pool e altre metriche dei driver.
Abilita il tracciamento dell'origine eventi 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 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.
LocalDB Connettiti alle istanze LocalDB di SQL Server Express.
Scoperta e classificazione dei dati Leggi i metadati di classificazione della sensibilità dai set di risultati.

Informazioni di riferimento e risorse

Article Description
Riferimento API di Microsoft.Data.SqlClient Consulta il riferimento API .NET per il driver.
Opzioni 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 GitHub del runtime .NET Leggi il sorgente delle librerie runtime .NET.

Richiedere una funzionalità

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