Retargeting Changes for Migration from .NET Framework 4.7 to 4.8

• (4.0 | 4.5)
• (4.0 | 4.5.1)
• (4.0 | 4.5.2)
• (4.0 | 4.6)
• (4.0 | 4.6.1)
• (4.0 | 4.6.2)
• (4.0 | 4.7)
• (4.0 | 4.7.1)
• (4.0 | 4.7.2)
• (4.0 | 4.8)
• (4.5 | 4.5.1)
• (4.5 | 4.5.2)
• (4.5 | 4.6)
• (4.5 | 4.6.1)
• (4.5 | 4.6.2)
• (4.5 | 4.7)
• (4.5 | 4.7.1)
• (4.5 | 4.7.2)
• (4.5 | 4.8)
• (4.5.1 | 4.5.2)
• (4.5.1 | 4.6)
• (4.5.1 | 4.6.1)
• (4.5.1 | 4.6.2)
• (4.5.1 | 4.7)
• (4.5.1 | 4.7.1)
• (4.5.1 | 4.7.2)
• (4.5.2 | 4.6)
• (4.5.2 | 4.6.1)
• (4.5.2 | 4.6.2)
• (4.5.2 | 4.7)
• (4.5.2 | 4.7.1)
• (4.5.2 | 4.7.2)
• (4.5.2 | 4.8)
• (4.6 | 4.6.1)
• (4.6 | 4.6.2)
• (4.6 | 4.7)
• (4.6 | 4.7.1)
• (4.6 | 4.7.2)
• (4.6 | 4.8)
• (4.6.1 | 4.6.2)
• (4.6.1 | 4.7)
• (4.6.1 | 4.7.1)
• (4.6.1 | 4.7.2)
• (4.6.1 | 4.8)
• (4.6.2 | 4.7)
• (4.6.2 | 4.7.1)
• (4.6.2 | 4.7.2)
• (4.6.2 | 4.8)
• (4.7 | 4.7.1)
• (4.7 | 4.7.2)
• (4.7 | 4.8)
• (4.7.1 | 4.7.2)
• (4.7.1 | 4.8)
• (4.7.2 | 4.8)
• (4.8 | 4.8.1)

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

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

Core

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

• System.Uri

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

• System.IO.Compression.DeflateStream
• System.IO.Compression.GZipStream

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

• System.Uri

Managed cryptography classes do not throw a CryptographyException in FIPS mode

Details

In .NET Framework 4.7.2 and earlier versions, managed cryptographic provider classes such as SHA256Managed throw a CryptographicException when the system cryptographic libraries are configured in FIPS mode. These exceptions are thrown because the managed versions have not undergone FIPS (Federal Information Processing Standards) 140-2 certification, as well as to block cryptographic algorithms that were not considered to be approved based on the FIPS rules. Because few developers have their development machines in FIPS mode, these exceptions are frequently thrown only on production systems.Applications that target .NET Framework 4.8 and later versions automatically switch to the newer, relaxed policy, so that a CryptographicException is no longer thrown by default in such cases. Instead, the managed cryptography classes redirect cryptographic operations to a system cryptography library. This policy change effectively removes a potentially confusing difference between developer environments and the production environments and makes native components and managed components operate under the same cryptographic policy.

Suggestion

If this behavior is undesirable, you can opt out of it and restore the previous behavior so that a CryptographicException is thrown in FIPS mode by adding the following AppContextSwitchOverrides configuration setting to the <runtime> section of your application configuration file:

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

If your application targets .NET Framework 4.7.2 or earlier, you can also opt in to this change by adding the following AppContextSwitchOverrides configuration setting to the <runtime> section of your application configuration file:

<runtime>
  <AppContextSwitchOverrides value="Switch.System.Security.Cryptography.UseLegacyFipsThrow=false" />
</runtime>

Name	Value
Scope	Edge
Version	4.8
Type	Retargeting

Affected APIs

• System.Security.Cryptography.AesManaged
• System.Security.Cryptography.MD5Cng
• System.Security.Cryptography.MD5CryptoServiceProvider
• System.Security.Cryptography.RC2CryptoServiceProvider
• System.Security.Cryptography.RijndaelManaged
• System.Security.Cryptography.RIPEMD160Managed
• System.Security.Cryptography.SHA1Managed
• System.Security.Cryptography.SHA256Managed

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

• System.IO.Ports.SerialPort

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

• ServiceBase.Run(ServiceBase)
• ServiceBase.Run(ServiceBase[])

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

• StackTrace(Boolean)
• StackTrace(Exception, Boolean)
• StackTrace(Exception, Int32, Boolean)

Security

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

• System.Security.Cryptography.Pkcs.CmsSigner
• System.Security.Cryptography.Xml.SignedXml
• System.Security.Cryptography.Xml.Reference

SignedXml.GetPublicKey returns RSACng on net462 (or lightup) without retargeting change

Details

Starting with the .NET Framework 4.6.2, the concrete type of the object returned by the SignedXml.GetPublicKey method changed (without a quirk) from a CryptoServiceProvider implementation to a Cng implementation. This is because the implementation changed from using certificate.PublicKey.Key to using the internal certificate.GetAnyPublicKey which forwards to RSACertificateExtensions.GetRSAPublicKey.

Suggestion

Starting with apps running on the .NET Framework 4.7.1, you can use the CryptoServiceProvider implementation used by default in the .NET Framework 4.6.1 and earlier versions by adding the following configuration switch to the runtime section of your app config file:

<AppContextSwitchOverrides value="Switch.System.Security.Cryptography.Xml.SignedXmlUseLegacyCertificatePrivateKey=true" />

Name	Value
Scope	Edge
Version	4.6.2
Type	Retargeting

Affected APIs

• SignedXml.CheckSignatureReturningKey(AsymmetricAlgorithm)

Windows Communication Foundation (WCF)

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

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

• Rows in a DataGridView can now be sorted using the keyboard. Now a user can use the F3 key in order to sort by the current column.
• When the DataGridView.SelectionMode is set to DataGridViewSelectionMode.FullRowSelect, the column header will change color to indicate the current column as the user tabs through the cells in the current row.
• The DataGridViewCell.DataGridViewCellAccessibleObject.Parent property now returns the correct parent control.

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

• The PropertyGrid control child elements now return a true for the IsReadOnlyProperty property only when a PropertyGrid element is enabled.

• The PropertyGrid control child elements now return a false for the IsEnabledProperty property only when a PropertyGrid element can be changed by the user. For an overview of UI automation, see the UI Automation Overview.

  Improved keyboard navigation

• ToolStripButton now allows focus when contained within a ToolStripPanel that has the TabStop property set to true.

Name	Value
Scope	Major
Version	4.7.2
Type	Retargeting

Accessibility improvements in Windows Forms controls for .NET 4.8

Details

The Windows Forms Framework is continuing to improve 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 interaction with Narrator.
• Changes in the Accessible hierarchy (improving navigation through the UI Automation tree).

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.8. The application can opt in into these changes in either of the following ways:

• It is recompiled to target the .NET Framework 4.8. These accessibility changes are enabled by default on Windows Forms applications that target the .NET Framework 4.8.
• It targets the .NET Framework 4.7.2 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;Switch.UseLegacyAccessibilityFeatures.3=false" />
  </runtime>
</configuration>

Note that to opt in to the accessibility features added in .NET Framework 4.8, you must also opt in to accessibility features of .NET Framework 4.7.1 and 4.7.2 as well. Applications that target the .NET Framework 4.8 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.Enabling the keyboard ToolTip invocation support requires adding the Switch.System.Windows.Forms.UseLegacyToolTipDisplay=false line to the AppContextSwitchOverrides value:

<AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures=false;Switch.UseLegacyAccessibilityFeatures.2=false;Switch.UseLegacyAccessibilityFeatures.3=false;Switch.System.Windows.Forms.UseLegacyToolTipDisplay=false" />

Note that enabling this feature requires opting in to the aforementioned accessibility features of .NET Framework 4.7.1 - 4.8. Also, if any of the accessibility features are not opted in but the tooltip display feature is opted in, a runtime NotSupportedException will be thrown on the first access to these features. The exception message indicates that keyboard ToolTips require accessibility improvements of level 3 to be enabled.

Use of OS-defined colors in High Contrast themes

• Improved high-contrast themes.

Improved Narrator support

• Narrator now announces the sort direction of the DataGridViewColumn when announcing an accessible name of a DataGridViewCell.

Improved CheckedListBox Accessibility support

• Improved Narrator support for the CheckedListBox control. When navigating to the CheckedListBox control using the keyboard, Narrator focuses the CheckedListBox item and announces it.
• An empty CheckedListBox control now has a focus rectangle drawn for a virtual first item when the control becomes focused.

Improved ComboBox Accessibility support

• Enabled UI Automation support for the ComboBox control, with the ability to use UI Automation notifications and other UI Automation features. Improved DataGridView Accessibility support

• Enabled UI Automation support for DataGridView control with ability to use UI Automation notifications and other UI Automation features.

• The UI Automation element which corresponds to the DataGridViewComboBoxEditingControl or DataGridViewTextBoxEditingControl is now a child of corresponding editing cell.

Improved LinkLabel Accessibility support

• Improved LinkLabel control accessibility: Narrator announces the disabled state for the link if the corresponding LinkLabel control is disabled.

Improved ProgressBar Accessibility support

• Enabled UI Automation support for the ProgressBar control with the ability to use UI Automation notifications and other UI Automation features. Developers are now able to use UI Automation notifications which Narrator can announce to indicate progress. For an overview of UI automation events overview, including UI automation notification events, see the UI Automation Events Overview.

Improved PropertyGrid Accessibility support

• Enabled UI Automation support for the PropertyGrid control, with the ability to use UI Automation notifications and other UI Automation features.
• The UI Automation element which corresponds to the currently edited property is now a child of the corresponding property item UI Automation element.
• The UI Automation property item element is now a child of the corresponding category element if the parent PropertyGrid control is set to category view.

Improved ToolStrip support

• Enabled UI Automation support for the ToolStrip control, with the ability to use UI Automation notifications and other UI Automation features.
• Improved navigation through ToolStrip items.
• In items mode, Narrator focus does not disappear and does not go to hidden items.

Improved Visual cues

• An empty CheckedListBox control now displays a focus indicator when it receives focus. Note: UI automation support is enabled for controls in runtime but is not used in design time. For an overview of UI automation, see the UI Automation Overview.

Invoking controls' ToolTips with a keyboard

• Control tooltip can now be invoked by focusing the control with keyboard. This feature needs to be enabled explicitly for the application (see section "How to opt in or out of these changes")

Name	Value
Scope	Major
Version	4.8
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:

• The ToolStripSplitButton and ComboBox controls support the Expand/Collapse pattern.

• The ToolStripMenuItem control has a ControlType property value ControlType.MenuItem.

• The ToolStripItem control supports the NameProperty property and theExpand/Collapse pattern.

• The ToolStripDropDownItem control supports AccessibleEvents indicating StateChange and NameChange when drop down is expanded or collapsed.

• The ToolStripDropDownButton control has a ControlType property value of ControlType.MenuItem.

• The DataGridViewCheckBoxCell control supports the TogglePattern.

• The NumericUpDown and DomainUpDown controls support the NameProperty property and have a ControlType of ControlType.Spinner.

  Improvements to the PropertyGrid control The .NET Framework 4.7.1 adds the following improvements to the PropertyBrowser control:

• The Details button in the error dialog that is displayed when the user enters an incorrect value in the PropertyGrid control supports the Expand/Collapse pattern, state and name change notifications, and a ControlType property with a value of ControlType.MenuItem.

• The message pane displayed when the Details button of the error dialog is expanded is now keyboard accessible and allows Narrator to announce the content of the error message.

• The AccessibleRole of rows in the PropertyGrid control have changed from "Row" to "Cell". The cell maps to UIA ControlType "DataItem", which allows it to support appropriate keyboard shortcuts and Narrator announcements.

• The PropertyGrid control rows that represent header items when the PropertyGrid control has a PropertySort property set to PropertySort.Categorized have a ControlType property value of ControlType.Button.

• The PropertyGrid control rows that represent header items when the PropertyGrid control has a PropertySort property set to PropertySort.Categorized support the Expand/Collapse pattern.

• Improved keyboard navigation between the grid and the ToolBar above it. Pressing "Shift-Tab" now selects the first ToolBar button, instead of the whole ToolBar.

• PropertyGrid controls displayed in High Contrast mode will now draw a focus rectangle around the ToolBar button which corresponds to the current PropertySort property value.

• PropertyGrid controls displayed in High Contrast mode and with a PropertySort property set to PropertySort.Categorized will now display the background of category headers in a highly contrasting color.

• PropertyGrid controls better differentiates between ToolBar items with focus and the ToolBar items which indicate the current value of the PropertySort property. This fix consists of a High Contrast change and a change for non-High Contrast scenarios.

• PropertyGrid control ToolBar items which indicates the current value of the PropertySort property support the TogglePattern.

• Improved Narrator support for distinguishing the selected alignment in the Alignment Picker.

• When an empty PropertyGrid control is displayed on a form, it will now receive focus where previously it would not.

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

• ToolStripDropDownButton.CreateAccessibilityInstance()
• DomainUpDown.DomainUpDownAccessibleObject.Name
• MonthCalendar.AccessibilityObject

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

• ContextMenuStrip.SourceControl

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

• PrivateFontCollection.AddFontFile(String)
• FontCollection.Dispose()

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

• DomainUpDown.UpButton()
• DomainUpDown.DownButton()

Windows Presentation Foundation (WPF)

Accessibility improvements in WPF

Details

High Contrast improvements

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

Screen reader interaction improvements

• Expander controls are now correctly announced as groups (expand/collapse) by screen readers.
• DataGridCell controls are now correctly announced as data grid cell (localized) by screen readers.
• Screen readers will now announce the name of an editable ComboBox.
• PasswordBox controls are no longer announced as "no item in view" by screen readers.

LiveRegion support

Screen readers, such as Narrator, help people understand the user interface (UI) of an application, usually by describing the UI element that currently has focus. 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 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 .NET Framework 4.7.1 or later. The application can benefit from these changes in either of the following ways:

• Target .NET Framework 4.7.1. This is the recommended approach. These accessibility changes are enabled by default on WPF applications that target .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 .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 UI Automation Overview.

Name	Value
Scope	Major
Version	4.7.1
Type	Retargeting

Affected APIs

• AutomationElementIdentifiers.LiveSettingProperty
• AutomationElementIdentifiers.LiveRegionChangedEvent
• System.Windows.Automation.AutomationLiveSetting
• AutomationProperties.LiveSettingProperty
• AutomationProperties.SetLiveSetting(DependencyObject, AutomationLiveSetting)
• AutomationProperties.GetLiveSetting(DependencyObject)
• AutomationPeer.GetLiveSettingCore()

Add SelectionTextBrush public property to TextBox/PasswordBox non-adorner selection

Details

In WPF applications using non-adorner based text selection for TextBox and PasswordBox, developers may now set the newly added SelectionTextBrush property in order to alter the rendering of the selected text. By default, this color changes with HighlightTextBrushKey. If non-adorner based text selection is not enabled, this property does nothing.

Suggestion

Once non-adorner based text selection is enabled, you can use the PasswordBox.SelectionTextBrush and SelectionTextBrush property to change the appearance of the selected text. This can be achieved using XAML:

<TextBox SelectionBrush="Red" SelectionTextBrush="White"  SelectionOpacity="0.5"
Foreground="Blue" CaretBrush="Blue">
This is some text.
</TextBox>

Name	Value
Scope	Major
Version	4.8
Type	Retargeting

Affected APIs

• TextBoxBase.SelectionTextBrushProperty
• TextBoxBase.SelectionTextBrush
• System.Windows.Controls.TextBox
• System.Windows.Controls.PasswordBox

HwndHost now correctly resizes child-HWND during DPI changes

Details

In .NET Framework 4.7.2 and earlier versions, when WPF was run in Per-Monitor Aware mode, controls hosted within HwndHost were not sized correctly after DPI changes, such as when moving applications from one monitor to another. This fix ensures that hosted controls are sized appropriately.

Suggestion

In order for the application to benefit from these changes, it must run on the .NET Framework 4.7.2 or later, and it must opt-in to this behavior by setting the following AppContext Switch in the <runtime> section of the app config file 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.System.Windows.DoNotUsePresentationDpiCapabilityTier2OrGreater=false" />
</runtime>
</configuration>

Name	Value
Scope	Major
Version	4.8
Type	Retargeting

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

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.SelectedContent
• Selector.SelectionChanged

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

• TabControl.SelectedContent
• Selector.SelectionChanged

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

• PackageDigitalSignatureManager.DefaultHashAlgorithm

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

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 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<TKey,TValue>, Microsoft.Activities.RemoveFromDictionary<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 workflow 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 service 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 service 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

Workflow XAML checksums for symbols changed from SHA1 to SHA256

Details

To support debugging with Visual Studio, the Workflow runtime generates a checksum for a workflow XAML file 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 default algorithm was changed to SHA1. Starting with the .NET Framework 4.8, the default algorithm was changed to SHA256.

Suggestion

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

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

Or in configuration:

<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.Activities.UseSHA1HashForDebuggerSymbols=true" />
  </runtime>
</configuration>

Name	Value
Scope	Minor
Version	4.8
Type	Retargeting

Workflow XOML definition and SqlTrackingService cache keys changed from MD5 to SHA256

Details

The Workflow Runtime in keeps a cache of workflow definitions defined in XOML. The SqlTrackingService also keeps a cache that is keyed by strings. These caches are keyed by values that include checksum hash value. In the .NET Framework 4.7.2 and earlier versions, this checksum hashing used the MD5 algorithm, which caused issues on FIPS-enabled systems. Starting with the .NET Framework 4.8, the algorithm used is SHA256.There shouldn't be a compatibility issue with this change because the values are recalculated each time the Workflow Runtime and SqlTrackingService is started. However, we have provided quirks to allow customers to revert back to usage of the legacy hashing algorithm, if necessary.

Suggestion

If this change presents a problem when executing workflows, try setting one or both of the AppContext switches:

• "Switch.System.Workflow.Runtime.UseLegacyHashForWorkflowDefinitionDispenserCacheKey" to true.
• "Switch.System.Workflow.Runtime.UseLegacyHashForSqlTrackingCacheKey" to true. In code:

System.AppContext.SetSwitch("Switch.System.Workflow.Runtime.UseLegacyHashForWorkflowDefinitionDispenserCacheKey", true);
System.AppContext.SetSwitch("Switch.System.Workflow.Runtime.UseLegacyHashForSqlTrackingCacheKey", true);

Or in the configuration file (this needs to be in the config file for the application that is creating the WorkflowRuntime object):

<configuration>
<runtime>
<AppContextSwitchOverrides value="Switch.System.Workflow.Runtime.UseLegacyHashForWorkflowDefinitionDispenserCacheKey=true" />
<AppContextSwitchOverrides value="Switch.System.Workflow.Runtime.UseLegacyHashForSqlTrackingCacheKeytrue" />
</runtime>
</configuration>

Name	Value
Scope	Minor
Version	4.8
Type	Retargeting

Workflow XOML file checksums changed from MD5 to SHA256

Details

To support debugging XOML-based workflows with Visual Studio, when workflow projects containing XOML files build, a checksum of the contents of the XOML file is included in the code generated as a WorkflowMarkupSourceAttribute.MD5Digest value. In the .NET Framework 4.7.2 and earlier versions, this checksum hashing used the MD5 algorithm, which caused issues on FIPS-enabled systems. Starting with the .NET Framework 4.8, the algorithm used is SHA256. To be compatible with the WorkflowMarkupSourceAttribute.MD5Digest, only the first 16 bytes of the generated checksum are used.This may cause problems during debugging. You may need to re-build your project.

Suggestion

If re-building your project does not solve the problem, try setting the AppContext switch "Switch.System.Workflow.ComponentModel.UseLegacyHashForXomlFileChecksum" to true.In code:

System.AppContext.SetSwitch("Switch.System.Workflow.ComponentModel.UseLegacyHashForXomlFileChecksum", true);

Or in a configuration file (this needs to be in MSBuild.exe.config for the MSBuild.exe that you are using):

<configuration>
<runtime>
<AppContextSwitchOverrides value="Switch.System.Workflow.ComponentModel.UseLegacyHashForXomlFileChecksum=true" />
</runtime>
</configuration>

Name	Value
Scope	Minor
Version	4.8
Type	Retargeting