Opzioni di AppContext in SqlClient

Si applica a: .NET Framework .NET .NET Standard

Scarica ADO.NET

La classe AppContext consente a SqlClient di fornire nuove funzionalità continuando a supportare i chiamanti che dipendono dal comportamento precedente. Gli utenti possono rifiutare esplicitamente una modifica di comportamento impostando opzioni di AppContext specifiche.

Abilitare MultiSubnetFailover per impostazione predefinita

Si applica a: .NET Framework; .NET; .NET Standard

(Disponibile a partire dalla versione 7.0)

Per impostare MultiSubnetFailover=true a livello globale senza modificare singole stringhe di connessione, è possibile impostare l'opzione AppContext "Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault" su true all'avvio dell'applicazione:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault", true);

È anche possibile abilitare questa opzione in App.Config:

<runtime>
  <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault=true" />
</runtime>

Se abilitata, tutte le connessioni si comportano come se MultiSubnetFailover=true fosse impostata nella stringa di connessione. Questa opzione è disabilitata per impostazione predefinita.

Abilitare il multiplexing dei pacchetti per le letture asincrone

Si applica a: .NET Framework; .NET; .NET Standard

(Disponibile a partire dalla versione 7.0)

Il multiplexing dei pacchetti migliora le prestazioni per operazioni di lettura asincrone di grandi dimensioni, ad ExecuteReaderAsync esempio con set di risultati di grandi dimensioni, scenari di streaming o recupero di dati in blocco. Questa funzionalità è controllata da due interruttori opt-in AppContext. L'impostazione di entrambe le opzioni su false consente il nuovo percorso di elaborazione asincrono:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityAsyncBehaviour", false);
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityProcessSni", false);

Per impostazione predefinita, entrambe le opzioni sono true, che mantiene il comportamento esistente (compatibile).

Abilitare l'estensione della funzionalità Agente utente

Si applica a: .NET Framework; .NET; .NET Standard

(Disponibile a partire dalla versione 7.0)

Quando l'opzione AppContext "Switch.Microsoft.Data.SqlClient.EnableUserAgent" è abilitata, il driver invia i dettagli dell'agente utente al server come parte della connessione. Queste informazioni consentono di risolvere i problemi e quantificare l'utilizzo dei driver in base alla versione e al sistema operativo. Questa opzione è disabilitata per impostazione predefinita. Per abilitarla, impostare l'opzione AppContext su true all'avvio dell'applicazione:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableUserAgent", true);

Abilitazione del comportamento di troncamento decimale

Si applica a: .NET Framework; .NET; .NET Standard

A partire da Microsoft.Data.SqlClient 2.0, i dati decimali vengono arrotondati per impostazione predefinita, come avviene in SQL Server. Per abilitare il comportamento di troncamento precedente, è possibile impostare l'opzione di AppContext "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal" su true all'avvio dell'applicazione:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);

Abilitazione di reti gestite in Windows

Si applica a: .NET; .NET Standard

Disponibile solo a partire dalla versione 2.0.

In Windows SqlClient usa un'implementazione nativa dell'interfaccia di rete SNI per impostazione predefinita. Per abilitare l'uso dell'implementazione di SNI gestita, è possibile impostare l'opzione di AppContext "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows" su true all'avvio dell'applicazione:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);

Questa opzione attiva o disattiva il comportamento del driver in modo da usare un'implementazione di rete gestita in progetti .NET Core 2.1+ e .NET Standard 2.0+ in Windows, eliminando tutte le dipendenze dalle librerie native per la libreria Microsoft.Data.SqlClient. Questa opzione viene usata solo per scopi di test e debug.

Nota

Esistono alcune differenze note rispetto all'implementazione nativa. Ad esempio, l'implementazione gestita non supporta l'autenticazione Windows non di dominio.

Disattivazione della risoluzione trasparente dell'IP di rete

Si applica a: .NET Framework

La Risoluzione Trasparente dell'IP di Rete (TNIR) è una revisione della funzionalità MultiSubnetFailover esistente. TNIR influisce sulla sequenza di connessione del driver nel caso in cui il primo IP risolto del nome host non risponda e al nome host siano associati più IP. La combinazione di TransparentNetworkIPResolution e MultiSubnetFailover seleziona la sequenza di connessione:

TransparentNetworkIPResolution	MultiSubnetFailover	Sequenza di connessione
Vero	Vero	TransparentNetworkIPResolution viene ignorato. Il driver tenta in parallelo gli indirizzi IP risolti dal DNS e completa l'autenticazione con il primo host che risponde.
Vero	Falso	Il driver esegue più cicli di connessione sugli indirizzi IP risolti tramite DNS, con un minimo di 500 millisecondi per il primo tentativo e timeout per tentativo via via più lunghi, finché non viene stabilita una connessione o non viene raggiunto il valore complessivo di Connect Timeout.
Falso	Vero	Il driver tenta in parallelo gli indirizzi IP restituiti dalla risoluzione DNS e completa l'autenticazione con il primo che risponde.
Falso	Falso	Il driver tenta ciascun indirizzo IP risolto dal DNS in sequenza finché uno non va a buon fine o finché non viene raggiunto Connect Timeout.

TransparentNetworkIPResolutionè abilitato di default su .NET Framework, ed MultiSubnetFailover è disabilitato di default. Su .NET 5 e versioni successive, TransparentNetworkIPResolution non è una parola chiave di connessione riconosciuta e impostandola (con qualsiasi valore) viene ArgumentException lanciata (KeywordNotSupported). Quelle versioni supportano solo MultiSubnetFailover. Il resto di questa sezione (l'override automatico, le modalità di guasto nell'avviso seguente e l'interruttore AppContext) si applica al .NET Framework.

Tip

Imposta MultiSubnetFailover=True su ogni stringa di connessione, indipendentemente dalla versione di .NET o dal fatto che la destinazione sia Azure SQL o SQL Server locale. MultiSubnetFailover=True seleziona un percorso di codice parallel-connect che trova rapidamente la prima replica responsiva. In .NET Framework, aggira anche il ciclo sequenziale di nuovi tentativi per ogni IP di TNIR, che è una causa comune di lunghi ritardi di connessione e di timeout dell’handshake di preautenticazione.

Su .NET Framework, quando TransparentNetworkIPResolution non è specificato nella stringa di connessione, il driver disabilita automaticamente TNIR quando la sorgente dati è un endpoint Azure SQL riconosciuto, quando la Authentication chiave è impostata su qualsiasi metodo Microsoft Entra ID (Active Directory Password, Active Directory Integrated, Active Directory Interactive, Active Directory Service PrincipalActive Directory Device Code Flow, , Active Directory Managed Identity, Active Directory MSI, Active Directory DefaultActive Directory Workload Identityo ), oppure quando la SqlConnection.AccessToken proprietà è impostata. Per i suffissi endpoint riconosciuti dal driver, vedi la TransparentNetworkIPResolution voce in SqlConnection.ConnectionString.

Un valore esplicito TransparentNetworkIPResolution bypassa questo comportamento automatico: True abilita il TNIR e False disabilita il TNIR incondizionatamente. Per ripristinare il comportamento automatico, rimuovi la parola chiave dalla stringa di connessione. La sostituzione automatica non si applica nemmeno quando la stringa di connessione fa riferimento ad Azure SQL tramite un CNAME personalizzato o un nome DNS personalizzato il cui suffisso non è riconosciuto come endpoint di Azure SQL. L'override automatico mira specificamente a Azure SQL; non si attiva per SQL Server on-premise, quindi TNIR è attivato di default lì.

Lunghi ritardi di connessione su .NET Framework

In .NET Framework, TransparentNetworkIPResolution=True (il valore predefinito) può causare lunghi ritardi di connessione e timeout dell'handshake di preautenticazione ogni volta che il nome DNS di destinazione viene risolto in più indirizzi IP e uno dei primi indirizzi IP non è integro, è obsoleto o irraggiungibile. TNIR prova gli IP risolti in sequenza e aumenta il timeout per tentativo a ogni round fino a raggiungere il totale Connect Timeout . Tipicamente si osserva un ritardo di connessione inaspettatamente lungo che termina con questo errore:

Connection Timeout Expired.  The timeout period elapsed while attempting to consume the pre-authentication handshake acknowledgement.  This could be because the pre-authentication handshake failed or the server was unable to respond back in time.

Questo schema si presenta in diverse topologie:

• database SQL di Azure, Istanza gestita di SQL di Azure o SQL Database in Microsoft Fabric. Il gateway Azure SQL instrada ogni autenticazione verso una replica backend. Quando una connessione instradata non riesce, TNIR ritenta il backend instradato senza tornare al gateway per un nuovo instradamento, prolungando il ritardo durante il failover del backend.
• SQL Server on-premises posto dietro un listener di un gruppo di disponibilità Always On il cui nome DNS si risolve in più indirizzi IP delle repliche. Una voce DNS obsoleta o una replica IP non sana viene testata sequenzialmente prima che TNIR raggiunga una replica funzionante.
• Istanze del cluster di failover con un listener di cluster multisubnet, o qualsiasi altra configurazione in cui il nome DNS di destinazione contiene più record A/AAAA (ad esempio DNS round-robin).

Per evitare questo comportamento, imposta MultiSubnetFailover=True nella stringa di connessione:

MultiSubnetFailover=True

Questa raccomandazione vale su ogni versione .NET e copre sia Azure SQL che SQL Server on-premise. Quando MultiSubnetFailover=True, il driver ignora TransparentNetworkIPResolution, tenta in parallelo gli indirizzi IP risolti dal DNS, e completa l'autenticazione con la prima replica responsiva. Nonostante il nome, MultiSubnetFailover si applica a qualsiasi ascoltatore il cui nome DNS si risolve su più IP target, indipendentemente dal fatto che quegli IP siano in subnet diverse, ed è sicuro su server stand-alone il cui DNS si risolve su un singolo IP.

Per un controllo dell'intero processo senza modificare ogni stringa di connessione, usa l'opzione AppContext Abilita MultiSubnetFailover per impostazione predefinita.

Disabilitare TNIR tramite un'opzione AppContext

Per invertire il valore predefinito di TransparentNetworkIPResolution da true a false su .NET Framework, imposta l'interruttore Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString AppContext su true all'avvio dell'applicazione. Questo switch cambia il valore predefinito solo quando TransparentNetworkIPResolution non è nella stringa di connessione; non sovrascrive un valore esplicito.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString", true);

Per altre informazioni sull'impostazione di queste proprietà, vedere la documentazione per la proprietà SqlConnection.ConnectionString.

Abilitazione di un timeout minimo durante l'accesso

Si applica a: .NET Framework; .NET; .NET Standard

Per impedire a un tentativo di accesso di attendere indefinitamente, è possibile impostare l'opzione di AppContext "Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin" su true all'avvio dell'applicazione:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin", false);

Disabilitazione del comportamento di blocco di ReadAsync

Si applica a: .NET Framework; .NET; .NET Standard

A partire dalla versione 3.0, ReadAsync viene eseguito in modo asincrono. Le versioni precedenti eseguono ReadAsync in modo sincrono e bloccano il thread chiamante nel .NET Framework. Per controllare questo comportamento di blocco, è possibile impostare l'opzione di AppContext "Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking" su true o false all'avvio dell'applicazione:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking", false);

Abilitazione del comportamento null di rowversion

Si applica a: .NET Framework; .NET; .NET Standard

A partire dalla versione 3.0, quando un elemento rowversion ha valore null, SqlDataReader restituisce un valore DBNull anziché un oggetto byte[] vuoto. Per abilitare il comportamento predefinito al fine di restituire un byte[] vuoto, abilitare l'opzione AppContext Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior all'avvio dell'applicazione.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior", true);

Eliminare gli avvisi TLS non sicuri

Si applica a: .NET Framework; .NET; .NET Standard

Disponibile solo a partire dalla versione 4.0.1.

Quando si usa Encrypt=false nella stringa di connessione, viene visualizzato un avviso di sicurezza nella console se la versione TLS è 1.2 o inferiore. Questo avviso può essere eliminato abilitando l'opzione AppContext seguente all'avvio dell'applicazione:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning", true);

Ignora il partner di failover fornito dal server

Si applica a: .NET Framework; .NET; .NET Standard

(Disponibile a partire dalle versioni 5.1.8, 6.0.4 e 6.1.3)

In caso di failover, le informazioni sul partner di failover fornite dal server sono preferibili rispetto alle informazioni sul partner di failover fornite nella stringa di connessione. Per ignorare le informazioni del partner di failover fornite dal server e prendere in considerazione solo le informazioni sul partner di failover fornite nella stringa di connessione, abilitare l'opzione AppContext all'avvio dell'applicazione:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.IgnoreServerProvidedFailoverPartner", true);

Contenuti correlati

• Classe AppContext