Retargeting Changes for Migration from .NET Framework 4.6 to 4.6.1

Introduction

Retargeting changes affect apps that are recompiled to target a different .NET Framework. They include:

  • Changes in the design-time environment. For example, build tools may emit warnings when previously they did not.

  • Changes in the runtime environment. These affect only apps that specifically target the retargeted .NET Framework. Apps that target previous versions of the .NET Framework behave as they did when running under those versions.

In the topics that describe retargeting changes, we have classified individual items by their expected impact, as follows:

Major This is a significant change that affects a large number of apps or that requires substantial modification of code.

Minor This is a change that affects a small number of apps or that requires minor modification of code.

Edge case This is a change that affects apps under very specific scenarios that are not common.

Transparent This is a change that has no noticeable effect on the app's developer or user. The app should not require modification because of this change.

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

Core

Change in path separator character in FullName property of ZipArchiveEntry objects

Details For apps that target the .NET Framework 4.6.1 and later versions, the path separator character has changed from a backslash ("") to a forward slash ("/") in the FullName property of ZipArchiveEntry objects created by overloads of the CreateFromDirectory method. The change brings the .NET implementation into conformity with section 4.4.17.1 of the .ZIP File Format Specification and allows .ZIP archives to be decompressed on non-Windows systems.
Decompressing a zip file created by an app that targets a previous version of the .NET Framework on non-Windows operating systems such as the Macintosh fails to preserve the directory structure. For example, on the Macintosh, it creates a set of files whose filename concatenates the directory path, along with any backslash ("") characters, and the filename. As a result, the directory structure of decompressed files is not preserved.
Suggestion The impact of this change on .ZIP files that are decompressed on the Windows operating system by APIs in the .NET Framework System.IO namespace should be minimal, since these APIs can seamlessly handle either a forward slash ("/") or a backslash ("") as the path separator character.
If this change is undesirable, you can opt out of it by adding a configuration setting to the < section of your application configuration file. The following example shows both the <runtime> section and the Switch.System.IO.Compression.ZipFile.UseBackslash opt-out switch:
<runtime>
<AppContextSwitchOverrides value="Switch.System.IO.Compression.ZipFile.UseBackslash=true" />
</runtime>
In addition, apps that target previous versions of the .NET Framework but are running on the .NET Framework 4.6.1 and later versions can opt in to this behavior by adding a configuration setting to the < section of the application configuration file. The following shows both the <runtime> section and the Switch.System.IO.Compression.ZipFile.UseBackslash opt-in switch.
<runtime>
<AppContextSwitchOverrides value="Switch.System.IO.Compression.ZipFile.UseBackslash=false" />
</runtime>
Scope Edge
Version 4.6.1
Type Retargeting
Affected APIs

Windows Communication Foundation (WCF)

WCF binding with the TransportWithMessageCredential security mode

Details Beginning in the .NET Framework 4.6.1, WCF binding that uses the TransportWithMessageCredential security mode can be set up to receive messages with unsigned "to" headers for asymmetric security keys.By default, unsigned "to" headers will continue to be rejected in .NET Framework 4.6.1. They will only be accepted if an application opts into this new mode of operation using the Switch.System.ServiceModel.AllowUnsignedToHeader configuration switch.
Suggestion Because this is an opt-in feature, it should not affect the behavior of existing apps.
To control whether the new behavior is used or not, use the following configuration setting:
<runtime>
<AppContextSwitchOverrides value="Switch.System.ServiceModel.AllowUnsignedToHeader=true" />
</runtime>
Scope Transparent
Version 4.6.1
Type Retargeting
Affected APIs

X509CertificateClaimSet.FindClaims Considers All claimTypes

Details In apps that target the .NET Framework 4.6.1, if an X509 claim set is initialized from a certificate that has multiple DNS entries in its SAN field, the FindClaims(String, String) method attempts to match the claimType argument with all the DNS entries.For apps that target previous versions of the .NET Framework, the FindClaims(String, String) method attempts to match the claimType argument only with the last DNS entry.
Suggestion This change only affects applications targeting the .NET Framework 4.6.1. This change may be disabled (or enabled if targetting pre-4.6.1) with the DisableMultipleDNSEntries compatibility switch.
Scope Minor
Version 4.6.1
Type Retargeting
Affected APIs

Windows Forms

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

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

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

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

Windows Presentation Foundation (WPF)

Calls to System.Windows.Input.PenContext.Disable on touch-enabled systems may throw an ArgumentException

Details Under some circumstances, calls to the internal System.Windows.Intput.PenContext.Disable method on touch-enabled systems may throw an unhandled T:System.ArgumentException because of reentrancy.
Suggestion This issue has been addressed in the .NET Framework 4.7. To prevent the exception, upgrade to a version of the .NET Framework starting with the .NET Framework 4.7.
Scope Edge
Version 4.6.1
Type Retargeting