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 attribute. 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 the .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 into 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.
The .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.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.Globalization.NoAsyncCurrentCulture |
Controls whether asynchronous operations do not flow from the calling thread's context. For more information, see Mitigation: Culture and Asynchronous Operations. | .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.IO.BlockLongPaths |
Controls whether paths longer than MAX_PATH (260 characters) throw a PathTooLongException. For more information, see Mitigation: Long Path Support. |
.NET Framework 4.6.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.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 Mitigation: MemberDescriptor.Equals. | .NET Framework 4.6.2 |
Switch.System.Net.DontCheckCertificateEKUs |
Disables certificate EKU OID validation. | .NET Framework 4.6 |
Switch.System.Net.DontEnableSchSendAuxRecord |
Disables TLS1.0 BEAST mitigation by disabling the use of SCH_SEND_AUX_RECORD. | .NET Framework 4.6 |
Switch.System.Net.DontEnableSchUseStrongCrypto |
Controls whether the ServicePointManager and 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.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.Security.ClaimsIdentity.SetActorAsReferenceWhenCopyingClaimsIdentity |
Controls whether the ClaimsIdentity.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 Retargeting Changes in the .NET Framework 4.6.2. | .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.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.DisableCngCertificates |
Determines whether the attempt to use X509 certificates with a CSG key storage provider throws an exception. For more information, see Windows Communication Foundation (WCF). | .NET Framework 4.6.1 |
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.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.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.Input.Stylus.EnablePointerSupport |
Determines whether an optional WM_POINTER-based touch/stylus stack is enabled in WPF applications. For more information, see Mitigation: Poiner-based Touch and Stylus Support |
|
Switch.System.Windows.Media.ImageSourceConverterOverrideExceptionWithNullReferenceException |
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 |
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 static (in C#) or Shared (in Visual Basic) 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.
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. Note that a semicolon separates the two name/value pairs.
<configuration>
<runtime>
<AppContextSwitchOverrides
value="Switch.System.Globalization.NoAsyncCurrentCulture=true;Switch.System.IO.BlockLongPaths=true" />
</runtime>
</configuration>




