Retargeting Changes for Migration from .NET Framework 4.0 to 4.7.2

If you are migrating from the .NET Framework 4.0 to 4.7.2, review the following topics for application compatibility issues that may affect your app:

ADO.NET

DbParameter.Precision and DbParameter.Scale are now public virtual members

Details

Precision and Scale are implemented as public virtual properties. They replace the corresponding explicit interface implementations, IDbDataParameter.Precision and IDbDataParameter.Scale.

Suggestion

When re-building an ADO.NET database provider, these differences will require the 'override' keyword to be applied to the Precision and Scale properties. This is only needed when re-building the components; existing binaries will continue to work.

Name Value
Scope Minor
Version 4.5.1
Type Retargeting

Affected APIs

ASP.NET

ASP.NET Accessibility Improvements in .NET Framework 4.7.1

Details

Starting with the .NET Framework 4.7.1, ASP.NET has improved how ASP.NET Web Controls work with accessibility technology in Visual Studio to better support ASP.NET customers. These include the following changes:

  • Changes to implement missing UI accessibility patterns in controls, like the Add Field dialog in the Details View wizard, or the Configure ListView dialog of the ListView wizard.
  • Changes to improve the display in High Contrast mode, like the Data Pager Fields Editor.
  • Changes to improve the keyboard navigation experiences for controls, like the Fields dialog in the Edit Pager Fields wizard of the DataPager control, the Configure ObjectContext dialog, or the Configure Data Selection dialog of the Configure Data Source wizard.

Suggestion

How to opt in or out of these changes In order for the Visual Studio Designer to benefit from these changes, it must run on the .NET Framework 4.7.1 or later. The web application can benefit from these changes in either of the following ways:

  • Install Visual Studio 2017 15.3 or later, which supports the new accessibility features with the following AppContext Switch by default.
  • Opt out of the legacy accessibility behaviors by adding the Switch.UseLegacyAccessibilityFeatures AppContext switch to the <runtime> section in the devenv.exe.config file and setting it to false, as the following example shows.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<runtime>
...
<!-- AppContextSwitchOverrides value attribute is in the form of 'key1=true/false;key2=true/false'  -->
<AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures=false" />
...
</runtime>
</configuration>

Applications that target the .NET Framework 4.7.1 or later and want to preserve the legacy accessibility behavior can opt in to the use of legacy accessibility features by explicitly setting this AppContext switch to true.

Name Value
Scope Minor
Version 4.7.1
Type Retargeting

HtmlTextWriter does not render <br/> element correctly

Details

Beginning in the .NET Framework 4.6, calling RenderBeginTag(String) and RenderEndTag() with a <BR /> element will correctly insert only one <BR /> (instead of two)

Suggestion

If an app depended on the extra <BR /> tag, RenderBeginTag(String) should be called a second time. Note that this behavior change only affects apps that target the .NET Framework 4.6 or later, so another option is to target a previous version of the .NET Framework in order to get the old behavior.

Name Value
Scope Edge
Version 4.6
Type Retargeting

Affected APIs

MachineKey.Encode and MachineKey.Decode methods are now obsolete

Details

These methods are now obsolete. Compilation of code that calls these methods produces a compiler warning.

Suggestion

The recommended alternatives are Protect(Byte[], String[]) and Unprotect(Byte[], String[]). Alternatively, the build warnings can be suppressed, or they can be avoided by using an older compiler. The APIs are still supported.

Name Value
Scope Minor
Version 4.5
Type Retargeting

Affected APIs

Multi-line ASP.Net TextBox spacing changed when using AntiXSSEncoder

Details

In .NET Framework 4.0, extra lines were inserted between lines of a multi-line text box on postback, if using the System.Web.Security.AntiXss.AntiXssEncoder. In .NET Framework 4.5, those extra line breaks are not included, but only if the web app is targeting .NET Framework 4.5

Suggestion

Be aware that 4.0 web apps retargeted to .NET Framework 4.5 may have multi-line text boxes improved to no longer insert extra line breaks. If this is not desirable, the app can have the old behavior when running on .NET Framework 4.5 by targeting the .NET Framework 4.0.

Name Value
Scope Minor
Version 4.5
Type Retargeting

Throttle concurrent requests per session

Details

In the .NET Framework 4.6.2 and earlier, ASP.NET executes requests with the same Sessionid sequentially, and ASP.NET always issues the Sessionid through cookies by default. If a page takes a long time to respond, it will significantly degrade server performance just by pressing F5 on the browser. In the fix, we added a counter to track the queued requests and terminate the requests when they exceed a specified limit. The default value is 50. If the limit is reached, a warning will be logged in the event log, and an HTTP 500 response may be recorded in the IIS log.

Suggestion

To restore the old behavior, you can add the following setting to your web.config file to opt out of the new behavior.

<appSettings>
    <add key="aspnet:RequestQueueLimitPerSession" value="2147483647"/>
</appSettings>
Name Value
Scope Edge
Version 4.7
Type Retargeting

WebUtility.HtmlEncode and WebUtility.HtmlDecode round-trip BMP correctly

Details

For applications that target the .NET Framework 4.5, characters that are outside the Basic Multilingual Plane (BMP) round-trip correctly when they are passed to the HtmlDecode(String) methods.

Suggestion

This change should have no effect on current applications, but to restore the original behavior, set the targetFramework attribute of the <httpRuntime> element to a string other than "4.5". You can also set the unicodeEncodingConformance and unicodeDecodingConformance attributes of the <webUtility> configuration element to control this behavior independently of the targeted version of the .NET Framework.

Name Value
Scope Edge
Version 4.5
Type Retargeting

Affected APIs

ClickOnce

ClickOnce supports SHA-256 on 4.0-targeted apps

Details

Previously, a ClickOnce app with a certificate signed with SHA-256 would require .NET Framework 4.5 or later to be present, even if the app targeted 4.0. Now, .NET Framework 4.0-targeted ClickOnce apps can run on .NET Framework 4.0, even if signed with SHA-256.

Suggestion

This change removes that dependency and allows SHA-256 certificates to be used to sign ClickOnce apps that target .NET Framework 4 and earlier versions.

Name Value
Scope Minor
Version 4.6
Type Retargeting

Core

AesCryptoServiceProvider decryptor provides a reusable transform

Details

Starting with apps that target the .NET Framework 4.6.2, the AesCryptoServiceProvider decryptor provides a reusable transform. After a call to System.Security.Cryptography.CryptoAPITransform.TransformFinalBlock(Byte[], Int32, Int32), the transform is reinitialized and can be reused. For apps that target earlier versions of the .NET Framework, attempting to reuse the decryptor by calling System.Security.Cryptography.CryptoAPITransform.TransformBlock(Byte[], Int32, Int32, Byte[], Int32) after a call to System.Security.Cryptography.CryptoAPITransform.TransformFinalBlock(Byte[], Int32, Int32) throws a CryptographicException or produces corrupted data.

Suggestion

The impact of this change should be minimal, since this is the expected behavior.Applications that depend on the previous behavior can opt out of it using it by adding the following configuration setting to the <runtime> section of the application's configuration file:

<runtime>
<AppContextSwitchOverrides value="Switch.System.Security.Cryptography.AesCryptoServiceProvider.DontCorrectlyResetDecryptor=true"/>
</runtime>

In addition, applications that target a previous version of the .NET Framework but are running under a version of the .NET Framework starting with .NET Framework 4.6.2 can opt in to it by adding the following configuration setting to the <runtime> section of the application's configuration file:

<runtime>
<AppContextSwitchOverrides value="Switch.System.Security.Cryptography.AesCryptoServiceProvider.DontCorrectlyResetDecryptor=false"/>
</runtime>
Name Value
Scope Minor
Version 4.6.2
Type Retargeting

Affected APIs

Allow Unicode Bidirectional Control Characters in URIs

Details

Unicode specifies several special control characters used to specify the orientation of text. In previous versions of the .NET Framework, these characters were incorrectly stripped from all URIs even if they were present in their percent-encoded form. In order to better follow RFC 3987, we now allow these characters in URIs. When found unencoded in a URI, they are percent-encoded. When found percent-encoded they are left as-is.

Suggestion

For applications that target versions of .NET Framework starting with 4.7.2, support for Unicode bidirectional characters is enabled by default. If this change is undesirable, you can disable it by adding the following AppContextSwitchOverrides switch to the <runtime> section of the application configuration file:

<runtime>
<AppContextSwitchOverrides value="Switch.System.Uri.DontKeepUnicodeBidiFormattingCharacters=true" />
</runtime>

For applications that target earlier versions of the .NET Framework but are running under versions starting with .NET Framework 4.7.2, support for Unicode bidirectional characters is disabled by default. You can enable it by adding the following AppContextSwitchOverrides switch to the <runtime> section of the application configuration file::

<runtime>
<AppContextSwitchOverrides value="Switch.System.Uri.DontKeepUnicodeBidiFormattingCharacters=false" />
</runtime>
Name Value
Scope Minor
Version 4.7.2
Type Retargeting

Affected APIs

Calls to ClaimsIdentity constructors

Details

Starting with the .NET Framework 4.6.2, there is a change in how ClaimsIdentity constructors with an System.Security.Principal.IIdentity parameter set the System.Security.Claims.ClaimsIdentity.Actor property. If the System.Security.Principal.IIdentity argument is a ClaimsIdentity object, and the System.Security.Claims.ClaimsIdentity.Actor property of that ClaimsIdentity object is not null, the System.Security.Claims.ClaimsIdentity.Actor property is attached by using the Clone() method. In the Framework 4.6.1 and earlier versions, the System.Security.Claims.ClaimsIdentity.Actor property is attached as an existing reference.Because of this change, starting with the .NET Framework 4.6.2, the System.Security.Claims.ClaimsIdentity.Actor property of the new ClaimsIdentity object is not equal to the System.Security.Claims.ClaimsIdentity.Actor property of the constructor's System.Security.Principal.IIdentity argument. In the .NET Framework 4.6.1 and earlier versions, it is equal.

Suggestion

If this behavior is undesirable, you can restore the previous behavior by setting the Switch.System.Security.ClaimsIdentity.SetActorAsReferenceWhenCopyingClaimsIdentity switch in your application configuration file to true. This requires that you add the following to the <runtime> section of your web.config file:

<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.Security.ClaimsIdentity.SetActorAsReferenceWhenCopyingClaimsIdentity=true" />
  </runtime>
</configuration>
Name Value
Scope Edge
Version 4.6.2
Type Retargeting

Affected APIs

Change in path separator character in FullName property of ZipArchiveEntry objects

Details

For apps that target the .NET Framework 4.6.1 and later versions, the path separator character has changed from a backslash ("\") to a forward slash ("/") in the FullName property of ZipArchiveEntry objects created by overloads of the CreateFromDirectory method. The change brings the .NET implementation into conformity with section 4.4.17.1 of the .ZIP File Format Specification and allows .ZIP archives to be decompressed on non-Windows systems.
Decompressing a zip file created by an app that targets a previous version of the .NET Framework on non-Windows operating systems such as the Macintosh fails to preserve the directory structure. For example, on the Macintosh, it creates a set of files whose filename concatenates the directory path, along with any backslash ("\") characters, and the filename. As a result, the directory structure of decompressed files is not preserved.

Suggestion

The impact of this change on .ZIP files that are decompressed on the Windows operating system by APIs in the .NET Framework System.IO namespace should be minimal, since these APIs can seamlessly handle either a forward slash ("/") or a backslash ("\") as the path separator character.
If this change is undesirable, you can opt out of it by adding a configuration setting to the <runtime> section of your application configuration file. The following example shows both the <runtime> section and the Switch.System.IO.Compression.ZipFile.UseBackslash opt-out switch:

<runtime>
  <AppContextSwitchOverrides value="Switch.System.IO.Compression.ZipFile.UseBackslash=true" />
</runtime>

In addition, apps that target previous versions of the .NET Framework but are running on the .NET Framework 4.6.1 and later versions can opt in to this behavior by adding a configuration setting to the <runtime> section of the application configuration file. The following shows both the <runtime> section and the Switch.System.IO.Compression.ZipFile.UseBackslash opt-in switch.

<runtime>
  <AppContextSwitchOverrides value="Switch.System.IO.Compression.ZipFile.UseBackslash=false" />
</runtime>
Name Value
Scope Edge
Version 4.6.1
Type Retargeting

Affected APIs

Changes in path normalization

Details

Starting with apps that target the .NET Framework 4.6.2, the way in which the runtime normalizes paths has changed.Normalizing a path involves modifying the string that identifies a path or file so that it conforms to a valid path on the target operating system. Normalization typically involves:

  • Canonicalizing component and directory separators.
  • Applying the current directory to a relative path.
  • Evaluating the relative directory (.) or the parent directory (..) in a path.
  • Trimming specified characters. Starting with apps that target the .NET Framework 4.6.2, the following changes in path normalization are enabled by default:
    • The runtime defers to the operating system's GetFullPathName function to normalize paths.
  • Normalization no longer involves trimming the end of directory segments (such as a space at the end of a directory name).
  • Support for device path syntax in full trust, including \\.\ and, for file I/O APIs in mscorlib.dll, \\?\.
  • The runtime does not validate device syntax paths.
  • The use of device syntax to access alternate data streams is supported. These changes improve performance while allowing methods to access previously inaccessible paths. Apps that target the .NET Framework 4.6.1 and earlier versions but are running under the .NET Framework 4.6.2 or later are unaffected by this change.

Suggestion

Apps that target the .NET Framework 4.6.2 or later can opt out of this change and use legacy normalization by adding the following to the <runtime> section of the application configuration file:

<runtime>
  <AppContextSwitchOverrides value="Switch.System.IO.UseLegacyPathHandling=true" />
</runtime>

Apps that target the .NET Framework 4.6.1 or earlier but are running on the .NET Framework 4.6.2 or later can enable the changes to path normalization by adding the following line to the <runtime> section of the application .configuration file:

<runtime>
  <AppContextSwitchOverrides value="Switch.System.IO.UseLegacyPathHandling=false" />
</runtime>
Name Value
Scope Minor
Version 4.6.2
Type Retargeting

DeflateStream uses native APIs for decompression

Details

Starting with the .NET Framework 4.7.2, the implementation of decompression in the T:System.IO.Compression.DeflateStream class has changed to use native Windows APIs by default. Typically, this results in a substantial performance improvement. All .NET applications targeting the .NET Framework version 4.7.2 or higher use the native implementation.This change might result in some differences in behavior, which include:

  • Exception messages may be different. However, the type of exception thrown remains the same.
  • Some special situations, such as not having enough memory to complete an operation, may be handled differently.
  • There are known differences for parsing gzip header (note: only GZipStream set for decompression is affected):
  • Exceptions when parsing invalid headers may be thrown at different times.
  • The native implementation enforces that values for some reserved flags inside the gzip header (i.e. FLG) are set according to the specification, which may cause it to throw an exception where previously invalid values were ignored.

Suggestion

If decompression with native APIs has adversely affected the behavior of your app, you can opt out of this feature by adding the Switch.System.IO.Compression.DoNotUseNativeZipLibraryForDecompression switch to the runtime section of your app.config file and setting it to true:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.IO.Compression.DoNotUseNativeZipLibraryForDecompression=true" />
  </runtime>
</configuration>
Name Value
Scope Minor
Version 4.7.2
Type Retargeting

Affected APIs

Ensure System.Uri uses a consistent reserved character set

Details

In System.Uri, certain percent-encoded characters that were sometimes decoded are now consistently left encoded. This occurs across the properties and methods that access the path, query, fragment, or userinfo components of the URI. The behavior will change only when both of the following are true:

  • The URI contains the encoded form of any of the following reserved characters: :, ', (, ), ! or *.
  • The URI contains a Unicode or encoded non-reserved character. If both of the above are true, the encoded reserved characters are left encoded. In previous versions of the .NET Framework, they are decoded.

Suggestion

For applications that target versions of .NET Framework starting with 4.7.2, the new decoding behavior is enabled by default. If this change is undesirable, you can disable it by adding the following AppContextSwitchOverrides switch to the <runtime> section of the application configuration file:

<runtime>
  <AppContextSwitchOverrides value="Switch.System.Uri.DontEnableStrictRFC3986ReservedCharacterSets=true" />
</runtime>

For applications that target earlier versions of the .NET Framework but are running under versions starting with .NET Framework 4.7.2, the new decoding behavior is disabled by default. You can enable it by adding the following AppContextSwitchOverrides switch to the <runtime> section of the application configuration file:

<runtime>
  <AppContextSwitchOverrides value="Switch.System.Uri.DontEnableStrictRFC3986ReservedCharacterSets=false" />
</runtime>
Name Value
Scope Minor
Version 4.7.2
Type Retargeting

Affected APIs

Foreach iterator variable is now scoped within the iteration, so closure capturing semantics are different (in C#5)

Details

Beginning with C# 5 (Visual Studio 2012), foreach iterator variables are scoped within the iteration. This can cause breaks if code was previously depending on the variables to not be included in the foreach's closure. The symptom of this change is that an iterator variable passed to a delegate is treated as the value it has at the time the delegate is created, rather than the value it has at the time the delegate is invoked.

Suggestion

Ideally, code should be updated to expect the new compiler behavior. If the old semantics are required, the iterator variable can be replaced with a separate variable which is explicitly placed outside of the loop's scope.

Name Value
Scope Major
Version 4.5
Type Retargeting

IAsyncResult.CompletedSynchronously property must be correct for the resulting task to complete

Details

When calling TaskFactory.FromAsync, the implementation of the CompletedSynchronously property must be correct for the resulting task to complete. That is, the property must return true if, and only if, the implementation completed synchronously. Previously, the property was not checked.

Suggestion

If System.IAsyncResult implementations correctly return true for the System.IAsyncResult.CompletedSynchronously property only when a task completed synchronously, then no break will be observed. Users should review System.IAsyncResult implementations they own (if any) to ensure that they correctly evaluate whether a task completed synchronously or not.

Name Value
Scope Edge
Version 4.5
Type Retargeting

Affected APIs

List<T>.ForEach can throw exception when modifying list item

Details

Beginning in .NET Framework 4.5, a ForEach(Action<T>) enumerator will throw an System.InvalidOperationException exception if an element in the calling collection is modified. Previously, this would not throw an exception but could lead to race conditions.

Suggestion

Ideally, code should be fixed to not modify lists while enumerating their elements because that is never a safe operation. To revert to the previous behavior, though, an app may target .NET Framework 4.0.

Name Value
Scope Edge
Version 4.5
Type Retargeting

Affected APIs

Long path support

Details

Starting with apps that target the .NET Framework 4.6.2, long paths (of up to 32K characters) are supported, and the 260-character (or MAX_PATH) limitation on path lengths has been removed.For apps that are recompiled to target the .NET Framework 4.6.2, code paths that previously threw a System.IO.PathTooLongException because a path exceeded 260 characters will now throw a System.IO.PathTooLongException only under the following conditions:

  • The length of the path is greater than MaxValue (32,767) characters.
  • The operating system returns COR_E_PATHTOOLONG or its equivalent. For apps that target the .NET Framework 4.6.1 and earlier versions, the runtime automatically throws a System.IO.PathTooLongException whenever a path exceeds 260 characters.

Suggestion

For apps that target the .NET Framework 4.6.2, you can opt out of long path support if it is not desirable by adding the following to the <runtime> section of your app.config file:

<runtime>
  <AppContextSwitchOverrides value="Switch.System.IO.BlockLongPaths=true" />
</runtime>

For apps that target earlier versions of the .NET Framework but run on the .NET Framework 4.6.2 or later, you can opt in to long path support by adding the following to the <runtime> section of your app.config file:

<runtime>
  <AppContextSwitchOverrides value="Switch.System.IO.BlockLongPaths=false" />
</runtime>
Name Value
Scope Minor
Version 4.6.2
Type Retargeting

ObsoleteAttribute exports as both ObsoleteAttribute and DeprecatedAttribute in WinMD scenarios

Details

When you create a Windows Metadata library (.winmd file), the System.ObsoleteAttribute attribute is exported as both System.ObsoleteAttribute and Windows.Foundation.DeprecatedAttribute.

Suggestion

Recompilation of existing source code that uses the System.ObsoleteAttribute attribute may generate warnings when consuming that code from C++/CX or JavaScript.We do not recommend applying both System.ObsoleteAttribute and Windows.Foundation.DeprecatedAttribute to code in managed assemblies; it may result in build warnings.

Name Value
Scope Edge
Version 4.5.1
Type Retargeting

Path colon checks are stricter

Details

In .NET Framework 4.6.2, a number of changes were made to support previously unsupported paths (both in length and format). Checks for proper drive separator (colon) syntax were made more correct, which had the side effect of blocking some URI paths in a few select Path APIs where they used to be tolerated.

Suggestion

If passing a URI to affected APIs, modify the string to be a legal path first.

  • Remove the scheme from URLs manually (e.g. remove file:// from URLs)

    Alternatively, you can opt out of the new path normalization by setting the Switch.System.IO.UseLegacyPathHandling AppContext switch to true.

    Name Value
    Scope Edge
    Version 4.6.2
    Type Retargeting

    Affected APIs

    Resgen refuses to load content from the web

    Details

    .resx files may contain binary formatted input. If you attempt to use resgen to load a file that was downloaded from an untrusted location, it will fail to load the input by default.

    Suggestion

    Resgen users who require loading binary formatted input from untrusted locations can either remove the mark of the web from the input file or apply the opt-out quirk.Add the following registry setting to apply the machine wide opt-out quirk: [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft.NETFramework\SDK] "AllowProcessOfUntrustedResourceFiles"="true"

    Name Value
    Scope Edge
    Version 4.7.2
    Type Retargeting

    SerialPort background thread exceptions

    Details

    Background threads created with SerialPort streams no longer terminate the process when OS exceptions are thrown.
    In applications that target the .NET Framework 4.7 and earlier versions, a process is terminated when an operating system exception is thrown on a background thread created with a SerialPort stream.
    In applications that target the .NET Framework 4.7.1 or a later version, background threads wait for OS events related to the active serial port and could crash in some cases, such as sudden removal of the serial port.

    Suggestion

    For apps that target the .NET Framework 4.7.1, you can opt out of the exception handling if it is not desirable by adding the following to the <runtime> section of your app.config file:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.IO.Ports.DoNotCatchSerialStreamThreadExceptions=true" />
    </runtime>
    

    For apps that target earlier versions of the .NET Framework but run on the .NET Framework 4.7.1 or later, you can opt in to the exception handling by adding the following to the <runtime> section of your app.config file:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.IO.Ports.DoNotCatchSerialStreamThreadExceptions=false" />
    </runtime>
    
    Name Value
    Scope Minor
    Version 4.7.1
    Type Retargeting

    Affected APIs

    ServiceBase doesn't propagate OnStart exceptions

    Details

    In the .NET Framework 4.7 and earlier versions, exceptions thrown on service startup are not propagated to the caller of ServiceBase.Run.
    Starting with applications that target the .NET Framework 4.7.1, the runtime propagates exceptions to ServiceBase.Run for services that fail to start.

    Suggestion

    On service start, if there is an exception, that exception will be propagated. This should help diagnose cases where services fail to start.
    If this behavior is undesirable, you can opt out of it by adding the following <AppContextSwitchOverrides> element to the <runtime> section of your application configuration file:

    <AppContextSwitchOverrides value="Switch.System.ServiceProcess.DontThrowExceptionsOnStart=true" />
    

    If your application targets an earlier version than 4.7.1 but you want to have this behavior, add the following <AppContextSwitchOverrides> element to the <runtime> section of your application configuration file:

    <AppContextSwitchOverrides value="Switch.System.ServiceProcess.DontThrowExceptionsOnStart=false" />
    
    Name Value
    Scope Minor
    Version 4.7.1
    Type Retargeting

    Affected APIs

    Stack traces obtained when using portable PDBs now include source file and line information if requested

    Details

    Starting with .NET Framework 4.7.2, stack traces obtained when using portable PDBs include source file and line information when requested. In versions prior to .NET Framework 4.7.2, source file and line information would be unavailable when using portable PDBs even if explicitly requested.

    Suggestion

    For applications that target the .NET Framework 4.7.2, you can opt out of the source file and line information when using portable PDBs if it is not desirable by adding the following to the <runtime> section of your app.config file:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.Diagnostics.IgnorePortablePDBsInStackTraces=true" />
    </runtime>
    

    For applications that target earlier versions of the .NET Framework but run on the .NET Framework 4.7.2 or later, you can opt in to the source file and line information when using portable PDBs by adding the following to the <runtime> section of your app.config file:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.Diagnostics.IgnorePortablePDBsInStackTraces=false" />
    </runtime>
    
    Name Value
    Scope Edge
    Version 4.7.2
    Type Retargeting

    Affected APIs

    System.Uri parsing adheres to RFC 3987

    Details

    URI parsing has changed in several ways in .NET Framework 4.5. Note, however, that these changes only affect code targeting .NET Framework 4.5. If a binary targets .NET Framework 4.0, the old behavior will be observed. Changes to URI parsing in .NET Framework 4.5 include:

    • URI parsing will perform normalization and character checking according to the latest IRI rules in RFC 3987.
    • Unicode normalization form C will only be performed on the host portion of the URI.
    • Invalid mailto: URIs will now cause an exception.
    • Trailing dots at the end of a path segment are now preserved.
    • file:// URIs do not escape the ? character.
    • Unicode control characters U+0080 through U+009F are not supported.
    • Comma characters , or %2c are not automatically unescaped.

    Suggestion

    If the old .NET Framework 4.0 URI parsing semantics are necessary (they often aren't), they can be used by targeting .NET Framework 4.0. This can be accomplished by using a System.Runtime.Versioning.TargetFrameworkAttribute on the assembly, or through Visual Studio's project system UI in the 'project properties' page.

    Name Value
    Scope Major
    Version 4.5
    Type Retargeting

    Affected APIs

    System.Uri.IsWellFormedUriString method returns false for relative URIs with a colon char in first segment

    Details

    Beginning with the .NET Framework 4.5, IsWellFormedUriString(String, UriKind) will treat relative URIs with a : in their first segment as not well formed. This is a change from System.Uri.IsWellFormedUriString(String, UriKind) behavior in the .NET Framework 4.0 that was made to conform to RFC3986.

    Suggestion

    This change (like many other URI changes) will only affect applications targeting the .NET Framework 4.5 (or later). To keep using the old behavior, target the app against the .NET Framework 4.0. Alternatively, scan URI's prior to calling System.Uri.IsWellFormedUriString(String, UriKind) looking for : characters that you may want to remove for validation purposes, if the old behavior is desirable.

    Name Value
    Scope Minor
    Version 4.5
    Type Retargeting

    Affected APIs

    Entity Framework

    Entity Framework version must match the .NET Framework version

    Details

    The Entity Framework (EF) version should be matched with the .NET Framework version. Entity Framework 5 is recommended for .NET Framework 4.5. There are some known issues with EF 4.x in a .NET Framework 4.5 project around System.ComponentModel.DataAnnotations. In .NET Framework 4.5, these were moved to a different assembly, so there are issues determining which annotations to use.

    Suggestion

    Upgrade to Entity Framework 5 for .NET Framework 4.5

    Name Value
    Scope Major
    Version 4.5
    Type Retargeting

    JIT

    IL ret not allowed in a try region

    Details

    Unlike the JIT64 just-in-time compiler, RyuJIT (used in .NET Framework 4.6) does not allow an IL ret instruction in a try region. Returning from a try region is disallowed by the ECMA-335 specification, and no known managed compiler generates such IL. However, the JIT64 compiler will execute such IL if it is generated using reflection emit.

    Suggestion

    If an app is generating IL that includes a ret opcode in a try region, the app may target .NET Framework 4.5 to use the old JIT and avoid this break. Alternatively, the generated IL may be updated to return after the try region.

    Name Value
    Scope Edge
    Version 4.6
    Type Retargeting

    New 64-bit JIT compiler in the .NET Framework 4.6

    Details

    Starting with the .NET Framework 4.6, a new 64-bit JIT compiler is used for just-in-time compilation. In some cases, an unexpected exception is thrown or a different behavior is observed than if an app is run using the 32-bit compiler or the older 64-bit JIT compiler. This change does not affect the 32-bit JIT compiler. The known differences include the following:

    • Under certain conditions, an unboxing operation may throw a NullReferenceException in Release builds with optimization turned on.
    • In some cases, execution of production code in a large method body may throw a StackOverflowException.
    • Under certain conditions, structures passed to a method are treated as reference types rather than as value types in Release builds. One of the manifestations of this issue is that the individual items in a collection appear in an unexpected order.
    • Under certain conditions, the comparison of UInt16 values with their high bit set is incorrect if optimization is enabled.
    • Under certain conditions, particularly when initializing array values, memory initialization by the OpCodes.Initblk IL instruction may initialize memory with an incorrect value. This can result either in an unhandled exception or incorrect output.
    • Under certain rare conditions, a conditional bit test can return the incorrect Boolean value or throw an exception if compiler optimizations are enabled.
    • Under certain conditions, if an if statement is used to test for a condition before entering a try block and in the exit from the try block, and the same condition is evaluated in the catch or finally block, the new 64-bit JIT compiler removes the if condition from the catch or finally block when it optimizes code. As a result, code inside the if statement in the catch or finally block is executed unconditionally.

    Suggestion

    Mitigation of known issues
    If you encounter the issues listed above, you can address them by doing any of the following:

    • Upgrade to the .NET Framework 4.6.2. The new 64-bit compiler included with the .NET Framework 4.6.2 addresses each of these known issues.

    • Ensure that your version of Windows is up to date by running Windows Update. Service updates to the .NET Framework 4.6 and 4.6.1 address each of these issues except the NullReferenceException in an unboxing operation.

    • Compile with the older 64-bit JIT compiler. See the Mitigation of other issues section for more information on how to do this. Mitigation of other issues
      If you encounter any other difference in behavior between code compiled with the older 64-bit compiler and the new 64-bit JIT compiler, or between the debug and release versions of your app that are both compiled with the new 64-bit JIT compiler, you can do the following to compile your app with the older 64-bit JIT compiler:

    • On a per-application basis, you can add the < element to your application's configuration file. The following disables compilation with the new 64-bit JIT compiler and instead uses the legacy 64-bit JIT compiler.

      <?xml version ="1.0"?>
      <configuration>
        <runtime>
         <useLegacyJit enabled="1" />
        </runtime>
      </configuration>
      
    • On a per-user basis, you can add a REG_DWORD value named useLegacyJit to the HKEY_CURRENT_USER\SOFTWARE\Microsoft\.NETFramework key of the registry. A value of 1 enables the legacy 64-bit JIT compiler; a value of 0 disables it and enables the new 64-bit JIT compiler.

    • On a per-machine basis, you can add a REG_DWORD value named useLegacyJit to the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework key of the registry. A value of 1 enables the legacy 64-bit JIT compiler; a value of 0 disables it and enables the new 64-bit JIT compiler. You can also let us know about the problem by reporting a bug on Microsoft Connect.

    Name Value
    Scope Edge
    Version 4.6
    Type Retargeting

    MSBuild

    ResolveAssemblyReference task now warns of dependencies with the wrong architecture

    Details

    The task emits a warning, MSB3270, which indicates that a reference or any of its dependencies does not match the app's architecture. For example, this occurs if an app that was compiled with the AnyCPU option includes an x86 reference. Such a scenario could result in an app failure at run time (in this case, if the app is deployed as an x64 process).

    Suggestion

    There are two areas of impact:

    • Recompilation generates warnings that did not appear when the app was compiled under a previous version of MSBuild. However, because the warning identifies a possible source of runtime failure, it should be investigated and addressed.
    • If warnings are treated as errors, the app will fail to compile.
    Name Value
    Scope Minor
    Version 4.5.1
    Type Retargeting

    Networking

    Certificate EKU OID validation

    Details

    Starting with .NET Framework 4.6, the SslStream or ServicePointManager classes perform enhanced key use (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. EKU OID validation uses remote certificate callbacks to ensure that the remote certificate has the correct OIDs for the intended purpose.

    Suggestion

    If this change is undesirable, you can disable certificate EKU OID validation by adding the following switch to the <AppContextSwitchOverrides> in the ` of your app configuration file:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.Net.DontCheckCertificateEKUs=true" />
    </runtime>
    

    Important

    This setting is provided for backward compatibility only. Its use is otherwise not recommended.

    Name Value
    Scope Minor
    Version 4.6
    Type Retargeting

    Affected APIs

    Default value of ServicePointManager.SecurityProtocol is SecurityProtocolType.System.Default

    Details

    Starting with apps that target the .NET Framework 4.7, the default value of the ServicePointManager.SecurityProtocol property is SecurityProtocolType.SystemDefault. This change allows .NET Framework networking APIs based on SslStream (such as FTP, HTTPS, and SMTP) to inherit the default security protocols from the operating system instead of using hard-coded values defined by the .NET Framework. The default varies by operating system and any custom configuration performed by the system administrator. For information on the default SChannel protocol in each version of the Windows operating system, see Protocols in TLS/SSL (Schannel SSP).

    For applications that target an earlier version of the .NET Framework, the default value of the ServicePointManager.SecurityProtocol property depends on the version of the .NET Framework targeted. See the Networking section of Retargeting Changes for Migration from .NET Framework 4.5.2 to 4.6 for more information.

    Suggestion

    This change affects applications that target the .NET Framework 4.7 or later versions. If you prefer to use a defined protocol rather than relying on the system default, you can explicitly set the value of the ServicePointManager.SecurityProtocol property. If this change is undesirable, you can opt out of it by adding a configuration setting to the <runtime> section of your application configuration file. The following example shows both the <runtime> section and the Switch.System.Net.DontEnableSystemDefaultTlsVersions opt-out switch:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.Net.DontEnableSystemDefaultTlsVersions=true" />
    </runtime>
    
    Name Value
    Scope Minor
    Version 4.7
    Type Retargeting

    Affected APIs

    Only Tls 1.0, 1.1 and 1.2 protocols supported in System.Net.ServicePointManager and System.Net.Security.SslStream

    Details

    Starting with the .NET Framework 4.6, the ServicePointManager and SslStream classes are only allowed to use one of the following three protocols: Tls1.0, Tls1.1, or Tls1.2. The SSL3.0 protocol and RC4 cipher are not supported.

    Suggestion

    The recommended mitigation is to upgrade the sever-side app to Tls1.0, Tls1.1, or Tls1.2. If this is not feasible, or if client apps are broken, the System.AppContext class can be used to opt out of this feature in either of two ways:

    • By programmatically setting compat switches on the System.AppContext, as explained here.
    • By adding the following line to the <runtime> section of the app.config file:
    <AppContextSwitchOverrides value="Switch.System.Net.DontEnableSchUseStrongCrypto=true"/>
    
    Name Value
    Scope Minor
    Version 4.6
    Type Retargeting

    Affected APIs

    SslStream supports TLS Alerts

    Details

    After a failed TLS handshake, an System.IO.IOException with an inner System.ComponentModel.Win32Exception exception will be thrown by the first I/O Read/Write operation. The System.ComponentModel.Win32Exception.NativeErrorCode code for the System.ComponentModel.Win32Exception can be mapped to the TLS Alert from the remote party using the Schannel error codes for TLS and SSL alerts.For more information, see RFC 2246: Section 7.2.2 Error alerts.
    The behavior in .NET Framework 4.6.2 and earlier is that the transport channel (usually TCP connection) will timeout during either Write or Read if the other party failed the handshake and immediately afterwards rejected the connection.

    Suggestion

    Applications calling network I/O APIs such as Read(Byte[], Int32, Int32)/Write(Byte[], Int32, Int32) should handle IOException or System.TimeoutException.
    The TLS Alerts feature is enabled by default starting with .NET Framework 4.7. Applications targeting versions of the .NET Framework from 4.0 through 4.6.2 running on a .NET Framework 4.7 or higher system will have the feature disabled to preserve compatibility.
    The following configuration API is available to enable or disable the feature for .NET Framework 4.6 and later applications running on .NET Framework 4.7 or later.

    • Programmatically: Must be the very first thing the application does since ServicePointManager will initialize only once:

      AppContext.SetSwitch("TestSwitch.LocalAppContext.DisableCaching", true);
      
      // Set to 'false' to enable the feature in .NET Framework 4.6 - 4.6.2.
      AppContext.SetSwitch("Switch.System.Net.DontEnableTlsAlerts", true);
      
    • AppConfig:

      <runtime>
        <AppContextSwitchOverrides value="Switch.System.Net.DontEnableTlsAlerts=true"/>
        <!-- Set to 'false' to enable the feature in .NET Framework 4.6 - 4.6.2. -->
      </runtime>
      
    • Registry key (machine global): Set the Value to false to enable the feature in .NET Framework 4.6 - 4.6.2.

      Key: HKLM\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\AppContext\Switch.System.Net.DontEnableTlsAlerts
      - Type: String
      - Value: "true"
      
    Name Value
    Scope Edge
    Version 4.7
    Type Retargeting

    Affected APIs

    TLS 1.x by default passes the SCH_SEND_AUX_RECORD flag to the underlying SCHANNEL API

    Details

    When using TLS 1.x, the .NET Framework relies on the underlying Windows SCHANNEL API. Starting with .NET Framework 4.6, the SCH_SEND_AUX_RECORD flag is passed by default to SCHANNEL. This causes SCHANNEL to split data to be encrypted into two separate records, the first as a single byte and the second as n-1 bytes.In rare cases, this breaks communication between clients and existing servers that make the assumption that the data resides in a single record.

    Suggestion

    If this change breaks communication with an existing server, you can disable sending the SCH_SEND_AUX_RECORD flag and restore the previous behavior of not splitting data into separate records by adding the following switch to the <AppContextSwitchOverrides> element in the <runtime> section of your app configuration file:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.Net.DontEnableSchSendAuxRecord=true" />
    </runtime>
    

    Important

    This setting is provided for backward compatibility only. Its use is otherwise not recommended.

    Name Value
    Scope Edge
    Version 4.6
    Type Retargeting

    Affected APIs

    Security

    CspParameters.ParentWindowHandle now expects HWND value

    Details

    The ParentWindowHandle value, introduced in .NET Framework 2.0, allows an application to register a parent window handle value such that any UI required to access the key (such as a PIN prompt or consent dialog) opens as a modal child to the specified window.Starting with apps that target the .NET Framework 4.7, a Windows Forms application can set the ParentWindowHandle property with code like the following:

    cspParameters.ParentWindowHandle = form.Handle;
    

    In previous versions of the .NET Framework, the value was expected to be an System.IntPtr representing a location in memory where the HWND value resided. Setting the property to form.Handle on Windows 7 and earlier versions had no effect, but on Windows 8 and later versions, it results in a "System.Security.Cryptography.CryptographicException: The parameter is incorrect."

    Suggestion

    Applications targeting .NET Framework 4.7 or higher wishing to register a parent window relationship are encouraged to use the simplified form:

    cspParameters.ParentWindowHandle = form.Handle;
    

    Users who had identified that the correct value to pass was the address of a memory location which held the value form.Handle can opt out of the behavior change by setting the AppContext switch Switch.System.Security.Cryptography.DoNotAddrOfCspParentWindowHandle to true:

    • By programmatically setting compat switches on the AppContext, as explained here.
    • By adding the following line to the <runtime> section of the app.config file:
    <runtime>
     <AppContextSwitchOverrides value="Switch.System.Security.Cryptography.DoNotAddrOfCspParentWindowHandle=true"/>
    </runtime>
    

    Conversely, users who wish to opt in to the new behavior on the .NET Framework 4.7 runtime when the application loads under older .NET Framework versions can set the AppContext switch to false.

    Name Value
    Scope Minor
    Version 4.7
    Type Retargeting

    Affected APIs

    Default SignedXML and SignedXMS algorithms changed to SHA256

    Details

    In the .NET Framework 4.7 and earlier, SignedXML and SignedCMS default to SHA1 for some operations.Starting with the .NET Framework 4.7.1, SHA256 is enabled by default for these operations. This change is necessary because SHA1 is no longer considered to be secure.

    Suggestion

    There are two new context switch values to control whether SHA1 (insecure) or SHA256 is used by default:

    • Switch.System.Security.Cryptography.Xml.UseInsecureHashAlgorithms
    • Switch.System.Security.Cryptography.Pkcs.UseInsecureHashAlgorithms For applications that target the .NET Framework 4.7.1 and later versions, if the use of SHA256 is undesirable, you can restore the default to SHA1 by adding the following configuration switch to the runtime section of your app config file:
    <AppContextSwitchOverrides value="Switch.System.Security.Cryptography.Xml.UseInsecureHashAlgorithms=true;Switch.System.Security.Cryptography.Pkcs.UseInsecureHashAlgorithms=true" />
    

    For applications that target the .NET Framework 4.7 and earlier versions, you can opt into this change by adding the following configuration switch to the runtime section of your app config file:

    <AppContextSwitchOverrides value="Switch.System.Security.Cryptography.Xml.UseInsecureHashAlgorithms=false;Switch.System.Security.Cryptography.Pkcs.UseInsecureHashAlgorithms=false" />
    
    Name Value
    Scope Minor
    Version 4.7.1
    Type Retargeting

    Affected APIs

    RSACng now correctly loads RSA keys of non-standard key size

    Details

    In .NET Framework versions prior to 4.6.2, customers with non-standard key sizes for RSA certificates are unable to access those keys via the System.Security.Cryptography.X509Certificates.RSACertificateExtensions.GetRSAPublicKey(X509Certificate2) and System.Security.Cryptography.X509Certificates.RSACertificateExtensions.GetRSAPrivateKey(X509Certificate2) extension methods. A System.Security.Cryptography.CryptographicException with the message "The requested key size is not supported" is thrown. In .NET Framework 4.6.2 this issue has been fixed. Similarly, ImportParameters(RSAParameters) and ImportParameters(RSAParameters) now work with non-standard key sizes without throwing a System.Security.Cryptography.CryptographicException.

    Suggestion

    If there is any exception handling logic that relies on the previous behavior where a System.Security.Cryptography.CryptographicException is thrown when non-standard key sizes are used, consider removing the logic.

    Name Value
    Scope Edge
    Version 4.6.2
    Type Retargeting

    Affected APIs

    SslStream supports TLS Alerts

    Details

    After a failed TLS handshake, an System.IO.IOException with an inner System.ComponentModel.Win32Exception exception will be thrown by the first I/O Read/Write operation. The System.ComponentModel.Win32Exception.NativeErrorCode code for the System.ComponentModel.Win32Exception can be mapped to the TLS Alert from the remote party using the Schannel error codes for TLS and SSL alerts.For more information, see RFC 2246: Section 7.2.2 Error alerts.
    The behavior in .NET Framework 4.6.2 and earlier is that the transport channel (usually TCP connection) will timeout during either Write or Read if the other party failed the handshake and immediately afterwards rejected the connection.

    Suggestion

    Applications calling network I/O APIs such as Read(Byte[], Int32, Int32)/Write(Byte[], Int32, Int32) should handle IOException or System.TimeoutException.
    The TLS Alerts feature is enabled by default starting with .NET Framework 4.7. Applications targeting versions of the .NET Framework from 4.0 through 4.6.2 running on a .NET Framework 4.7 or higher system will have the feature disabled to preserve compatibility.
    The following configuration API is available to enable or disable the feature for .NET Framework 4.6 and later applications running on .NET Framework 4.7 or later.

    • Programmatically: Must be the very first thing the application does since ServicePointManager will initialize only once:

      AppContext.SetSwitch("TestSwitch.LocalAppContext.DisableCaching", true);
      
      // Set to 'false' to enable the feature in .NET Framework 4.6 - 4.6.2.
      AppContext.SetSwitch("Switch.System.Net.DontEnableTlsAlerts", true);
      
    • AppConfig:

      <runtime>
        <AppContextSwitchOverrides value="Switch.System.Net.DontEnableTlsAlerts=true"/>
        <!-- Set to 'false' to enable the feature in .NET Framework 4.6 - 4.6.2. -->
      </runtime>
      
    • Registry key (machine global): Set the Value to false to enable the feature in .NET Framework 4.6 - 4.6.2.

      Key: HKLM\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\AppContext\Switch.System.Net.DontEnableTlsAlerts
      - Type: String
      - Value: "true"
      
    Name Value
    Scope Edge
    Version 4.7
    Type Retargeting

    Affected APIs

    Visual Basic .NET

    VB.NET no longer supports partial namespace qualification for System.Windows APIs

    Details

    Beginning in .NET Framework 4.5.2, VB.NET projects cannot specify System.Windows APIs with partially-qualified namespaces. For example, referring to Windows.Forms.DialogResult will fail. Instead, code must refer to the fully qualified name (DialogResult) or import the specific namespace and refer simply to System.Windows.Forms.DialogResult.

    Suggestion

    Code should be updated to refer to System.Windows APIs either with simple names (and importing the relevant namespace) or with fully qualified names.

    Name Value
    Scope Minor
    Version 4.5.2
    Type Retargeting

    Windows Communication Foundation (WCF)

    Calling CreateDefaultAuthorizationContext with a null argument has changed

    Details

    The implementation of the System.IdentityModel.Policy.AuthorizationContext returned by a call to the System.IdentityModel.Policy.AuthorizationContext.CreateDefaultAuthorizationContext(IList<IAuthorizationPolicy>) with a null authorizationPolicies argument has changed its implementation in the .NET Framework 4.6.

    Suggestion

    In rare cases, WCF apps that use custom authentication may see behavioral differences. In such cases, the previous behavior can be restored in either of two ways:

    • Recompile your app to target an earlier version of the .NET Framework than 4.6. For IIS-hosted services, use the <httpRuntime targetFramework="x.x"> element to target an earlier version of the .NET Framework.

    • Add the following line to the <appSettings> section of your app.config file:

      <add key="appContext.SetSwitch:Switch.System.IdentityModel.EnableCachedEmptyDefaultAuthorizationContext" value="true" />
      
    Name Value
    Scope Minor
    Version 4.6
    Type Retargeting

    Affected APIs

    Deadlock may result when using Reentrant services

    Details

    A deadlock may result in a Reentrant service, which restricts instances of the service to one thread of execution at a time. Services prone to encounter this problem will have the following ServiceBehaviorAttribute in their code:

    [ServiceBehavior(ConcurrencyMode = ConcurrencyMode.Reentrant)]
    

    Suggestion

    To address this issue, you can do the following:

    • Set the service's concurrency mode to ConcurrencyMode.Single or <System.ServiceModel.ConcurrencyMode.Multiple?displayProperty=nameWithType>. For example:
    [ServiceBehavior(ConcurrencyMode = ConcurrencyMode.Reentrant)]
    
    • Install the latest update to the .NET Framework 4.6.2, or upgrade to a later version of the .NET Framework. This disables the flow of the ExecutionContext in OperationContext.Current. This behavior is configurable; it is equivalent to adding the following app setting to your configuration file:
    <appSettings>
      <add key="Switch.System.ServiceModel.DisableOperationContextAsyncFlow" value="true" />
    </appSettings>
    

    The value of Switch.System.ServiceModel.DisableOperationContextAsyncFlow should never be set to false for Reentrant services.

    Name Value
    Scope Minor
    Version 4.6.2
    Type Retargeting

    Affected APIs

    Improved accessibility for some .NET SDK tools

    Details

    In the .NET Framework SDK 4.7.1, the SvcConfigEditor.exe and SvcTraceViewer.exe tools have been improved by fixing varied accessibility issues. Most of these were small issues like a name not being defined or certain UI automation patterns not being implemented correctly. While many users wouldn't be aware of these incorrect values, customers who use assistive technologies like screen readers will find these SDK tools more accessible. Certainly, these fixes change some previous behaviors, like keyboard focus order.In order to get all the accessibility fixes in these tools, you can the following to your app.config file:

    <runtime>
      <AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures=false"/>
    </runtime>
    
    Name Value
    Scope Edge
    Version 4.7.1
    Type Retargeting

    OperationContext.Current may return null when called in a using clause

    Details

    OperationContext.Current may return null and a NullReferenceException may result if all of the following conditions are true:

    using (new OperationContextScope(OperationContext.Current))
    {
        // OperationContext.Current is null.
        OperationContext context = OperationContext.Current;
    
        // ...
    }
    

    Suggestion

    To address this issue, you can do the following:

    • Modify your code as follows to instantiate a new non- null Current object:

      OperationContext ocx = OperationContext.Current;
      using (new OperationContextScope(OperationContext.Current))
      {
          OperationContext.Current = new OperationContext(ocx.Channel);
      
          // ...
      }
      
    • Install the latest update to the .NET Framework 4.6.2, or upgrade to a later version of the .NET Framework. This disables the flow of the ExecutionContext in OperationContext.Current and restores the behavior of WCF applications in the .NET Framework 4.6.1 and earlier versions. This behavior is configurable; it is equivalent to adding the following app setting to your configuration file:

      <appSettings>
        <add key="Switch.System.ServiceModel.DisableOperationContextAsyncFlow" value="true" />
      </appSettings>
      

      If this change is undesirable and your application depends on execution context flowing between operation contexts, you can enable its flow as follows:

      <appSettings>
        <add key="Switch.System.ServiceModel.DisableOperationContextAsyncFlow" value="false" />
      </appSettings>
      
    Name Value
    Scope Edge
    Version 4.6.2
    Type Retargeting

    Affected APIs

    Serialization of control characters with DataContractJsonSerializer is now compatible with ECMAScript V6 and V8

    Details

    In .NET Framework 4.6.2 and earlier versions, the System.Runtime.Serialization.Json.DataContractJsonSerializer did not serialize some special control characters, such as \b, \f, and \t, in a way that was compatible with the ECMAScript V6 and V8 standards. Starting with .NET Framework 4.7, serialization of these control characters is compatible with ECMAScript V6 and V8.

    Suggestion

    For apps that target the .NET Framework 4.7, this feature is enabled by default. If this behavior is not desirable, you can opt out of this feature by adding the following line to the <runtime> section of the app.config or web.config file:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.Runtime.Serialization.DoNotUseECMAScriptV6EscapeControlCharacter=false" />
    </runtime>
    
    Name Value
    Scope Edge
    Version 4.7
    Type Retargeting

    Affected APIs

    WCF binding with the TransportWithMessageCredential security mode

    Details

    Beginning in the .NET Framework 4.6.1, WCF binding that uses the TransportWithMessageCredential security mode can be set up to receive messages with unsigned "to" headers for asymmetric security keys.By default, unsigned "to" headers will continue to be rejected in .NET Framework 4.6.1. They will only be accepted if an application opts into this new mode of operation using the Switch.System.ServiceModel.AllowUnsignedToHeader configuration switch.

    Suggestion

    Because this is an opt-in feature, it should not affect the behavior of existing apps.
    To control whether the new behavior is used or not, use the following configuration setting:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.ServiceModel.AllowUnsignedToHeader=true" />
    </runtime>
    
    Name Value
    Scope Transparent
    Version 4.6.1
    Type Retargeting

    Affected APIs

    WCF message security now is able to use TLS1.1 and TLS1.2

    Details

    Starting in the .NET Framework 4.7, customers can configure either TLS1.1 or TLS1.2 in WCF message security in addition to SSL3.0 and TLS1.0 through application configuration settings.

    Suggestion

    In the .NET Framework 4.7, support for TLS1.1 and TLS1.2 in WCF message security is disabled by default. You can enable it by adding the following line to the <runtime> section of the app.config or web.config file:

    <runtime>
    <AppContextSwitchOverrides value="Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols=false;Switch.System.Net.DontEnableSchUseStrongCrypto=false" />
    </runtime>
    
    Name Value
    Scope Edge
    Version 4.7
    Type Retargeting

    WCF transport security supports certificates stored using CNG

    Details

    Starting with apps that target the .NET Framework 4.6.2, WCF transport security supports certificates stored using the Windows Cryptography Library (CNG). This support is limited to certificates with a public key that has an exponent no more than 32 bits in length. When an application targets the .NET Framework 4.6.2, this feature is on by default.In earlier versions of the .NET Framework, the attempt to use X509 certificates with a CSG key storage provider throws an exception.

    Suggestion

    Apps that target the .NET Framework 4.6.1 and earlier but are running on the .NET Framework 4.6.2 can enable support for CNG certificates by adding the following line to the <runtime> section of the app.config or web.config file:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.ServiceModel.DisableCngCertificates=false" />
    </runtime>
    

    This can also be done programmatically with the following code:

    private const string DisableCngCertificates = @"Switch.System.ServiceModel.DisableCngCertificate";
    
    AppContext.SetSwitch(disableCngCertificates, false);
    
    Const DisableCngCertificates As String = "Switch.System.ServiceModel.DisableCngCertificates"
    AppContext.SetSwitch(disableCngCertificates, False)
    

    Note that, because of this change, any exception handling code that depends on the attempt to initiate secure communication with a CNG certificate to fail will no longer execute.

    Name Value
    Scope Minor
    Version 4.6.2
    Type Retargeting

    X509CertificateClaimSet.FindClaims Considers All claimTypes

    Details

    In apps that target the .NET Framework 4.6.1, if an X509 claim set is initialized from a certificate that has multiple DNS entries in its SAN field, the System.IdentityModel.Claims.X509CertificateClaimSet.FindClaims(String, String) method attempts to match the claimType argument with all the DNS entries.For apps that target previous versions of the .NET Framework, the System.IdentityModel.Claims.X509CertificateClaimSet.FindClaims(String, String) method attempts to match the claimType argument only with the last DNS entry.

    Suggestion

    This change only affects applications targeting the .NET Framework 4.6.1. This change may be disabled (or enabled if targeting pre-4.6.1) with the DisableMultipleDNSEntries compatibility switch.

    Name Value
    Scope Minor
    Version 4.6.1
    Type Retargeting

    Affected APIs

    Windows Forms

    Accessibility improvements in Windows Forms controls for .NET 4.7.2

    Details

    Windows Forms Framework is improving how it works with accessibility technologies to better support Windows Forms customers. These include the following changes:

    • Changes to improve display during High Contrast mode.
    • Changes to improve the keyboard navigation in the DataGridView and MenuStrip controls.
    • Changes to interaction with Narrator.

    Suggestion

    How to opt in or out of these changes In order for the application to benefit from these changes, it must run on the .NET Framework 4.7.2 or later. The application can benefit from these changes in either of the following ways:

    • It is recompiled to target the .NET Framework 4.7.2. These accessibility changes are enabled by default on Windows Forms applications that target the .NET Framework 4.7.2 or later.
    • It targets the .NET Framework 4.7.1 or earlier version and opts out of the legacy accessibility behaviors by adding the following AppContext Switch to the <runtime> section of the app config file and setting it to false, as the following example shows.
    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
      <startup>
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7"/>
      </startup>
      <runtime>
        <!-- AppContextSwitchOverrides value attribute is in the form of 'key1=true/false;key2=true/false  -->
        <AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures=false;Switch.UseLegacyAccessibilityFeatures.2=false" />
      </runtime>
    </configuration>
    

    Note that to opt in to the accessibility features added in .NET Framework 4.7.2, you must also opt in to accessibility features of .NET Framework 4.7.1 as well. Applications that target the .NET Framework 4.7.2 or later and want to preserve the legacy accessibility behavior can opt in to the use of legacy accessibility features by explicitly setting this AppContext switch to true.

    Use of OS-defined colors in High Contrast themes

    • The drop down arrow of the ToolStripDropDownButton now uses OS-defined colors in High Contrast theme.
    • Button, RadioButton and CheckBox controls with FlatStyle set to FlatStyle.Flat or FlatStyle.Popup now use OS-defined colors in High Contrast theme when selected. Previously, text and background colors were not contrasting and were hard to read.
    • Controls contained within a GroupBox that has its Enabled property set to false will now use OS-defined colors in High Contrast theme.
    • The ToolStripButton, ToolStripComboBox, and ToolStripDropDownButton controls have an increased luminosity contrast ratio in High Contrast Mode.
    • DataGridViewLinkCell will by default use OS-defined colors in High Contrast mode for the DataGridViewLinkCell.LinkColor property. NOTE: Windows 10 has changed values for some high contrast system colors. Windows Forms Framework is based on the Win32 framework. For the best experience, run on the latest version of Windows and opt in to the latest OS changes by adding an app.manifest file in a test application and un-commenting the following code:
    <!-- Windows 10 -->
    <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
    

    Improved Narrator support

    • Narrator now announces the value of the ToolStripMenuItem.ShortcutKeys property when announcing the text of a ToolStripMenuItem.
    • Narrator now indicates when a ToolStripMenuItem has its Enabled property set to false.
    • Narrator now gives feedback on the state of a check box when the ListView.CheckBoxes property is set to true.
    • Narrator Scan Mode focus order is now consistent with the visual order of the controls on the ClickOnce download dialog window.

    Improved DataGridView Accessibility support

    Improved Visual cues

    • The RadioButton and CheckBox controls with an empty Text property will now display a focus indicator when they receive focus.

    Improved Property Grid Support

    Name Value
    Scope Major
    Version 4.7.2
    Type Retargeting

    Accessibility improvements in Windows Forms controls

    Details

    Windows Forms is improving how it works with accessibility technologies to better support Windows Forms customers. These include the following changes starting with the .NET Framework 4.7.1:

    • Changes to improve display during High Contrast mode.
    • Changes to improve the property browser experience. Property browser improvements include:
    • Better keyboard navigation through the various drop-down selection windows.
    • Reduced unnecessary tab stops.
    • Better reporting of control types.
    • Improved narrator behavior.
    • Changes to implement missing UI accessibility patterns in controls.

    Suggestion

    How to opt in or out of these changes In order for the application to benefit from these changes, it must run on the .NET Framework 4.7.1 or later. The application can benefit from these changes in either of the following ways:

    • It is recompiled to target the .NET Framework 4.7.1. These accessibility changes are enabled by default on Windows Forms applications that target the .NET Framework 4.7.1 or later.
    • It opts out of the legacy accessibility behaviors by adding the following AppContext switch to the <runtime> section of the app.config file and setting it to false, as the following example shows.
    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
      <startup>
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7"/>
      </startup>
      <runtime>
        <!-- AppContextSwitchOverrides value attribute is in the form of 'key1=true/false;key2=true/false  -->
        <AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures=false" />
      </runtime>
    </configuration>
    

    Applications that target the .NET Framework 4.7.1 or later and want to preserve the legacy accessibility behavior can opt in to the use of legacy accessibility features by explicitly setting this AppContext switch to true.

    For an overview of UI automation, see the UI Automation Overview.

    Added support for UI Automation patterns and properties
    Accessibility clients can take advantage of new WinForms accessibility functionality by using common, publicly described invocation patterns. These patterns are not WinForms-specific. For instance, accessibility clients can call the QueryInterface method on the IAccessible interface (MAAS) to obtain an IServiceProvider interface. If this interface is available, clients can use its QueryService method to request an IAccessibleEx interface. For more information, see Using IAccessibleEx from a Client. Starting with the .NET Framework 4.7.1, IServiceProvider and IAccessibleEx (where applicable) are available for WinForms accessibility objects.

    The .NET Framework 4.7.1 adds support for the following UI automation patterns and properties:

    Use of OS-defined colors in High Contrast themes

    • The Button and CheckBox controls with their FlatStyle property set to FlatStyle.System, which is the default style, now use OS-defined colors in High Contrast theme when selected. Previously, text and background colors were not contrasting and were hard to read.
    • The Button, CheckBox, RadioButton, Label, LinkLabel, and GroupBox controls with their Enabled property set to false used a shaded color to render text in High Contrast themes, resulting in low contrast against the background. Now these controls use the "Disabled Text" color defined by the OS. This fix applies to controls with the FlatStyle property set to a value other than FlatStyle.System. The latter controls are rendered by the OS.
    • DataGridView now renders a visible rectangle around the content of the cell which has the current focus. Previously, this was not visible in certain High Contrast themes.
    • ToolStripMenuItem controls with their Enabled property set to false now use the "Disabled Text" color defined by the OS.
    • ToolStripMenuItem controls with their Checked property set to true now render the associated check mark in a contrasting system color. Previously the check mark color was not contrasting enough and not visible in High Contrast themes. NOTE: Windows 10 has changed values for some high contrast system colors. Windows Forms Framework is based on the Win32 framework. For the best experience, run on the latest version of Windows and opt in to the latest OS changes by adding an app.manifest file in a test application and un-commenting the following code:
    <!-- Windows 10 -->
    <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
    

    Improved keyboard navigation

    • When a ComboBox control has its DropDownStyle property set to ComboBoxStyle.DropDownList and is the first control in the tab order on the form, it now displays a focus rectangle when the parent form is opened using the keyboard. Before this change, keyboard focus was on this control, but a focus indicator was not rendered.

    Improved Narrator support

    • The MonthCalendar control has added support for assistive technologies to access the control, including the ability for Narrator to read the value of the control when previously it could not.

    • The CheckedListBox control now notifies Narrator when a CheckBox.CheckState property has been changed. Previously, Narrator did not receive notification and as a result users would not be informed that the CheckState property had been updated.

    • The LinkLabel control has changed the way it notifies Narrator of the text of in the control. Previously, Narrator announced this text twice and read "&" symbols as real text even though they are not visible to a user. The duplicated text was removed from the Narrator announcements, as well as unnecessary "&" symbols.

    • The DataGridViewCell control types now correctly report the read-only status to Narrator and other assistive technologies.

    • Narrator is now able to read the System Menu of child windows in [Multiple-Document Interface]~/docs/framework/winforms/advanced/multiple-document-interface-mdi-applications.md) applications.

    • Narrator is now able to read ToolStripMenuItem controls with a ToolStripItem.Enabled property set to false. Previously, Narrator was unable to focus on disabled menu items to read the content.

    Name Value
    Scope Major
    Version 4.8
    Type Retargeting

    Affected APIs

    Application.FilterMessage no longer throws for re-entrant implementations of IMessageFilter.PreFilterMessage

    Details

    Prior to the .NET Framework 4.6.1, calling FilterMessage(Message) with an PreFilterMessage(Message) which called System.Windows.Forms.Application.AddMessageFilter(IMessageFilter) or System.Windows.Forms.Application.RemoveMessageFilter(IMessageFilter) (while also calling DoEvents()) would cause an System.IndexOutOfRangeException.

    Beginning with applications targeting the .NET Framework 4.6.1, this exception is no longer thrown, and re-entrant filters as described above may be used.

    Suggestion

    Be aware that FilterMessage(Message) will no longer throw for the re-entrant PreFilterMessage(Message) behavior described above. This only affects applications targeting the .NET Framework 4.6.1.Apps targeting the .NET Framework 4.6.1 can opt out of this change (or apps targeting older Frameworks may opt in) by using the DontSupportReentrantFilterMessage compatibility switch.

    Name Value
    Scope Edge
    Version 4.6.1
    Type Retargeting

    Affected APIs

    ContextMenuStrip.SourceControl property contains a valid control in the case of nested ToolStripMenuItems

    Details

    In the .NET Framework 4.7.1 and previous versions, the ContextMenuStrip.SourceControl property incorrectly returns null when the user opens the menu from nested ToolStripMenuItem controls. In the .NET Framework 4.7.2 and later, SourceControl property is always set to the actual source control.

    Suggestion

    How to opt in or out of these changes In order for an application to benefit from these changes, it must run on the .NET Framework 4.7.2 or later. The application can benefit from these changes in either of the following ways:

    • It targets the .NET Framework 4.7.2. This change is enabled by default on Windows Forms applications that target the .NET Framework 4.7.2 or later.
    • It targets the .NET Framework 4.7.1 or an earlier version and opts out of the legacy accessibility behaviors by adding the following AppContext Switch to the <runtime> section of the app.config file and setting it to false, as the following example shows.
    <runtime>
      <AppContextSwitchOverrides value="Switch.System.Windows.Forms.UseLegacyContextMenuStripSourceControlValue=false"/>
    </runtime>
    

    Applications that target the .NET Framework 4.7.2 or later, and want to preserve the legacy behavior can opt in to the use of the legacy source control value by explicitly setting this AppContext switch to true.

    Name Value
    Scope Edge
    Version 4.7.2
    Type Retargeting

    Affected APIs

    DataObject.GetData now retrieves data as UTF-8

    Details

    For apps that target the .NET Framework 4 or that run on the .NET Framework 4.5.1 or earlier versions, DataObject.GetData retrieves HTML-formatted data as an ASCII string. As a result, non-ASCII characters (characters whose ASCII codes are greater than 0x7F) are represented by two random characters.

    For apps that target the .NET Framework 4.5 or later and run on the .NET Framework 4.5.2, DataObject.GetData retrieves HTML-formatted data as UTF-8, which represents characters greater than 0x7F correctly.

    Suggestion

    If you implemented a workaround for the encoding problem with HTML-formatted strings (for example, by explicitly encoding the HTML string retrieved from the Clipboard by passing it to System.Text.UTF8Encoding.GetString(Byte[], Int32, Int32)) and you're retargeting your app from version 4 to 4.5, that workaround should be removed.If the old behavior is needed for some reason, the app can target the .NET Framework 4.0 to get that behavior.

    Name Value
    Scope Edge
    Version 4.5.2
    Type Retargeting

    Affected APIs

    EncoderParameter ctor is obsolete

    Details

    The EncoderParameter(Encoder, Int32, Int32, Int32, Int32) constructor is obsolete now and will introduce build warnings if used.

    Suggestion

    Although the EncoderParameter(Encoder, Int32, Int32, Int32, Int32)constructor will continue to work, the following constructor should be used instead to avoid the obsolete build warning when re-compiling code with .NET Framework 4.5 tools: EncoderParameter(Encoder, Int32, EncoderParameterValueType, IntPtr).

    Name Value
    Scope Minor
    Version 4.5
    Type Retargeting

    Affected APIs

    Icon.ToBitmap successfully converts icons with PNG frames into Bitmap objects

    Details

    Starting with the apps that target the .NET Framework 4.6, the Icon.ToBitmap method successfully converts icons with PNG frames into Bitmap objects.

    In apps that target the .NET Framework 4.5.2 and earlier versions, the Icon.ToBitmap method throws an ArgumentOutOfRangeException exception if the Icon object has PNG frames.

    This change affects apps that are recompiled to target the .NET Framework 4.6 and that implement special handling for the ArgumentOutOfRangeException that is thrown when an Icon object has PNG frames. When running under the .NET Framework 4.6, the conversion is successful, an ArgumentOutOfRangeException is no longer thrown, and therefore the exception handler is no longer invoked.

    Suggestion

    If this behavior is undesirable, you can retain the previous behavior by adding the following element to the <runtime> section of your app.config file:

    <AppContextSwitchOverrides
    value="Switch.System.Drawing.DontSupportPngFramesInIcons=true" />
    

    If the app.config file already contains the AppContextSwitchOverrides element, the new value should be merged with the value attribute like this:

    <AppContextSwitchOverrides
    value="Switch.System.Drawing.DontSupportPngFramesInIcons=true;<previous key>=<previous value>" />
    
    Name Value
    Scope Minor
    Version 4.6
    Type Retargeting

    Affected APIs

    Incorrect implementation of MemberDescriptor.Equals

    Details

    The original implementation of the MemberDescriptor.Equals method compares two different string properties from the objects being compared: the category name and the description string. The fix is to compare the Category of the first object to the Category of the second one, and the Description of the first to the Description of the second.

    Suggestion

    If your application depends on MemberDescriptor.Equals sometimes returning false when descriptors are equivalent, and you are targeting the .NET Framework 4.6.2 or later, you have several options:

    • Make code changes to compare the Category and Description fields manually in addition to calling the MemberDescriptor.Equals method.
    • Opt out of this change by adding the following value to the app.config file:
    <runtime>
      <AppContextSwitchOverrides value="Switch.System.MemberDescriptorEqualsReturnsFalseIfEquivalent=true" />
    </runtime>
    

    If your application targets .NET Framework 4.6.1 or earlier and is running on the .NET Framework 4.6.2 or later and you want this change enabled, you can set the compatibility switch to false by adding the following value to the app.config file:

    <runtime>
      <AppContextSwitchOverrides value="Switch.System.MemberDescriptorEqualsReturnsFalseIfEquivalent=false" />
    </runtime>
    
    Name Value
    Scope Edge
    Version 4.6.2
    Type Retargeting

    Affected APIs

    PrivateFontCollection.AddFontFile method releases Font resources

    Details

    In the .NET Framework 4.7.1 and previous versions, the System.Drawing.Text.PrivateFontCollection class does not release the GDI+ font resources after the PrivateFontCollection is disposed for Font objects that are added to this collection using the AddFontFile(String) method. In the .NET Framework 4.7.2 and later Dispose releases the GDI+ fonts that were added to the collection as files.

    Suggestion

    How to opt in or out of these changes In order for an application to benefit from these changes, it must run on the .NET Framework 4.7.2 or later. The application can benefit from these changes in either of the following ways:

    • It is recompiled to target the .NET Framework 4.7.2. This change is enabled by default on Windows Forms applications that target the .NET Framework 4.7.2 or later.
    • It targets the .NET Framework 4.7.1 or an earlier version and opts out of the legacy accessibility behaviors by adding the following AppContext Switch to the <runtime> section of the app.config file and setting it to false, as the following example shows.
    <runtime>
    <AppContextSwitchOverrides value="Switch.System.Drawing.Text.DoNotRemoveGdiFontsResourcesFromFontCollection=false"/>
    </runtime>
    

    Applications that target the .NET Framework 4.7.2 or later, and want to preserve the legacy behavior can opt in to not release font resources by explicitly setting this AppContext switch to true.

    Name Value
    Scope Edge
    Version 4.7.2
    Type Retargeting

    Affected APIs

    WinForm's Domain upbutton and downbutton actions are in sync now

    Details

    In the .NET Framework 4.7.1 and previous versions the DomainUpDown control's DomainUpDown.UpButton() action is ignored when control text is present, and the developer is required to use DomainUpDown.DownButton() action on the control before using DomainUpDown.UpButton() action. Starting with the .NET Framework 4.7.2 both the DomainUpDown.UpButton() and DomainUpDown.DownButton() actions work independently in this scenario and remain in sync.

    Suggestion

    In order for an application to benefit from these changes, it must run on the .NET Framework 4.7.2 or later. The application can benefit from these changes in either of the following ways:

    • It is recompiled to target the .NET Framework 4.7.2. This change is enabled by default on Windows Forms applications that target the .NET Framework 4.7.2 or later.
    • It opts out of the legacy scrolling behavior by adding the following AppContext Switch to the <runtime> section of the app config file and setting it to false, as the following example shows.
    <runtime>
    <AppContextSwitchOverrides value="Switch.System.Windows.Forms.DomainUpDown.UseLegacyScrolling=false"/>
    </runtime>
    
    Name Value
    Scope Edge
    Version 4.7.2
    Type Retargeting

    Affected APIs

    Windows Presentation Foundation (WPF)

    Accessibility improvements in WPF

    Details

    High Contrast improvements

    • The focus for the control is now visible. In previous versions of the .NET Framework, it was not. - The text in and controls when they are selected is now easier to see than in previous .NET Framework versions. - The border of a disabled is now the same color as the disabled text. In previous versions of the .NET Framework, it was not. - Disabled and focused buttons now use the correct theme color. In previous versions of the .NET Framework, they did not. - The dropdown button is now visible when a control's style is set to , In previous versions of the .NET Framework, it was not. - The sort indicator arrow in a control now uses theme colors. In previous versions of the .NET Framework, it did not. - The default hyperlink style now changes to the correct theme color on mouse over. In previous versions of the .NET Framework, it did not. - The Keyboard focus on radio buttons is now visible. In previous versions of the .NET Framework, it was not. - The control's checkbox column now uses the expected colors for keyboard focus feedback. In previous versions of the .NET Framework, it did not. - the Keyboard focus visuals are now visible on and controls. In previous versions of the .NET Framework, it was not.

      **Screen reader interaction improvements**
      • controls are now correctly announced as groups (expand/collapse) by screen readers. - controls are now correctly announced as data grid cell (localized) by screen readers. - Screen readers will now announce the name of an editable . - controls are no longer announced as "no item in view" by screen readers.

        **LiveRegion support** Screen readers such as Narrator help people know the UI contents of an application, usually by describing something about the UI that's currently focused, because that is probably the element of most interest to the user. However, if a UI element changes somewhere in the screen and it does not have the focus, the user may not be informed and miss important information. LiveRegions are meant to solve this problem. A developer can use them to inform the screen reader or any other [UI Automation](~/docs/framework/ui-automation/ui-automation-overview.md) client that an important change has been made to a UI element. The screen reader can then decide how and when to inform the user of this change. The LiveSetting property also lets the screen reader know how important it is to inform the user of the change made to the UI.

        Suggestion

        How to opt in or out of these changes In order for the application to benefit from these changes, it must run on the .NET Framework 4.7.1 or later. The application can benefit from these changes in either of the following ways:

        • Target the .NET Framework 4.7.1. This is the recommended approach. These accessibility changes are enabled by default on WPF applications that target the .NET Framework 4.7.1 or later.
        • It opts out of the legacy accessibility behaviors by adding the following AppContext Switch in the <runtime> section of the app config file and setting it to false, as the following example shows.
        <?xml version="1.0" encoding="utf-8"?>
        <configuration>
        <startup>
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7"/>
        </startup>
        <runtime>
        <!-- AppContextSwitchOverrides value attribute is in the form of 'key1=true/false;key2=true/false  -->
        <AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures=false" />
        </runtime>
        </configuration>
        

        Applications that target the .NET Framework 4.7.1 or later and want to preserve the legacy accessibility behavior can opt in to the use of legacy accessibility features by explicitly setting this AppContext switch to true. For an overview of UI automation, see the UI Automation Overview.

        Name Value
        Scope Major
        Version 4.7.1
        Type Retargeting

        Affected APIs

        Keyboard focus now moves correctly across multiple layers of WinForms/WPF hosting

        Details

        Consider a WPF application hosting a WinForms control which in turn hosts WPF controls. Users may not be able to tab out of the WinForms layer if the first or last control in that layer is the WPF System.Windows.Forms.Integration.ElementHost. This change fixes this issue, and users are now able to tab out of the WinForms layer.Automated applications that rely on focus never escaping the WinForms layer may no longer work as expected.

        Suggestion

        A developer who wants to utilize this change while targeting a framework version below .NET 4.7.2 can set the following set of AppContext flags to false for the change to be enabled.

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures=false;Switch.UseLegacyAccessibilityFeatures.2=false"/>
        </runtime>
        </configuration>
        

        WPF applications must opt in to all early accessibility improvements to get the later improvements. In other words, both the Switch.UseLegacyAccessibilityFeatures and the Switch.UseLegacyAccessibilityFeatures.2 switches must be setA developer who requires the previous functionality while targeting .NET 4.7.2 or greater can set the following AppContext flag to true for the change to be disabled.

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures.2=true"/>
        </runtime>
        </configuration>
        
        Name Value
        Scope Edge
        Version 4.7.2
        Type Retargeting

        NullReferenceException in exception handling code from ImageSourceConverter.ConvertFrom

        Details

        An error in the exception handling code for ConvertFrom(ITypeDescriptorContext, CultureInfo, Object) caused an incorrect System.NullReferenceException to be thrown instead of the intended exception ( System.IO.DirectoryNotFoundException or System.IO.FileNotFoundException). This change corrects that error so that the method now throws the right exception.

        By default all applications targeting .NET Framework 4.6.2 and earlier continue to throw System.NullReferenceException for compatibility. Developers targeting .NET Framework 4.7 and above should see the right exceptions.

        Suggestion

        Developers who wish to revert to getting System.NullReferenceException when targeting .NET Framework 4.7 or later can add/merge the following to their application's App.config file:

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.System.Windows.Media.ImageSourceConverter.OverrideExceptionWithNullReferenceException=true"/>
        </runtime>
        </configuration>
        
        Name Value
        Scope Edge
        Version 4.7
        Type Retargeting

        Affected APIs

        Selector SelectionChanged event and SelectedValue property

        Details

        Starting with the .NET Framework 4.7.1, a Selector always updates the value of its SelectedValue property before raising the SelectionChanged event, when its selection changes. This makes the SelectedValue property consistent with the other selection properties (SelectedItem and SelectedIndex), which are updated before raising the event.

        In the .NET Framework 4.7 and earlier versions, the update to SelectedValue happened before the event in most cases, but it happened after the event if the selection change was caused by changing the SelectedValue property.

        Suggestion

        Apps that target the .NET Framework 4.7.1 or later can opt out of this change and use legacy behavior by adding the following to the <runtime> section of the application configuration file:

        <runtime>
        <AppContextSwitchOverrides
        value="Switch.System.Windows.Controls.TabControl.SelectionPropertiesCanLagBehindSelectionChangedEvent=true" />
        </runtime>
        

        Apps that target the .NET Framework 4.7 or earlier but are running on the .NET Framework 4.7.1 or later can enable the new behavior by adding the following line to the <runtime> section of the application .configuration file:

        <runtime>
        <AppContextSwitchOverrides value="Switch.System.Windows.Controls.TabControl.SelectionPropertiesCanLagBehindSelectionChangedEvent=false" />
        </runtime>
        
        Name Value
        Scope Minor
        Version 4.7.1
        Type Retargeting

        Affected APIs

        TabControl SelectionChanged event and SelectedContent property

        Details

        Starting with the .NET Framework 4.7.1, a TabControl updates the value of its SelectedContent property before raising the SelectionChanged event, when its selection changes.In the .NET Framework 4.7 and earlier versions, the update to SelectedContent happened after the event.

        Suggestion

        Apps that target the .NET Framework 4.7.1 or later can opt out of this change and use legacy behavior by adding the following to the <runtime> section of the application configuration file:

        <runtime>
        <AppContextSwitchOverrides value="Switch.System.Windows.Controls.TabControl.SelectionPropertiesCanLagBehindSelectionChangedEvent=true" />
        </runtime>
        

        Apps that target the .NET Framework 4.7 or earlier but are running on the .NET Framework 4.7.1 or later can enable the new behavior by adding the following line to the <runtime> section of the application .configuration file:

        <runtime>
        <AppContextSwitchOverrides value="Switch.System.Windows.Controls.TabControl.SelectionPropertiesCanLagBehindSelectionChangedEvent=false" />
        </runtime>
        
        Name Value
        Scope Minor
        Version 4.7.1
        Type Retargeting

        Affected APIs

        The default hash algorithm for WPF PackageDigitalSignatureManager is now SHA256

        Details

        The System.IO.Packaging.PackageDigitalSignatureManager provides functionality for digital signatures in relation to WPF packages. In the .NET Framework 4.7 and earlier versions, the default algorithm (PackageDigitalSignatureManager.DefaultHashAlgorithm) used for signing parts of a package was SHA1. Due to recent security concerns with SHA1, this default has been changed to SHA256 starting with the .NET Framework 4.7.1. This change affects all package signing, including XPS documents.

        Suggestion

        A developer who wants to utilize this change while targeting a framework version below .NET Framework 4.7.1 or a developer who requires the previous functionality while targeting .NET Framework 4.7.1 or greater can set the following AppContext flag appropriately. A value of true will result in SHA1 being used as the default algorithm; false results in SHA256.

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.MS.Internal.UseSha1AsDefaultHashAlgorithmForDigitalSignatures=true"/>
        </runtime>
        </configuration>
        

        Name Value
        Scope Edge
        Version 4.7.1
        Type Retargeting

        Affected APIs

        The default hash algorithm for WPF's Markup Compiler is now SHA256

        Details

        The WPF MarkupCompiler provides compilation services for XAML markup files. In the .NET Framework 4.7.1 and earlier versions, the default hash algorithm used for checksums was SHA1. Due to recent security concerns with SHA1, this default has been changed to SHA256 starting with the .NET Framework 4.7.2. This change affects all checksum generation for markup files during compilation.

        Suggestion

        A developer who targets .NET Framework 4.7.2 or greater and wants to revert to SHA1 hashing behavior must set the following AppContext flag.

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.System.Windows.Markup.DoNotUseSha256ForMarkupCompilerChecksumAlgorithm=true"/>
        </runtime>
        </configuration>
        

        A developer who wants to utilize SHA256 hashing while targeting a framework version below .NET 4.7.2 must set the below AppContext flag. Note that the installed version of the .NET Framework must be 4.7.2 or greater.

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.System.Windows.Markup.DoNotUseSha256ForMarkupCompilerChecksumAlgorithm=false
        </runtime>
        </configuration>
        
        Name Value
        Scope Transparent
        Version 4.7.2
        Type Retargeting

        Two-way data-binding to a property with a non-public setter is not supported

        Details

        Attempting to data bind to a property without a public setter has never been a supported scenario. Beginning in the .NET Framework 4.5.1, this scenario will throw an System.InvalidOperationException. Note that this new exception will only be thrown for apps that specifically target the .NET Framework 4.5.1. If an app targets the .NET Framework 4.5, the call will be allowed. If the app does not target a particular .NET Framework version, the binding will be treated as one-way.

        Suggestion

        The app should be updated to either use one-way binding, or expose the property's setter publicly. Alternatively, targeting the .NET Framework 4.5 will cause the app to exhibit the old behavior.

        Name Value
        Scope Minor
        Version 4.5.1
        Type Retargeting

        Affected APIs

        WPF AppDomain Shutdown Handling May Now Call Dispatcher.Invoke in Cleanup of Weak Events

        Details

        In .NET Framework 4.7.1 and earlier versions, WPF potentially creates a System.Windows.Threading.Dispatcher on the .NET finalizer thread during AppDomain shutdown. This was fixed in .NET Framework 4.7.2 and later versions by making the cleanup of weak events thread-aware. Due to this, WPF may call Dispatcher.Invoke to complete the cleanup process.In certain applications, this change in finalizer timing can potentially cause exceptions during AppDomain or process shutdown. This is generally seen in applications that do not correctly shut down dispatchers running on worker threads prior to process or AppDomain shutdown. Such applications should take care to properly manage the lifetime of dispatchers.

        Suggestion

        In .NET Framework 4.7.2 and later versions, developers can disable this fix in order to help alleviate (but not eliminate) timing issues that may occur due to the cleanup change.To disable the change in cleanup, use the following AppContext flag.

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.MS.Internal.DoNotInvokeInWeakEventTableShutdownListener=true"/>
        </runtime>
        </configuration>
        

        Name Value
        Scope Edge
        Version 4.7.2
        Type Retargeting

        WPF Changing a primary key when displaying ADO data in a Master/Detail scenario

        Details

        Suppose you have an ADO collection of items of type Order, with a relation named "OrderDetails" relating it to a collection of items of type Detail via the primary key "OrderID". In your WPF app, you can bind a list control to the details for a given order:

        <ListBox ItemsSource="{Binding Path=OrderDetails}" >
        

        where the DataContext is an Order. WPF gets the value of the OrderDetails property - a collection D of all the Detail items whose OrderID matches the OrderID of the master item. The behavior change arises when you change the primary key OrderID of the master item. ADO automatically changes the OrderID of each of the affected records in the Details collection (namely the ones copied into collection D). But what happens to D?

        • Old behavior: Collection D is cleared. The master item does not raise a change notification for property OrderDetails. The ListBox continues to use collection D, which is now empty.
        • New behavior: Collection D is unchanged. Each of its items raises a change notification for the OrderID property. The ListBox continues to use collection D, and displays the details with the new OrderID. WPF implements the new behavior by creating collection D in a different way: by calling the ADO method DataRowView.CreateChildView(DataRelation, Boolean) with the followParent argument set to true.

        Suggestion

        An app gets the new behavior by using the following AppContext switch.

        <configuration>
          <runtime>
            <AppContextSwitchOverrides value="Switch.System.Windows.Data.DoNotUseFollowParentWhenBindingToADODataRelation=false"/>
          </runtime>
        </configuration>
        

        The switch defaults to true (old behavior) for apps that target .NET 4.7.1 or below, and to false (new behavior) for apps that target .NET 4.7.2 or above.

        Name Value
        Scope Minor
        Version 4.7.2
        Type Retargeting

        WPF FocusVisual for RadioButton and CheckBox Now Displays Correctly When The Controls Have No Content

        Details

        In the .NET Framework 4.7.1 and earlier versions, WPF System.Windows.Controls.CheckBox and System.Windows.Controls.RadioButton have inconsistent and, in Classic and High Contrast themes, incorrect focus visuals. These issues occur in cases where the controls do not have any content set. This can make the transition between themes confusing and the focus visual hard to see. In the .NET Framework 4.7.2, these visuals are now more consistent across themes and more easily visible in Classic and High Contrast themes.

        Suggestion

        A developer targeting .NET Framework 4.7.2 that wants to revert to the behavior in .NET 4.7.1 will need to set the following AppContext flag.

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures.2=true;"/>
        </runtime>
        </configuration>
        

        A developer who wants to utilize this change while targeting a framework version below .NET 4.7.2 must set the following AppContext flags.Note that all the flags must be set appropriately and the installed version of the .NET Framework must be 4.7.2 or greater.WPF applications are required to opt in to all earlier accessibility improvements to get the latest improvements. To do this, ensure that both the AppContext switches 'Switch.UseLegacyAccessibilityFeatures' and 'Switch.UseLegacyAccessibilityFeatures.2' are set to false.

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures=false;Switch.UseLegacyAccessibilityFeatures.2=false;"/>
        </runtime>
        </configuration>
        
        Name Value
        Scope Edge
        Version 4.7.2
        Type Retargeting

        WPF Grid allocation of space to star-columns

        Details

        Starting with the .NET Framework 4.7, WPF replaces the algorithm that Grid uses to allocate space to *-columns. This will change the actual width assigned to *-columns in a number of cases:

        • When one or more *-columns also have a minimum or maximum width that overrides the proportional allocation for that colum. (The minimum width can derive from an explicit MinWidth declaration, or from an implicit minimum obtained from the column's content. The maximum width can only be defined explicitly, from a MaxWidth declaration.)

        • When one or more *-columns declare an extremely large *-weight, greater than 10^298.

        • When the *-weights are sufficiently different to encounter floating-point instability (overflow, underflow, loss of precision).

        • When layout rounding is enabled, and the effective display DPI is sufficiently high. In the first two cases, the widths produced by the new algorithm can be significantly different from those produced by the old algorithm; in the last case, the difference will be at most one or two pixels.

          The new algorithm fixes several bugs present in the old algorithm:

        • Total allocation to columns can exceed the Grid's width. This can occur when allocating space to a column whose proportional share is less than its minimum size. The algorithm allocates the minimum size, which decreases the space available to other columns. If there are no *-columns left to allocate, the total allocation will be too large.

        • Total allocation can fall short of the Grid's width. This is the dual problem to #1, arising when allocating to a column whose proportional share is greater than its maximum size, with no *-columns left to take up the slack.

        • Two *-columns can receive allocations not proportional to their *-weights. This is a milder version of #1/#2, arising when allocating to *-columns A, B, and C (in that order), where B's proportional share violates its min (or max) constraint. As above, this changes the space available to column C, who gets less (or more) proportional allocation than A did,

        • Columns with extremely large weights (> 10^298) are all treated as if they had weight 10^298. Proportional differences between them (and between columns with slightly smaller weights) are not honored.

        • Columns with inifinte weights are not handled correctly. [Actually you can't set a weight to Infinity, but this is an artificial restriction. The allocation code was trying to handle it, but doing a bad job.]

        • Several minor problems while avoiding overflow, underflow, loss of precision and similar floating-point issues.

        • Adjustments for layout rounding are incorrect at sufficiently high DPI. The new algorithm produces results that meet the following criteria:

          A. The actual width assigned to a *-column is never less than its minimum width nor greater than its maximum width.
          B. Each -column that is not assigned its minimum or maximum width is assigned a width proportional to its -weight. To be precise, if two columns are declared with width x and y respectively, and if neither column receives its minimum or maximum width, the actual widths v and w assigned to the columns are in the same proportion: v / w == x / y.
          C. The total width allocated to "proportional" *-columns is equal to the space available after allocating to the constrained columns (fixed, auto, and *-columns that are allocated their min or max width). This might be zero, for instance if the sum of the minimum widths exceeds the Grid's availbable width.
          D. All these statements are to be interpreted with respect to the "ideal" layout. When layout rounding is in effect, the actual widths can differ from the ideal widths by as much as one pixel.
          The old algorithm honored (A) but failed to honor the other criteria in the cases outlined above.

          Everything said about columns and widths in this article applies as well to rows and heights.

        Suggestion

        By default, apps that target versions of the .NET Framework starting with the .NET Framework 4.7 will see the new algorithm, while apps that target the .NET Framework 4.6.2 or earlier versions will see the old algorithm.

        To override the default, use the following configuration setting:

        <runtime>
        <AppContextSwitchOverrides value="Switch.System.Windows.Controls.Grid.StarDefinitionsCanExceedAvailableSpace=true" />
        </runtime>
        

        The value true selects the old algorithm, false selects the new algorithm.

        Name Value
        Scope Minor
        Version 4.7
        Type Retargeting

        WPF layout rounding of margins has changed

        Details

        The way in which margins are rounded and borders and the background inside of them has changed. As a result of this change:

        • The width or height of elements may grow or shrink by at most one pixel.
        • The placement of an object can move by at most one pixel.
        • Centered elements can be vertically or horizontally off center by at most one pixel. By default, this new layout is enabled only for apps that target the .NET Framework 4.6.

        Suggestion

        Since this modification tends to eliminate clipping of the right or bottom of WPF controls at high DPIs, apps that target earlier versions of the .NET Framework but are running on the .NET Framework 4.6 can opt into this new behavior by adding the following line to the <runtime> section of the app.config file:

        <AppContextSwitchOverrides value="Switch.MS.Internal.DoNotApplyLayoutRoundingToMarginsAndBorderThickness=false" />'
        

        Apps that target the .NET Framework 4.6 but want WPF controls to render using the previous layout algorithm can do so by adding the following line to the <runtime> section of the app.config file:

        <AppContextSwitchOverrides value="Switch.MS.Internal.DoNotApplyLayoutRoundingToMarginsAndBorderThickness=true" />'.
        
        Name Value
        Scope Minor
        Version 4.6
        Type Retargeting

        WPF Pointer-Based Touch Stack

        Details

        This change adds the ability to enable an optional WM_POINTER based WPF touch/stylus stack. Developers that do not explicitly enable this should see no change in WPF touch/stylus behavior.Current Known Issues With optional WM_POINTER based touch/stylus stack:

        • No support for real-time inking.
        • While inking and StylusPlugins will still work, they will be processed on the UI Thread which can lead to poor performance.
        • Behavioral changes due to changes in promotion from touch/stylus events to mouse events
        • Manipulation may behave differently
        • Drag/Drop will not show appropriate feedback for touch input
        • This does not affect stylus input
        • Drag/Drop can no longer be initiated on touch/stylus events
        • This can potentially hang the application until mouse input is detected.
        • Instead, developers should initiate drag and drop from mouse events.

        Suggestion

        Developers who wish to enable this stack can add/merge the following to their application's App.config file:

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.System.Windows.Input.Stylus.EnablePointerSupport=true"/>
        </runtime>
        </configuration>
        

        Removing this or setting the value to false will turn this optional stack off.Note that this stack is available only on Windows 10 Creators Update and above.

        Name Value
        Scope Edge
        Version 4.7
        Type Retargeting

        WPF TextBox.Text can be out-of-sync with databinding

        Details

        In some cases, the Text property reflects a previous value of the databound property value if the property is modified during a databinding write operation.

        Suggestion

        This should have no negative impact. However, you can restore the previous behavior by setting the KeepTextBoxDisplaySynchronizedWithTextProperty property to false.

        Name Value
        Scope Edge
        Version 4.5
        Type Retargeting

        Affected APIs

        WPF TextBox/PasswordBox Text Selection Does Not Follow System Colors

        Details

        In .NET Framework 4.7.1 and earlier versions, WPF System.Windows.Controls.TextBox and System.Windows.Controls.PasswordBox could only render a text selection in the Adorner layer. In some system themes this would occlude text, making it hard to read. In .NET Framework 4.7.2 and later, developers have an option of enabling a non-Adorner-based selection rendering scheme that alleviates this issue.

        Suggestion

        A developer who wants to utilize this change must set the following AppContext flag appropriately. To utilize this feature, the installed .NET Framework version must be 4.7.2 or greater.To enabled the non-adorner-based selection, use the following AppContext flag.

        <configuration>
        <runtime>
        <AppContextSwitchOverrides value="Switch.System.Windows.Controls.Text.UseAdornerForTextboxSelectionRendering=false"/>
        </runtime>
        </configuration>
        

        Name Value
        Scope Edge
        Version 4.7.2
        Type Retargeting

        Windows Workflow Foundation (WF)

        Accessibility improvements in Windows Workflow Foundation (WF) workflow designer

        Details

        The Windows Workflow Foundation (WF) workflow designer is improving how it works with accessibility technologies. These improvements include the following changes:

        • The tab order is changed to left to right and top to bottom in some controls:
        • The initialize correlation window for setting correlation data for the InitializeCorrelation activity
        • The content definition window for the Receive, Send, SendReply, and ReceiveReply activities
        • More functions are available via the keyboard:
        • When editing the properties of an activity, property groups can be collapsed by keyboard the first time they are focused.
        • Warning icons are now accessible by keyboard.
        • The More Properties button in the Properties window is now accessible by keyboard.
        • Keyboard users now can access the header items in the Arguments and Variables panes of the Workflow Designer.
        • Improved visibility of items with focus, such as when:
        • Adding rows to data grids used by the Workflow Designer and activity designers.
        • Tabbing through fields in the ReceiveReply and SendReply activities.
        • Setting default values for variables or arguments
        • Screen readers can now correctly recognize:
        • Breakpoints set in the workflow designer.
        • The FlowSwitch<T>, FlowDecision, and CorrelationScope activities.
        • The contents of the Receive activity.
        • The Target Type for the InvokeMethod activity.
        • The Exception combobox and the Finally section in the TryCatch activity.
        • The Message Type combobox, the splitter in the Add Correlation Initializers window, the Content Definition window, and the CorrelatesOn Defintion window in the messaging activities (Receive, Send, SendReply, and ReceiveReply).
        • State machine transitions and transitions destinations.
        • Annotations and connectors on FlowDecision activities.
        • The context (right-click) menus for activities.
        • The property value editors, the Clear Search button, the By Category and Alphabetical sort buttons, and the Expression Editor dialog in the properties grid.
        • The zoom percentage in the Workflow Designer.
        • The separator in Parallel and Pick activities.
        • The InvokeDelegate activity.
        • The Select Types window for dictionary activities (Microsoft.Activities.AddToDictionary&lt;TKey,TValue>, Microsoft.Activities.RemoveFromDictionary&lt;TKey,TValue>, etc.).
        • The Browse and Select .NET Type window.
        • Breadcrumbs in the Workflow Designer.
        • Users who choose High Contrast themes will see many improvements in the visibility of the Workflow Designer and its controls like better contrast ratios between elements and more noticeable selection boxes used for focus elements.

        Suggestion

        If you have an application with a re-hosted workflow designer, your application can benefit from these changes by performing either of these actions:

        • Recompile your application to target the .NET Framework 4.7.1. These accessibility changes are enabled by default.
        • If your application targets the .NET Framework 4.7 or earlier but is running on the .NET Framework 4.7.1, you can opt out of these legacy accessibility behaviors by adding the following AppContext switch to the <runtime> section of the app.config file and set it to false, as the following example shows.
        <?xml version="1.0" encoding="utf-8"?>
        <configuration>
          <startup>
            <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7"/>
          </startup>
          <runtime>
            <!-- AppContextSwitchOverrides value attribute is in the form of 'key1=true/false;key2=true/false  -->
            <AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures=false" />
          </runtime>
        </configuration>
        

        Applications that target the .NET Framework 4.7.1 or later and want to preserve the legacy accessibility behavior can opt in to the use of legacy accessibility features by explicitly setting this AppContext switch to true.

        Name Value
        Scope Minor
        Version 4.7.1
        Type Retargeting

        Avoiding endless recursion for IWorkflowInstanceManagement.TransactedCancel and IWorkflowInstanceManagement.TransactedTerminate

        Details

        Under some circumstances when using IWorkflowInstanceManagement.TransactedCancel or IWorkflowInstanceManagement.TransactedTerminate APIs to cancel or terminate a worklow service instance, the workflow instance may encounter a stack overflow due to endless recursion when the Workflow runtime attempts to persist the service instance as part of processing the request. The problem occurs if the workflow instance is in a state where it is waiting for some other outstanding WCF request to another service to complete. The TransactedCancel and TransactedTerminate operations create work items that are queued for the workflow service instance. These work items are not executed as part of the processing of the TransactedCancel/TransactedTerminate request. Because the workflow service instance is busy waiting for the other outstanding WCF request to complete, the work item created remains queued. The TransactedCancel/TransactedTerminate operation completes and control is returned back to the client. When the transaction associated with the TransactedCancel/TransactedTerminate operation attempts to commit, it needs to persist the workflow serivce instance state. But because there is an outstanding WCF request for the instance, the Workflow runtime cannot persist the workflow service instance, and an endless recursion loop leads to the stack overflow.Because TransactedCancel and TransactedTerminate only create a work item in memory, the fact that a transaction exists doesn't have any effect. A rollback of the transaction does not discard the work item.To address this issue, starting in .NET Framework 4.7.2, we have introduced an AppSetting that can be added to the web.config/app.config of the workflow service that tells it to ignore transactions for TransactedCancel and TransactedTerminate. This allows the transaction to commit without waiting for the workflow instance to persist. The AppSetting for this feature is named microsoft:WorkflowServices:IgnoreTransactionsForTransactedCancelAndTransactedTerminate. A value of true indicates that the transaction should be ignored, thus avoiding the stack overflow. The default value of this AppSetting is false, so existing workflow service instances are not affected.

        Suggestion

        If you are using AppFabric or another IWorkflowInstanceManagement client and are encountering a stack overflow in the workflow serivce instance when trying to cancel or terminate a workflow instance, you can add the following to the <appSettings> section of the web.config/app.config file for the workflow service:

        <add key="microsoft:WorkflowServices:IgnoreTransactionsForTransactedCancelAndTransactedTerminate" value="true"/>
        

        If you are not encountering the problem, you do not need to do this.

        Name Value
        Scope Edge
        Version 4.7.2
        Type Retargeting

        New (ambiguous) Dispatcher.Invoke overloads could result in different behavior

        Details

        The .NET Framework 4.5 adds new overloads to Dispatcher.Invoke that include a parameter of type Action. When existing code is recompiled, compilers may resolve calls to Dispatcher.Invoke methods that have a Delegate parameter as calls to Dispatcher.Invoke methods with an Action parameter. If a call to a Dispatcher.Invoke overload with a Delegate parameter is resolved as a call to a Dispatcher.Invoke overload with an Action parameter, the following differences in behavior may occur:

        Suggestion

        To avoid ambiguity (and potential differences in exception handling or blocking behaviors), code calling Dispatcher.Invoke can pass an empty object[] as a second parameter to the Invoke call to be sure of resolving to the .NET Framework 4.0 method overload.

        Name Value
        Scope Minor
        Version 4.5
        Type Retargeting

        Affected APIs

        Some WorkFlow drag-and-drop APIs are obsolete

        Details

        This WorkFlow drag-and-drop API is obsolete and will cause compiler warnings if the app is rebuilt against 4.5.

        Suggestion

        New System.Activities.Presentation.DragDropHelper APIs that support operations with multiple objects should be used instead. Alternatively, the build warnings can be suppressed or they can be avoided by using an older compiler. The APIs are still supported.

        Name Value
        Scope Minor
        Version 4.5
        Type Retargeting

        Affected APIs

        WorkFlow 3.0 types are obsolete

        Details

        Windows Workflow Foundation (WWF) 3.0 APIs (those from the System.Workflow namespace) are now obsolete.

        Suggestion

        New WWF 4.0 APIs (in System.Activities) should be used instead. An example of using the new APIs can be found here and further guidance is available here. Alternatively, since the WWF 3.0 APIs are still supported, they may be used and the build-time warning avoided either by suppressing it or by using an older compiler.

        Name Value
        Scope Major
        Version 4.5
        Type Retargeting

        Workflow checksums changed from MD5 to SHA1

        Details

        To support debugging with Visual Studio, the Workflow runtime generates a checksum for a workflow instance using a hashing algorithm. In the .NET Framework 4.6.2 and earlier versions, workflow checksum hashing used the MD5 algorithm, which caused issues on FIPS-enabled systems. Starting with the .NET Framework 4.7, the algorithm is SHA1. If your code has persisted these checksums, they will be incompatible.

        Suggestion

        If your code is unable to load workflow instances due to a checksum failure, try setting the AppContext switch "Switch.System.Activities.UseMD5ForWFDebugger" to true.In code:

        System.AppContext.SetSwitch("Switch.System.Activities.UseMD5ForWFDebugger", true);
        

        Or in configuration:

        <configuration>
          <runtime>
            <AppContextSwitchOverrides value="Switch.System.Activities.UseMD5ForWFDebugger=true" />
          </runtime>
        </configuration>
        
        Name Value
        Scope Minor
        Version 4.7
        Type Retargeting

        XML, XSLT

        XML schema validation is stricter

        Details

        In the .NET Framework 4.5, XML schema validation is more strict. If you use xsd:anyURI to validate a URI such as a mailto protocol, validation fails if there are spaces in the URI. In previous versions of the .NET Framework, validation succeeded. The change affects only applications that target the .NET Framework 4.5.

        Suggestion

        If looser .NET Framework 4.0 validation is needed, the validating application can target version 4.0 of the .NET Framework. When retargeting to .NET Framework 4.5, however, code review should be done to be sure that invalid URIs (with spaces) are not expected as attribute values with the anyURI data type.

        Name Value
        Scope Minor
        Version 4.5
        Type Retargeting

        XmlWriter throws on invalid surrogate pairs

        Details

        For apps that target the .NET Framework 4.5.2 or previous versions, writing an invalid surrogate pair using exception fallback handling does not always throw an exception. For apps that target the .NET Framework 4.6, attempting to write an invalid surrogate pair throws an System.ArgumentException.

        Suggestion

        If necessary, this break can be avoided by targeting the .NET Framework 4.5.2 or earlier. Alternatively, invalid surrogate pairs can be pre-processed into valid xml prior to writing them.

        Name Value
        Scope Edge
        Version 4.6
        Type Retargeting

        Affected APIs

        XSD Schema validation now correctly detects violations of unique constraints if compound keys are used and one key is empty

        Details

        Versions of the .NET Framework prior to 4.6 had a bug that caused XSD validation to not detect unique constraints on compound keys if one of the keys was empty. In the .NET Framework 4.6, this issue is corrected. This will result in more correct validation, but it may also result in some XML not validating which previously would have.

        Suggestion

        If looser .NET Framework 4.0 validation is needed, the validating application can target version 4.5 (or earlier) of the .NET Framework. When retargeting to .NET Framework 4.6, however, code review should be done to be sure that duplicate compound keys (as described in this issue's description) are not expected to validate.

        Name Value
        Scope Edge
        Version 4.6
        Type Retargeting