<AppContextSwitchOverrides> element

Article
06/02/2022

Defines one or more switches used by the AppContext class to provide an opt-out mechanism for new functionality.

<configuration>
<runtime>
<AppContextSwitchOverrides>

Syntax

<AppContextSwitchOverrides value="name1=value1[[;name2=value2];...]" />

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute	Description
`value`	Required. Defines one or more switch names and their associated Boolean values.

value Attribute

Value	Description
"name=value"	A predefined switch name along with its value (`true` or `false`). Multiple switch name/value pairs are separated by semicolons (";"). For a list of predefined switch names supported by the .NET Framework, see the Remarks section.

Child Elements

None.

Parent Elements

Element	Description
`configuration`	The root element in every configuration file used by the common language runtime and .NET Framework applications.
`runtime`	Contains information about runtime initialization options.

Remarks

Starting with .NET Framework 4.6, the <AppContextSwitchOverrides> element in a configuration file allows callers of an API to determine whether their app can take advantage of new functionality or preserve compatibility with previous versions of a library. For example, if the behavior of an API has changed between two versions of a library, the <AppContextSwitchOverrides> element allows callers of that API to opt out of the new behavior on versions of the library that support the new functionality. For apps that call APIs in the .NET Framework, the <AppContextSwitchOverrides> element can also allow callers whose apps target an earlier version of the .NET Framework to opt in to new functionality if their app is running on a version of the .NET Framework that includes that functionality.

The value attribute of the <AppContextSwitchOverrides> element consists of a single string that consists of one or more semicolon-delimited name/value pairs. Each name identifies a compatibility switch, and its corresponding value is a Boolean (true or false) that indicates whether the switch is set. By default, the switch is false, and libraries provide the new functionality. They only provide the previous functionality if the switch is set (that is, its value is true). This allows libraries to provide new behavior for an existing API while allowing callers who depend on the previous behavior to opt out of the new functionality.

.NET Framework supports the following switches:

Switch name	Description	Introduced
`Switch.MS.Internal.` `DoNotApplyLayoutRoundingToMarginsAndBorderThickness`	Controls whether Windows Presentation Foundation uses legacy a algorithm for control layout. For more information, see Mitigation: WPF Layout.	.NET Framework 4.6
`Switch.MS.Internal.` `UseSha1AsDefaultHashAlgorithmForDigitalSignatures`	Controls whether the default algorithm used for signing parts of a package by PackageDigitalSignatureManager is SHA1 or SHA256. Due to collision problems with SHA1, Microsoft recommends SHA256.	.NET Framework 4.7.1
`Switch.System.Activities.` `UseMD5CryptoServiceProviderForWFDebugger`	When set to `false`, allows debugging of XAML-based workflow projects with Visual Studio when FIPS is enabled. Without it, a NullReferenceException is thrown in calls to methods in the System.Activities assembly.	.NET Framework 4.7
`Switch.System.Activities.` `UseMD5ForWFDebugger`	Controls whether the checksum for a workflow instance in the debugger uses MD5 or SHA1.	.NET Framework 4.7
`Switch.System.Activities.` `UseSHA1HashForDebuggerSymbols`	Controls whether workflow checksum hashing uses the SHA1 algorithm introduced as the default in .NET Framework 4.7 (`true`), or whether it uses the default SHA256 algorithm introduced as the default in .NET Framework 4.8 (`false`). Due to collision problems with SHA1, Microsoft recommends SHA256.	.NET Framework 4.8
`Switch.System.Diagnostics.` `IgnorePortablePDBsInStackTraces`	Controls whether stack traces obtain when using portable PDBs can include source file and line information. `false` to include source file and line information; otherwise, `true`.	.NET Framework 4.7.2
`Switch.System.Drawing.` `DontSupportPngFramesInIcons`	Controls whether the Icon.ToBitmap method throws an exception when an Icon object has PNG frames. For more information, see Mitigation: PNG Frames in Icon Objects.	.NET Framework 4.6
`Switch.System.Drawing.Text.` `DoNotRemoveGdiFontsResourcesFromFontCollection`	Determines whether System.Drawing.Text.PrivateFontCollection objects are properly disposed when added to the collection by the PrivateFontCollection.AddFontFile(String) method. `true` to maintain the legacy behavior; `false` to dispose of all private font objects.	.NET Framework 4.7.2
`Switch.System.Drawing.Printing.` `OptimizePrintPreview`	Controls whether the performance of the PrintPreviewDialog is optimized for network printers. For more information, see PrintPreviewDialog control overview.	.NET Framework 4.6
`Switch.System.Globalization.EnforceJapaneseEraYearRanges`	Controls whether year range checks for Japanese calendar eras are enforced. `true` to enforce year range checks, and `false` to disable them (the default behavior). For more information, see Working with calendars.	.NET Framework 4.6
`Switch.System.Globalization.EnforceLegacyJapaneseDateParsing`	Controls whether only "1" is recognized as the first year of a Japanese calendar era in parsing operations. `true` to recognize only "1"; `false` to recognize either "1" or Gannen (the default behavior). For more information, see Working with calendars.	.NET Framework 4.6
`Switch.System.Globalization.FormatJapaneseFirstYearAsANumber`	Controls whether the first year of a Japanese calendar era is represented as "1" or Gannen in formatting operations. `true` to format the era's first year as "1"; `false` to format it as Gannen (the default behavior). For more information, see Working with calendars.	.NET Framework 4.6
`Switch.System.Globalization.NoAsyncCurrentCulture`	Controls whether asynchronous operations do not flow from the calling thread's context. For more information, see CurrentCulture and CurrentUICulture flow across tasks.	.NET Framework 4.6
`Switch.System.IdentityModel.` `DisableMultipleDNSEntriesInSANCertificate`	Controls whether the X509CertificateClaimSet.FindClaims method attempts to match the claim type only with the last DNS entry. For more information, see Mitigation: X509CertificateClaimSet.FindClaims Method.	.NET Framework 4.6.1
`Switch.System.IdentityModel.` `EnableCachedEmptyDefaultAuthorizationContext`	Controls whether to allow AuthorizationContext.Empty to return a mutable object.	.NET Framework 4.6
`Switch.System.IO.BlockLongPaths`	Controls whether paths longer than `MAX_PATH` (260 characters) throw a PathTooLongException. For more information, see Long Path Support.	.NET Framework 4.6.2
`Switch.System.IO.Compression.` `DoNotUseNativeZipLibraryForDecompression`	Controls whether native OS routines are used for decompression by the DeflateStream class. `false` to use native APIs; `true` to use the DeflateStream implementation.	.NET Framework 4.7.2
`Switch.System.IO.Compression.ZipFile.` `UseBackslash`	Uses the backslash ("\") rather than the forward slash ("/") as the path separator in the ZipArchiveEntry.FullName property. For more information, see Mitigation: ZipArchiveEntry.FullName Path Separator.	.NET Framework 4.6.1
`Switch.System.IO.Ports.` `DoNotCatchSerialStreamThreadExceptions`	Controls whether operating system exceptions that are thrown on background threads created with SerialPort streams terminate the process.	.NET Framework 4.7.1
`Switch.System.IO.` `UseLegacyPathHandling`	Controls whether legacy path normalization is used and URI paths are supported by the Path.GetDirectoryName and Path.GetPathRoot methods. For more information, see Mitigation: Path Normalization and Mitigation: Path Colon Checks.	.NET Framework 4.6.2
`Switch.System.` `MemberDescriptorEqualsReturnsFalseIfEquivalent`	Controls whether a test for equality compares the MemberDescriptor.Category property of one object with the MemberDescriptor.Description property of the second object. For more information, see Incorrect implementation of MemberDescriptor.Equals.	.NET Framework 4.6.2
`Switch.System.Net.` `DontCheckCertificateEKUs`	Disables certificate enhanced key usage (EKU) object identifier (OID) validation. An enhanced key usage (EKU) extension is a collection of object identifiers (OIDs) that indicate the applications that use the key.	.NET Framework 4.6
`Switch.System.Net.` `DontEnableSchSendAuxRecord`	Disables TLS1.0 Browser Exploit Against SSL/TLS (BEAST) mitigation by disabling the use of SCH_SEND_AUX_RECORD.	.NET Framework 4.6
`Switch.System.Net.` `DontEnableSchUseStrongCrypto`	Controls whether the System.Net.ServicePointManager and System.Net.Security.SslStream classes can use the SSL 3.0 protocol. For more information, see Mitigation: TLS Protocols.	.NET Framework 4.6
`Switch.System.Net.` `DontEnableSystemDefaultTlsVersions`	Disables SystemDefault TLS versions reverting back to a default of Tls12, Tls11, Tls.	.NET Framework 4.7
`Switch.System.Net.` `DontEnableTlsAlerts`	Disables SslStream TLS server-side Alerts.	.NET Framework 4.7
`Switch.System.Runtime.InteropServices.` `DoNotMarshalOutByrefSafeArrayOnInvoke`	Controls whether ByRef SafeArray parameters on COM interop events marshal back to native code (`false`) or whether marshalling back to native code is disabled (`true`).	.NET Framework 4.8
`Switch.System.Runtime.Serialization.` `DoNotUseECMAScriptV6EscapeControlCharacter`	Controls whether the DataContractJsonSerializer serializes some control characters based on the ECMAScript V6 and V8 standards. For more information, see Mitigation: Serialization of Control Characters with the DataContractJsonSerializer	.NET Framework 4.7
`Switch.System.Runtime.Serialization.` `DoNotUseTimeZoneInfo`	Controls whether the DataContractJsonSerializer supports multiple adjustments or only a single adjustment for a time zone. If `true`, it uses the TimeZoneInfo type to serialize and deserialize date and time data; otherwise, it uses the TimeZone type, which does not support multiple adjustment rules.	.NET Framework 4.6.2
`Switch.System.Runtime.Serialization.UseNewMaxArraySize`	Controls whether System.Runtime.Serialization.ObjectManager uses a larger array size during object serialization and deserialization. Set this switch to `true` to improve the performance of serialization and deserialization of large object graphs by types such as BinaryFormatter.	.NET Framework 4.7.2
`Switch.System.Security.ClaimsIdentity.` `SetActorAsReferenceWhenCopyingClaimsIdentity`	Controls whether the ClaimsIdentity(IIdentity) constructor sets the new object's ClaimsIdentity.Actor property with an existing object reference. For more information, see Mitigation: ClaimsIdentity Constructor.	.NET Framework 4.6.2
`Switch.System.Security.Cryptography.` `AesCryptoServiceProvider.DontCorrectlyResetDecryptor`	Controls whether the attempt to reuse an AesCryptoServiceProvider decryptor throws a CryptographicException. For more information, see AesCryptoServiceProvider decryptor provides a reusable transform.	.NET Framework 4.6.2
`Switch.System.Security.Cryptography.` `DoNotAddrOfCspParentWindowHandle`	Controls whether the value of the CspParameters.ParentWindowHandle property is an IntPtr that represents the memory location of a window handle, or whether it is a window handle (an HWND). For more information, see Mitigation: CspParameters.ParentWindowHandle Expects an HWND.	.NET Framework 4.7
`Switch.System.Security.Cryptography.` `UseLegacyFipsThrow`	Controls whether the use of managed cryptography classes in FIPS mode throws a CryptographicException (`true`) or relies on the implementation of system libraries (`false`).	.NET Framework 4.8
`Switch.System.Security.Cryptography.Pkcs.` `UseInsecureHashAlgorithms`	Determines whether the default for some SignedCMS operations is SHA1 or SHA256. Due to collision problems with SHA1, Microsoft recommends SHA256.	.NET Framework 4.7.1
`Switch.System.Security.Cryptography.X509Certificates.` `ECDsaCertificateExtensions.UseLegacyPublicKeyReader`	Controls whether the ECDsaCertificateExtensions.GetECDsaPublicKey method correctly handles all named curves supported by the operating system (`false`) or reverts to legacy behavior.	.NET Framework 4.8
`Switch.System.Security.Cryptography.Xml.` `UseInsecureHashAlgorithms`	Determines whether the default for some SignedXML operations is SHA1 or SHA256. Due to collision problems with SHA1, Microsoft recommends SHA256.	.NET Framework 4.7.1
`Switch.System.ServiceModel.` `AllowUnsignedToHeader`	Determines whether the `TransportWithMessageCredential` security mode allows messages with an unsigned "to" header. This is an opt-in switch. For more information, see Runtime Changes in the .NET Framework 4.6.1.	.NET Framework 4.6.1
`Switch.System.ServiceModel.` `DisableAddressHeaderCollectionValidation`>	Controls whether the AddressHeaderCollection(IEnumerable<AddressHeader>) constructor throws an ArgumentException if one of the elements is `null`.	.NET Framework 4.7.1
`Switch.System.IdentityModel.` `DisableCngCertificates`	Determines whether the attempt to use X509 certificates with a CSG key storage provider throws an exception. For more information, see WCF transport security supports certificates stored using CNG.	.NET Framework 4.6.1
`Switch.System.ServiceModel.` `DisableExplicitConnectionCloseHeader`	When using the HTTP transport with a self-hosted service, setting this value to `true` causes WCF to ignore an application adding the `Connection: close` header to the response headers for a request. Setting this value to `false` enables adding the `Connection: close` header to the response headers, which results in closing the request socket after a response has been sent.	.NET Framework 4.6
`Switch.System.ServiceModel.` `DisableOperationContextAsyncFlow`	Handles deadlocks that result from restricting instances of a re-entrant service to a single thread of execution at a time.	.NET Framework 4.6.2
`Switch.System.ServiceModel.` `DisableUsingServicePointManagerSecurityProtocols`	Along with `Switch.System.Net.DontEnableSchUseStrongCrypto`, determines whether WCF message security uses TLS 1.1 and TLS 1.2.	.NET Framework 4.7
`Switch.System.ServiceModel.` `DontEnableSystemDefaultTlsVersions`	A value of `false` sets the default configuration to allow the operating system to choose the protocol. A value of `true` sets the default to the highest protocol available. (Also available on servicing branch of previous framework versions)	.NET Framework 4.7.1
`Switch.System.ServiceModel.` `UseSha1InMsmqEncryptionAlgorithm`	Determines whether the default message signing algorithm for MSMQ messages in WCF is SHA1 or SHA256. Due to collision problems with SHA1, Microsoft recommends SHA256.	.NET Framework 4.7.1
`Switch.System.ServiceModel.` `UseSha1InPipeConnectionGetHashAlgorithm`	Controls whether WCF uses a SHA1 or a SHA256 hash to generate random names for named pipes. Due to collision problems with SHA1, Microsoft recommends SHA256.	.NET Framework 4.7.1
`Switch.System.ServiceModel.Internals` `IncludeNullExceptionMessageInETWTrace`	Controls whether to throw a NullReferenceException when the exception message is null.	.NET Framework 4.7
`Switch.System.ServiceProcess.` `DontThrowExceptionsOnStart`	Controls whether exceptions thrown on service startup are propagated to the caller of the ServiceBase.Run method.	.NET Framework 4.7.1
`Switch.System.Threading.UseNetCoreTimer`	Controls whether Timer instances take advantage of performance improvements for high-scale environments. If `true`, the performance improvements are enabled; if `false` (the default value), they are disabled.	.NET Framework 4.8
`Switch.System.Uri.` `DontEnableStrictRFC3986ReservedCharacterSets`	Determines whether certain percent-encoded characters that were sometimes decoded are now consistently left encoded. If `true`, they are decoded; otherwise, `false`.	.NET Framework 4.7.2
`Switch.System.Uri.` `DontKeepUnicodeBidiFormattingCharacters`	Determines the handling of Unicode bidirectional characters in URIs. `true` to strip them from URIs; `false` to preserve and percent-encode them.	.NET Framework 4.7.2
`Switch.System.Windows.Controls.Grid.` `StarDefinitionsCanExceedAvailableSpace`	Determines whether Windows Presentation Foundation applies an old algorithm (`true`) or a new algorithm (`false`) in allocating space to *-columns. For more information, see Mitigation: Grid Control's Space Allocation to Star-columns.	.NET Framework 4.7
`Switch.System.Windows.Controls.TabControl.` `SelectionPropertiesCanLagBehindSelectionChangedEvent`	Controls whether a selector or a tab control always updates the value of its selected value property before raising the selection changed event.	.NET Framework 4.7.1
`Switch.System.Windows.Controls.Text.` `UseAdornerForTextboxSelectionRendering`	Determines whether non-Adorner-based selection rendering is available for the TextBox and PasswordBox controls to prevent occluded text (`false`), or whether text is rendered only in the Adorner layer (`true`).	.NET Framework 4.7.2
`Switch.System.Windows.Data.Binding.` `IListIndexerHidesCustomIndexer`	Controls whether custom IList indexers are used incorrectly (`true`) or correctly (`false`) by the System.Windows.Data.Binding class.	.NET Framework 4.8
`Switch.System.Windows.DoNotScaleForDpiChanges`	Determines whether DPI changes occur on a per-system (a value of `false`) or per-monitor basis (a value of `true`).	.NET Framework 4.6.2
`Switch.System.Windows.` `DoNotUsePresentationDpiCapabilityTier2OrGreater`	Controls whether improvements in sizing of controls in a System.Windows.Interop.HwndHost when WPF is run in per-monitor aware mode are disabled (`true`) or enabled (`false`).	.NET Framework 4.8
`Switch.System.Windows.Forms.` `DisconnectUiaProvidersOnWmDestroy`	Controls whether providers are disconnected when the corresponding control window is destroyed (`true`) or not (`false`). This switch provides an opt-in to a performance fix to address a leak of IRawElementProviderSimple objects.	.NET Framework 4.8
`Switch.System.Windows.Forms.` `DomainUpDown.UseLegacyScrolling`	Determines whether the developer needs to specially handle the DomainUpDown.UpButton() action when control text is present. `true` to handle the UpButton() action; `false` for the DomainUpDown.UpButton() and DomainUpDown.DownButton() actions to be properly in sync.	.NET Framework 4.7.2
`Switch.System.Windows.Forms.` `DontSupportReentrantFilterMessage`	Opts out of the code that allows a custom IMessageFilter.PreFilterMessage implementation to safely filter messages without throwing an exception when the Application.FilterMessage method is called. For more information, see Mitigation: Custom IMessageFilter.PreFilterMessage Implementations.	.NET Framework 4.6.1
`Switch.System.Windows.Forms.` `UseLegacyContextMenuStripSourceControlValue`	Determines whether the ContextMenuStrip.SourceControl property returns the source control when the user opens the menu from a nested ToolStripMenuItem control. `true` to return `null`, the legacy behavior; `false` to return the source control.	.NET Framework 4.7.2
`Switch.System.Windows.Forms.UseLegacyToolTipDisplay`	Controls whether tooltip invocation support is disabled (`true`) or enabled (`false`). Enabling tooltip invocation support also requires legacy accessibility features defined by `Switch.UseLegacyAccessibilityFeatures`, `Switch.UseLegacyAccessibilityFeatures.2`, and `Switch.UseLegacyAccessibilityFeatures.3` all be disabled (set to `false`).	.NET Framework 4.8
`Switch.System.Windows.Input.Stylus.` `EnablePointerSupport`	Determines whether an optional `WM_POINTER`-based touch/stylus stack is enabled in WPF applications. For more information, see Mitigation: Pointer-based Touch and Stylus Support	.NET Framework 4.7
`Switch.System.Windows.Markup.` `DoNotUseSha256ForMarkupCompilerChecksumAlgorithm`	Determines whether the default hash algorithm used for checksums is SHA256 (`false`) or SHA1 (`true`). Due to collision problems with SHA1, Microsoft recommends SHA256.	.NET Framework 4.7.2
`Switch.System.Windows.Media.ImageSourceConverter.` `OverrideExceptionWithNullReferenceException`	Controls whether a legacy NullReferenceException is thrown instead of the exception that more specifically indicates the cause of the exception (such as a DirectoryNotFoundException or a FileNotFoundException. It is intended for use by code that depends on handling the NullReferenceException.	.NET Framework 4.7
`Switch.System.Workflow.ComponentModel.` `UseLegacyHashForXomlFileChecksum`	Controls whether checksum hashing of XOML files in workflow project builds use the MD5 algorithm (`true`), or whether they use the SHA256 algorithm introduced as the default in .NET Framework 4.8. Due to collision problems with MD5, Microsoft recommends SHA256.	.NET Framework 4.8
`Switch.System.Workflow.Runtime.` `UseLegacyHashForSqlTrackingCacheKey`	Controls whether checksum hashing by the SqlTrackingService uses the MD5 algorithm (`true`) for cached strings, or whether it uses the SHA256 algorithm introduced as the default in .NET Framework 4.8. Due to collision problems with MD5, Microsoft recommends SHA256.	.NET Framework 4.8
`Switch.System.Workflow.Runtime.` `UseLegacyHashForWorkflowDefinitionDispenserCacheKey`	Controls whether checksum hashing by the Workflow Runtime uses the MD5 algorithm (`true`) for cached workflow definitions, or whether it uses the SHA256 algorithm introduced as the default in .NET Framework 4.8. Due to collision problems with MD5, Microsoft recommends SHA256.	.NET Framework 4.8
`Switch.UseLegacyAccessibilityFeatures`	Controls whether accessibility features available starting with .NET Framework 4.7.1 are enabled or disabled.	.NET Framework 4.7.1
`Switch.UseLegacyAccessibilityFeatures.2`	Controls whether accessibility features available in .NET Framework 4.7.2 are enabled (`false`) or disabled (`true`). If `true`, `Switch.UseLegacyAccessibilityFeatures` must also be `true` to enable .NET Framework 4.7.1 accessibility features.	.NET Framework 4.7.2
`Switch.UseLegacyAccessibilityFeatures.3`	Controls whether accessibility features introduced in .NET Framework 4.8 are enabled (`false`) or disabled (`true`). If `true`, `Switch.UseLegacyAccessibilityFeatures` and `Switch.UseLegacyAccessibilityFeatures.2` must also be `true`.	.NET Framework 4.8
`Switch.UseLegacyToolTipDisplay`	Controls whether tooltips are displayed when a user hovers the mouse cursor over a WPF control (`true`), or whether they are displayed both on keyboard focus and via keyboard shortcut key (`false`, the default behavior). For applications running on .NET Framework 4.8 but targeting previous versions of the .NET Framework, enabling both keyboard focus and shortcut key support requires that `Switch.UseLegacyAccessibilityFeatures`, `Switch.UseLegacyAccessibilityFeatures.2`, and `Switch.UseLegacyAccessibilityFeatures.3` all be set to `false`.	.NET Framework 4.8
`Switch.System.Xml.` `IgnoreEmptyKeySequences`	Controls whether empty key sequences in compound keys are ignored by XSD schema validation. For more information, see Mitigation: XML Schema Validation.	.NET Framework 4.6

Note

Instead of adding an AppContextSwitchOverrides element to an application configuration file, you can also set the switches programmatically by calling the AppContext.SetSwitch method.

Library developers can also define custom switches to allow callers to opt out of changed functionality introduced in later versions of their libraries. For more information, see the AppContext class.

Switches in ASP.NET apps

You can configure an ASP.NET application to use compatibility settings by adding an <Add> element to the <appSettings> section of the web.config file.

The following example uses the <add> element to add two settings to the <appSettings> section of a web.config file:

<appSettings>
  <add key="AppContext.SetSwitch:Switch.System.Globalization.NoAsyncCurrentCulture" value="true" />
  <add key="AppContext.SetSwitch:Switch.System.Uri.DontEnableStrictRFC3986ReservedCharacterSets" value="true" />
</appSettings>

Example

The following example uses the AppContextSwitchOverrides element to define a single application compatibility switch, Switch.System.Globalization.NoAsyncCurrentCulture, that prevents culture from flowing across threads in asynchronous method calls.

<configuration>
   <runtime>
      <AppContextSwitchOverrides value="Switch.System.Globalization.NoAsyncCurrentCulture=true" />
   </runtime>
</configuration>

The following example uses the AppContextSwitchOverrides element to define two application compatibility switches, Switch.System.Globalization.NoAsyncCurrentCulture and Switch.System.IO.BlockLongPaths. A semicolon separates the two name/value pairs.

<configuration>
    <runtime>
       <AppContextSwitchOverrides
          value="Switch.System.Globalization.NoAsyncCurrentCulture=true;Switch.System.IO.BlockLongPaths=true" />
    </runtime>
</configuration>

Share via