Přepínače AppContext v SqlClient

Platí pro: .NET Framework .NET Standard

Stáhnout ADO.NET

Třída AppContext umožňuje SqlClient poskytovat nové funkce a zároveň pokračovat v podpoře volajících, kteří závisejí na předchozím chování. Uživatelé se můžou odhlásit ze změny chování nastavením konkrétních přepínačů AppContext.

SqlClient při prvním použití tohoto switche čte a ukládá do cache. Nastavte spínače při spuštění aplikace, než použijete jakýkoli typ SqlClient. Změna switche poté, co SqlClient uloží jeho hodnotu do mezipaměti, nemá žádný efekt.

Povolení funkce MultiSubnetFailover ve výchozím nastavení

Platí pro: .NET Framework; .NET; .NET Standard

(K dispozici od verze 7.0)

Chcete-li nastavit MultiSubnetFailover=true globálně bez úpravy jednotlivých připojovacích řetězců, nastavte při spuštění aplikace přepínač AppContext Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault na true:

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

Tento přepínač můžete také povolit ve službě App.Config:

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

Pokud je tato možnost povolená, chovají se všechna připojení, jako by bylo v připojovacím řetězci nastaveno MultiSubnetFailover=true. Tento přepínač je ve výchozím nastavení zakázaný.

Povolení multiplexování paketů pro asynchronní čtení

Platí pro: .NET Framework; .NET; .NET Standard

(K dispozici od verze 7.0)

Multiplexování paketů zlepšuje výkon u rozsáhlých asynchronních operací čtení, jako je ExecuteReaderAsync s velkými sadami výsledků, při scénářích streamování nebo hromadném načítání dat. Tato funkce je řízená dvěma přepínači AppContext pro výslovný souhlas. Nastavením obou přepínačů false povolíte novou cestu asynchronního zpracování:

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

Ve výchozím nastavení jsou oba přepínače true, což zachovává stávající (kompatibilní) chování.

Povolit oříznutí desetinných míst

Platí pro: .NET Framework; .NET; .NET Standard

Počínaje Microsoft.Data.SqlClient 2.0 se desetinná data ve výchozím nastavení zaokrouhlují, jak to dělá SQL Server. Chcete-li povolit předchozí chování zkracování, můžete při spuštění aplikace nastavit přepínač AppContext Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal na true:

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

Povolení spravovaných sítí ve Windows

Týká se: .NET; .NET Standard

(Dostupné od verze 2.0)

Ve Windows sqlClient ve výchozím nastavení používá nativní implementaci síťového rozhraní SNI. Chcete-li povolit použití spravované implementace SNI, nastavte při spuštění aplikace přepínač AppContext Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows na true:

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

Tento přepínač přepne chování ovladače tak, aby používal spravovanou síťovou implementaci v projektech .NET Core 2.1+ a .NET Standard 2.0+ ve Windows a eliminuje všechny závislosti na nativních knihovnách knihovny Microsoft.Data.SqlClient. Slouží pouze pro účely testování a ladění.

Poznámka:

V porovnání s nativní implementací existují některé známé rozdíly. Například spravovaná implementace nepodporuje nedoménové Windows Authentication.

Vypnout transparentní síťové IP rozlišení

Platí pro: .NET Framework

Transparentní řešení síťových IP adres (TNIR) je revize stávající funkce MultiSubnetFailover. TNIR ovlivňuje posloupnost připojení ovladače v případě, že první vyřešená IP adresa názvu hostitele nereaguje a k názvu hostitele je přidružených více IP adres. Kombinace TransparentNetworkIPResolution a MultiSubnetFailover vybírá sekvenci spojení:

TransparentníŘešeníSítěIP	MultiSubnetFailover	Pořadí připojení
Pravdivé	Pravdivé	Vlastnost TransparentNetworkIPResolution je ignorována. Ovladač se pokusí paralelně zpracovat DNS IP adresy a dokončí autentizaci s prvním zasahujícím operátorem.
Pravdivé	Nepravda	Ovladač provádí několik kol pokusů o připojení napříč IP adresami přeloženými pomocí DNS, s minimem 500 milisekund při prvním pokusu a postupně se prodlužujícími časovými limity pro jednotlivé pokusy, dokud se připojení nezdaří nebo není dosaženo celkového limitu Connect Timeout.
Nepravda	Pravdivé	Ovladač se pokusí paralelně zpracovat DNS IP adresy a dokončí autentizaci s prvním zasahujícím operátorem.
Nepravda	Nepravda	Ovladač se postupně pokouší o každou IP adresu přeloženou pomocí DNS, dokud se to u jedné z nich nepodaří nebo není dosaženo hodnoty Connect Timeout.

TransparentNetworkIPResolutionje ve výchozím nastavení povolena ve .NET Frameworku a MultiSubnetFailover ve výchozím nastavení je deaktivována. TransparentNetworkIPResolution v .NET 5 a novějších verzích není rozpoznaným klíčovým slovem připojovacího řetězce a jeho nastavení (na libovolnou hodnotu) vyvolá ArgumentException (KeywordNotSupported). Tyto verze podporují pouze MultiSubnetFailover. Zbytek této části (automatické přepsání nastavení, režimy selhání popsané v následujícím upozornění a přepínač AppContext) se týká rozhraní .NET Framework.

Tip

Nastavte MultiSubnetFailover=True na každý připojovací řetězec, bez ohledu na verzi .NET nebo zda je cílem Azure SQL nebo on-premises SQL Server. MultiSubnetFailover=True vybere paralelní cestu kódu, která rychle najde první responzivní repliku. V prostředí .NET Framework také obchází sekvenční smyčku opakovaných pokusů TNIR pro jednotlivé IP adresy, která je častou příčinou dlouhých prodlev při připojování a časových limitů handshake před ověřením.

V .NET Framework platí, že pokud v připojovacím řetězci není zadáno TransparentNetworkIPResolution, ovladač automaticky zakáže TNIR, když je zdrojem dat rozpoznaný koncový bod Azure SQL, když je klíč Authentication nastaven na libovolnou metodu Microsoft Entra ID (služba Active Directory Password, služba Active Directory Integrated, služba Active Directory Interactive, služba Active Directory Service Principal, služba Active Directory Device Code Flow, služba Active Directory Managed Identity, služba Active Directory MSI, služba Active Directory Default nebo služba Active Directory Workload Identity) nebo když je nastavena vlastnost SqlConnection.AccessToken. Pro koncové přípony, které ovladač rozpoznává, viz TransparentNetworkIPResolution záznam v SqlConnection.ConnectionString.

Explicitní TransparentNetworkIPResolution hodnota obchází toto automatické chování: True aktivuje TNIR a False TNIR bezpodmínečně deaktivuje. Pro obnovení automatického chování odstraňte klíčové slovo z připojovací řetězec. Automatické přepsání se také nepoužije, když připojovací řetězec odkazuje na Azure SQL prostřednictvím vlastního záznamu CNAME nebo vlastního názvu DNS, jehož přípona není rozpoznána jako koncový bod Azure SQL. Automatické přepsání se týká konkrétně Azure SQL; pro místní nasazení SQL Serveru se neuplatňuje, takže TNIR je tam ve výchozím nastavení povolený.

Dlouhé zpoždění připojení v .NET Frameworku

V rozhraní .NET Framework může TransparentNetworkIPResolution=True (výchozí nastavení) způsobit dlouhé prodlevy při připojování a časové limity při předautentizačním navazování spojení vždy, když se cílový název DNS přeloží na více IP adres a jedna z IP adres, které se vrátí dříve, je nefunkční, zastaralá nebo nedostupná. TNIR zkouší přeložené IP adresy postupně a v každém dalším kole zvyšuje časový limit pro každý pokus, dokud není dosaženo celkového časového limitu Connect Timeout. Obvykle pozorujete nečekaně dlouhé zpoždění připojení, které končí touto chybou:

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.

Vzor se objevuje v několika topologiích:

• Azure SQL Database, Azure SQL Managed Instance, nebo SQL database in Microsoft Fabric. Azure SQL gateway směruje každé ověření do backendové repliky. Když selže směrované spojení, TNIR znovu zkusí směrovaný backend bez návratu k bráně k přesměrování, což prodlužuje zpoždění během failoveru backendu.
• Místní SQL Server za naslouchačem skupiny dostupnosti Always On, jehož název DNS se překládá na více IP adres replik. Zastaralý DNS záznam nebo nezdravá replika IP se zkouší postupně před tím, než TNIR dosáhne funkční repliky.
• Instance clusteru pro failover s multi-subnet clusterovým listenerem nebo jakákoli jiná konfigurace, kde cílové DNS jméno má více A/AAAA záznamů (například DNS round-robin).

Abychom se tomuto chování vyhnuli, nastavte MultiSubnetFailover=True v připojovací řetězec:

MultiSubnetFailover=True

Toto doporučení funguje na každé verzi .NET a pokrývá jak Azure SQL, tak on-premises SQL Server. Když MultiSubnetFailover=True, ovladač ignoruje TransparentNetworkIPResolution, paralelně se pokusí připojit k IP adresám přeloženým službou DNS a dokončí ověřování s první odpovídající replikou. Navzdory názvu se MultiSubnetFailover vztahuje na každého posluchače, jehož název DNS se překládá na více cílových IP adres, bez ohledu na to, zda jsou tyto IP adresy v různých podsítích, a je bezpečné i pro samostatné servery, jejichž název DNS se překládá na jedinou IP adresu.

Pro řízení v rámci celého procesu bez úpravy každého připojovacího řetězce použijte přepínač AppContext Enable MultiSubnetFailover by default.

Vypněte TNIR pomocí přepínače AppContext

Chcete-li v rozhraní .NET Framework změnit výchozí hodnotu TransparentNetworkIPResolution z true na false, nastavte při spuštění aplikace přepínač AppContext Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString na true. Tento přepínač mění výchozí hodnotu pouze tehdy, když TransparentNetworkIPResolution není v připojovací řetězec; nepřepisuje explicitní hodnotu.

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

Další informace o nastavení těchto vlastností naleznete v dokumentaci sqlConnection.ConnectionString Vlastnost.

Vypněte minimální časový limit při přihlášení

Platí pro: .NET Framework; .NET; .NET Standard

Ve výchozím nastavení SqlClient uplatňuje minimální dobu jedné sekundy při výpočtu času dostupného pro pokus o přihlášení. Toto chování zabraňuje tomu, aby pokus o přihlášení čekal neomezeně dlouho, když se vypočítaný časový limit zaokrouhluje na nulu.

Pro obnovení staršího chování nastavte přepínač Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin AppContext na false při spuštění aplikace:

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

Zakázání blokujícího chování readAsync

Platí pro: .NET Framework; .NET; .NET Standard

Od verze 3.0 běží ReadAsync asynchronně. Předchozí verze běží ReadAsync synchronně a blokují volací vlákno v .NET Frameworku. Pro kontrolu tohoto blokovacího chování nastavte přepínač Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking AppContext na true nebo false při spuštění aplikace:

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

Povolit chování hodnoty NULL pro rowversion

Platí pro: .NET Framework; .NET; .NET Standard

Od verze 3.0, když má rowversion nulovou hodnotu, SqlDataReader vrací DBNull hodnotu místo prázdné byte[]. Chcete-li zachovat původní chování, kdy se vrací prázdné byte[], zapněte při spuštění aplikace přepínač AppContext Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior.

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

Potlačení nezabezpečeného upozornění protokolu TLS

Platí pro: .NET Framework; .NET; .NET Standard

(Dostupné od verze 4.0.1)

Při použití Encrypt=false v připojovací řetězec konzole vydá bezpečnostní varování, pokud je verze TLS 1.2 nebo nižší. Toto varování potlačte povolením následujícího přepínání AppContext při spuštění aplikace:

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

Ignorovat partnera pro převzetí služeb při selhání poskytnutého serverem

Platí pro: .NET Framework; .NET; .NET Standard

(Dostupné od verzí 5.1.8, 6.0.4 a 6.1.3)

Při převzetí služeb při selhání jsou informace o partnerovi převzetí služeb při selhání poskytované serverem upřednostňované před informacemi o partnerovi převzetí služeb při selhání poskytnuté v připojovacím řetězci. Pokud chcete ignorovat informace o partnerovi převzetí služeb při selhání poskytované serverem a zvažovat pouze informace o partnerovi převzetí služeb při selhání poskytnuté v připojovacím řetězci, povolte tento přepínač AppContext při startu aplikace:

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

Vynutit časový limit nečinnosti připojení

Platí pro: .NET Framework; .NET; .NET Standard

Od verze 7.1.0 klíčové slovo připojovacího řetězce Connection Idle Timeout a vlastnost SqlConnectionStringBuilder.IdleTimeout konfigurují kontroly nečinné expirace a čištění na pozadí pro sdružená připojení. Výchozí hodnota je 300 sekund. Záporné hodnoty házejí ArgumentException výjimku.

Nastavení switche a připojovací řetězec ovlivňují implementaci každého poolu odlišně:

• V1 pool. Když je přepínač true, V1 používá svůj historický náhodný dvou- až čtyřminutový úklidový rytmus a vyřazuje nečinná spojení bez ohledu na Connection Idle Timeout. Když je přepínač nastaven na false a hodnota Connection Idle Timeout je nenulová, V1 používá polovinu konfigurovaného timeoutu jako svůj úklidový rytmus a po jednom nebo dvou cyklech čištění vyřadí nečinné spoje. Když je přepínač false a Connection Idle Timeout=0, V1 deaktivuje nečinné vyřazování, ale pokračuje v údržbě minimální velikosti poolu v historicky náhodných intervalech dvou až čtyř minut.
• V2 pool. Když je spínač true, V2 neprovádí kontroly stáří nečinnosti pro každé připojení, ale nenulový Connection Idle Timeout interval umožňuje a konfiguruje prořezávání na pozadí. Když je přepínač falsezapnutýConnection Idle Timeout a hodnota je nenulová, V2 provádí kontroly idle-age pro každé spojení a konfiguruje prořezávání na pozadí na základě časového limitu. Když je přepínač false a Connection Idle Timeout=0, V2 neprovádí kontroly stáří nečinnosti pro jednotlivá připojení ani prořezávání na pozadí. V2 neprovádí prořezávání pozadí, když Min Pool Size je větší nebo rovno Max Pool Size.

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

Příklady konfigurace naleznete v části Omezit dobu nečinnosti připojení.

Povolte fond připojení V2

Platí pro: .NET Framework; .NET; .NET Standard

Od verze 7.1 SqlClient zahrnuje implementaci alternativního poolu připojení (V2). Fond V1 zůstává výchozí a přepínač je ve výchozím nastavení nastaven na false.

Chcete-li používat V2, povolte přepínač AppContext Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2 při spuštění aplikace:

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

Nastavení poolování připojovacího řetězce se vztahuje na obě implementace. Pro více informací viz SQL Server connection pooling.

Používejte jeden časový limit připojení pro čekání v poolu a síťová připojení

Platí pro: .NET Framework; .NET; .NET Standard

Od verze 7.1.0 může čas strávený čekáním na spojení z poolu počítat do rozpočtu volajícího Connect Timeout , takže čekání v poolu a pokus o připojení k síti mají společný jeden celkový timeout. Povolte u Switch.Microsoft.Data.SqlClient.UseOverallConnectTimeoutForPoolWait použití celkového timeoutu s kteroukoli implementací connection poolu:

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

Přepínač se ve výchozím nastavení nastaví na false. Toto výchozí nastavení zachovává starší chování časového limitu připojení, kdy operace poolu obdrží plný Connect Timeout časový limit a pokus o navázání síťového připojení dostane další plný časový limit. V důsledku toho může Open nebo OpenAsync trvat déle než konfigurované Connect Timeout.

Návrat k střídání starého failoveru při chybách přihlášení

Platí pro: .NET Framework; .NET; .NET Standard

Od verze 7.1.0 při připojení s nastavením failoveru SqlClient již nepřepíná na partnera při selhání pro chyby SQL vrácené během fáze přihlašování. Chcete-li se vrátit k původnímu chování alternace, povolte při spuštění aplikace přepínač AppContext Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors. Přepínač se ve výchozím nastavení nastaví na false.

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

Respektujte explicitní nulovou škálu na parametrech vartime

Platí pro: .NET Framework; .NET; .NET Standard

Ve výchozím nastavení SqlClient posílá škálu 7, když explicitně nastavíte škálu na 0 pro datetime2, datetimeoffsetnebo časové parametry. Ve verzi 6.0 nebo novější nastavte Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour na false při spuštění aplikace, aby se zachovala explicitní škála 0. Přepínač se ve výchozím nastavení nastaví na true.

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

Související obsah

• AppContext – třída