Edit

Retargeting Changes for Migration from .NET Framework 4.7.1 to 4.7.2

  • Article
  • 19 minutes to read

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

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

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

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

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

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

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

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)

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

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)

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