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

Povolení rozšíření funkcí uživatelského agenta

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

(K dispozici od verze 7.0)

Když je přepínač Switch.Microsoft.Data.SqlClient.EnableUserAgent AppContext povolen, ovladač odesílá serveru údaje o uživatelském agentovi jako součást připojení. Tyto informace pomáhají s řešením potíží a kvantifikací využití ovladačů podle verze a operačního systému. Tento přepínač je ve výchozím nastavení zakázaný. Pokud ho chcete povolit, nastavte přepínač AppContext na true při spuštění aplikace:

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

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.

Povolení minimálního časového limitu během přihlášení

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

Abyste zabránili tomu, aby pokus o přihlášení nečekal neomezeně dlouho, můžete při spuštění aplikace nastavit přepínač AppContext Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin na true:

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-preview2 klíčové slovo připojovacího řetězce Connection Idle Timeout nastavuje dobu nečinnosti v sekundách, po jejímž uplynutí může být připojení ve fondu vyřazeno (výchozí hodnota je 300; hodnota 0 zakáže vypršení časového limitu nečinnosti). Oprávněné připojení je vyřazeno při pozdějším vyzvednutí nebo údržbě, takže přesné načasování se může lišit podle implementace bazénu a tempa údržby. Klíčové slovo se uplatňuje pouze tehdy, když je zakázáno starší chování časového limitu nečinnosti. Při přepnutí na výchozí hodnotě true, pool zachovává historické chování a klíčové slovo nemá žádný vliv.

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

Povolte fond připojení V2

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

Od verze 6.1 SqlClient zahrnuje alternativní experimentální implementaci poolu připojení (V2). Pool V1 zůstává výchozí (přepínač je ve výchozím nastavení nastaven na false). Pro přihlášení do V2 poolu povolte přepínač Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2 AppContext při spuštění aplikace.

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

Count pool čeká na timeout připojení

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

Od verze 7.1.0-preview2 může čas strávený čekáním na spojení z poolu počítat do rozpočtu volajícího, takže čekání poolu a pokus o síťové připojení sdílejí Connect Timeout jeden celkový timeout. Když je přepínač nastaven na výchozí hodnotu false, operace poolu obdrží plný Connect Timeout rozpočet a pokus o připojení k síti získá další plný rozpočet.

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

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-preview2 se při připojování s nakonfigurovaným failoverem SqlClient již nepřepíná na partnera pro failover v případě chyb SQL vrácených 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