Användning av AppContext-omkopplare i SqlClient

Gäller för: .NET Framework .NET .NET Standard

Ladda ned ADO.NET

Klassen AppContext gör att SqlClient kan tillhandahålla nya funktioner samtidigt som de fortsätter att stödja anropare som är beroende av det tidigare beteendet. Användare kan välja bort en ändring av beteendet genom att ange specifika AppContext-växlar.

SqlClient läser och cachar varje switch första gången den använder den switchen. Ställ in växlar vid applikationsstart, innan du använder några SqlClient-typer. Att ändra en switch efter att SqlClient har cacchat dess värde har ingen effekt.

Aktivera MultiSubnetFailover som standard

Gäller för: .NET Framework; .NET; .NET Standard

(Tillgänglig från och med version 7.0)

För att ställa MultiSubnetFailover=true in globalt utan att ändra individuella anslutningssträngar, ställ in AppContext-switchen Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault till true vid applikationsstart:

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

Du kan också aktivera den här växeln i din App.Config:

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

När det är aktiverat fungerar alla anslutningar som om MultiSubnetFailover=true är inställd i anslutningssträngen. Den här växeln är inaktiverad som standard.

Aktivera paket multiplexering för asynkrona läsningar

Gäller för: .NET Framework; .NET; .NET Standard

(Tillgänglig från och med version 7.0)

Multipling av paket förbättrar prestanda för stora asynkrona läsåtgärder, till exempel ExecuteReaderAsync med stora resultatuppsättningar, scenarier för direktuppspelning eller massdatahämtning. Den här funktionen styrs av två aktiveringsbara AppContext-växlar. Om du anger båda växlarna till false aktiveras den nya asynkrona bearbetningssökvägen:

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

Som standard är truebåda växlarna , vilket bevarar det befintliga (kompatibla) beteendet.

Aktivera användaragentens funktionstillägg

Gäller för: .NET Framework; .NET; .NET Standard

(Tillgänglig från och med version 7.0)

När AppContext-switchen Switch.Microsoft.Data.SqlClient.EnableUserAgent är aktiverad skickar drivrutinen användaragentdetaljer till servern som en del av anslutningen. Den här informationen hjälper till med felsökning och kvantifiering av drivrutinsanvändning efter version och operativsystem. Den här växeln är inaktiverad som standard. Om du vill aktivera det anger du AppContext-växeln till true vid programstart:

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

Aktivera beteende för decimaltrunkering

Gäller för: .NET Framework; .NET; .NET Standard

Från och med Microsoft.Data.SqlClient 2.0 avrundas decimaldata som standard, vilket görs av SQL Server. För att aktivera det tidigare beteendet med trunkering kan du ställa in AppContext-switchen Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal till true vid applikationsstart:

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

Aktivera hanterat nätverk i Windows

Gäller för: .NET; .NET Standard

(Tillgänglig från och med version 2.0)

I Windows använder SqlClient en intern implementering av SNI-nätverksgränssnittet som standard. För att möjliggöra användning av en hanterad SNI-implementation, ställ in AppContext-switchen Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows till true vid applikationsstart:

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

Den här växeln växlar drivrutinsbeteendet för att använda en implementering av hanterade nätverk i .NET Core 2.1+ och .NET Standard 2.0+-projekt i Windows, vilket eliminerar alla beroenden för interna bibliotek för Microsoft.Data.SqlClient-biblioteket. Det är endast för testning och felsökning.

Inaktivera transparent nätverks-IP-upplösning

Gäller för: .NET Framework

Transparent nätverks-IP-upplösning (TNIR) är en revision av den befintliga MultiSubnetFailover-funktionen. TNIR påverkar drivrutinens anslutningssekvens om den första lösta IP-adressen för värdnamnet inte svarar och det finns flera IP-adresser som är associerade med värdnamnet. Kombinationen av TransparentNetworkIPResolution och MultiSubnetFailover väljer anslutningssekvensen:

TransparentNetworkIPResolutionär aktiverad som standard på .NET Framework och MultiSubnetFailover är inaktiverad som standard. På .NET 5 och senare versioner är TransparentNetworkIPResolution inte ett känt nyckelord i anslutningssträngen, och att ange det (med valfritt värde) resulterar i ArgumentException (KeywordNotSupported). Dessa versioner stöder endast MultiSubnetFailover. Resten av detta avsnitt (den automatiska överskrivningen, fellägena i följande varning och AppContext-växlingen) gäller .NET Framework.

I .NET Framework, när TransparentNetworkIPResolution inte anges i anslutningssträngen, inaktiverar drivrutinen automatiskt TNIR när datakällan är en identifierad Azure SQL-slutpunkt, när nyckeln Authentication är inställd på någon Microsoft Entra ID-metod (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 eller služba Active Directory Workload Identity), eller när egenskapen SqlConnection.AccessToken anges. För de slutpunktssuffix som drivrutinen känner igen, se posten TransparentNetworkIPResolution i SqlConnection.ConnectionString.

Ett explicit TransparentNetworkIPResolution värde kringgår detta automatiska beteende: True aktiverar TNIR och False inaktiverar TNIR villkorslöst. För att återställa det automatiska beteendet, ta bort nyckelordet från reťazec pripojenia. Den automatiska åsidosättningen gäller inte heller när anslutningssträngen pekar på Azure SQL via ett anpassat CNAME eller ett anpassat DNS-namn vars suffix inte identifieras som en Azure SQL-slutpunkt. Den automatiska överskrivningen riktar sig specifikt mot Azure SQL; den aktiveras inte för lokal SQL Server, så TNIR är aktiverat som standard där.

Långa anslutningsfördröjningar på .NET Framework

I .NET Framework kan TransparentNetworkIPResolution=True (standardvärdet) orsaka långa anslutningsfördröjningar och timeout under handskakningen före autentisering när målets DNS-namn slås upp till flera IP-adresser och en av de första IP-adresserna inte fungerar, är inaktuell eller inte kan nås. TNIR försöker lösa IP:n i följd och ökar timeouten per försök varje runda tills totalen Connect Timeout är nådd. Du brukar observera en oväntat lång anslutningsfördröjning som slutar med detta fel:

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.

Mönstret förekommer i flera topologier:

• Azure SQL Database, Azure SQL Managed Instance eller SQL-databas i Microsoft Fabric. Azure SQL-gatewayen routar varje autentisering till en backend-replika. När en routad anslutning misslyckas försöker TNIR om den routade backend utan att återvända till gatewayen för omdirigering, vilket förlänger fördröjningen under en backend-failover.
• Lokal SQL Server bakom en Always On-tillgänglighetsgrupplyssnare vars DNS-namn löser sig till flera replika-IP-adresser. En föråldrad DNS-post eller en ohälsosam replika-IP testas sekventiellt innan TNIR når en fungerande replika.
• Redundanta klusterinstanser med en klusterlyssnare för flera undernät, eller någon annan konfiguration där målets DNS-namn har flera A/AAAA poster (till exempel DNS round-robin).

För att undvika detta beteende, sätt MultiSubnetFailover=True i reťazec pripojenia:

MultiSubnetFailover=True

Denna rekommendation fungerar på alla .NET-versioner och täcker både Azure SQL och lokal SQL Server. När MultiSubnetFailover=True ignorerar drivrutinen TransparentNetworkIPResolution, försöker ansluta till de DNS-matchade IP-adresserna parallellt och slutför autentiseringen med den första replika som svarar. Trots namnet gäller MultiSubnetFailover alla lyssnarobjekt vars DNS-namn upplöses till flera mål-IP-adresser, oavsett om dessa IP-adresser finns i olika subnät, och det är säkert på fristående servrar vars DNS-namn upplöses till en enda IP-adress.

För processövergripande kontroll utan att redigera varje reťazec pripojenia, använd Enable MultiSubnetFailover som standard AppContext-switch.

Inaktivera TNIR med en AppContext-switch

För att vända standardvärdet för TransparentNetworkIPResolution från true till false i .NET Framework, ställ in AppContext-switchen Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString till true vid applikationsstart. Denna inställning ändrar bara standardvärdet när TransparentNetworkIPResolution inte finns i anslutningssträngen; den åsidosätter inte ett uttryckligen angivet värde.

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

Mer information om hur du anger dessa egenskaper finns i dokumentationen för egenskapen SqlConnection.ConnectionString.

Aktivera en minsta tidsgräns under inloggningen

Gäller för: .NET Framework; .NET; .NET Standard

För att förhindra att ett inloggningsförsök väntar på obestämd tid kan du ställa in AppContext-switchen Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin till true vid applikationsstart:

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

Inaktivera blockerande beteende för ReadAsync

Gäller för: .NET Framework; .NET; .NET Standard

Från och med version 3.0 ReadAsync körs den asynkront. Tidigare versioner körs ReadAsync synkront och blockerar den anropande tråden på .NET Framework. För att kontrollera detta blockerande beteende, ställ in AppContext-switchen Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking till true eller false vid applikationsstart:

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

Aktivera rowversion-beteende för nullvärden

Gäller för: .NET Framework; .NET; .NET Standard

Från och med version 3.0, när en radversion har ett nollvärde, SqlDataReader returnerar ett DBNull värde istället för ett tomt byte[]. För att aktivera det äldre beteendet att returnera en tom byte[], aktivera AppContext-switchen Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior vid applikationsstart.

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

Ignorera osäker TLS-varning

Gäller för: .NET Framework; .NET; .NET Standard

(Tillgänglig från och med version 4.0.1)

När man använder Encrypt=false i reťazec pripojenia ger konsolen en säkerhetsvarning om TLS-versionen är 1.2 eller lägre. Undertrycka denna varning genom att aktivera följande AppContext-omkoppling vid applikationsstart:

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

Ignorera server som tillhandahålls av redundanspartner

Gäller för: .NET Framework; .NET; .NET Standard

(Tillgänglig från och med versionerna 5.1.8, 6.0.4 och 6.1.3)

Vid failover föredras failoverpartnerinformation som tillhandahålls av servern framför failoverpartnerinformation som anges i anslutningssträngen. Om du vill ignorera failover-partnerinformation som tillhandahålls av servern och endast överväga failover-partnerinformation som anges i anslutningssträngen, aktiverar du den här AppContext-omkopplaren vid programstart:

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

Tillämpa anslutningens inaktivitetstimeout

Gäller för: .NET Framework; .NET; .NET Standard

Från och med version 7.1.0-preview2 Connection Idle Timeout konfigurerar reťazec pripojenia-nyckelordet vilotiden i sekunder, varefter en poolad anslutning blir berättigad till avhysning (standard 300; ett värde 0 inaktiverar viloförfall). En berättigad anslutning kastas bort vid en senare hämtnings- eller underhållspass, så den exakta tidpunkten kan variera beroende på poolimplementering och underhållsrytm. Nyckelordet aktiveras endast när det gamla idle-timeout-beteendet är inaktiverat. Med switchen på dess standardvärde , truebevarar poolen det historiska beteendet och nyckelordet har ingen effekt.

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

Aktivera V2-anslutningspoolen

Gäller för: .NET Framework; .NET; .NET Standard

Från och med version 6.1 inkluderar SqlClient en alternativ, experimentell anslutningspoolimplementation (V2). V1-poolen förblir standard (switchen är standard på false). För att välja in i V2-poolen, aktivera AppContext-switchen Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2 när applikationen startar.

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

Räkna väntetider i poolen mot tidsgränsen för anslutning

Gäller för: .NET Framework; .NET; .NET Standard

Från och med version 7.1.0-preview2 kan tiden som läggs på att vänta på en anslutning från poolen räknas mot anroparens Connect Timeout tidsbudget, så väntetiden i poolen och försöket att upprätta nätverksanslutningen omfattas av en och samma tidsgräns. När switchen är inställd på standardvärdet false får pooloperationer en full Connect Timeout, och försöket att upprätta nätverksanslutningen får ytterligare en full budget.

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

Återgå till äldre failover-alternativ vid inloggningsfel

Gäller för: .NET Framework; .NET; .NET Standard

Från och med version 7.1.0-preview2 växlar SqlClient inte längre till partnern för redundansväxling för SQL-fel som returneras under inloggningsprocessen när en anslutning är konfigurerad med redundansväxling. För att återgå till det äldre alterneringsbeteendet, aktivera AppContext-switchen Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors vid applikationsstart. Växeln är standardinställd på false.

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

Respektera en explicit nollskala på vartidsparametrar

Gäller för: .NET Framework; .NET; .NET Standard

Som standard skickar SqlClient en skala på 7 när du uttryckligen sätter skalan till 0 för datetime2, datetimeoffset eller tidsparametrar . I version 6.0 eller senare, ställ Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour in till false vid applikationsstart för att bevara den explicita skalan 0. Omkopplaren är som standard inställd på true.

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

Relaterat innehåll

• AppContext-klass