Retargeting Changes for Migration from .NET Framework 4.6.1 to 4.6.2

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

ASP.NET

HttpRuntime.AppDomainAppPath Throws a NullReferenceException

Details

In the .NET Framework 4.6.2, the runtime throws a T:System.NullReferenceException when retrieving a P:System.Web.HttpRuntime.AppDomainAppPath value that includes null characters.In the .NET Framework 4.6.1 and earlier versions, the runtime throws an T:System.ArgumentNullException.

Suggestion

You can do either of the follow to respond to this change:

  • Handle the T:System.NullReferenceException if you application is running on the .NET Framework 4.6.2.
  • Upgrade to the .NET Framework 4.7, which restores the previous behavior and throws an T:System.ArgumentNullException.
Name Value
Scope Edge
Version 4.6.2
Type Retargeting

Affected APIs

Core

AesCryptoServiceProvider decryptor provides a reusable transform

Details

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

Suggestion

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

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

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

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

Affected APIs

Calls to ClaimsIdentity constructors

Details

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

Suggestion

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

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

Affected APIs

Changes in path normalization

Details

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

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

Suggestion

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

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

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

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

CurrentCulture and CurrentUICulture flow across tasks

Details

Beginning in the .NET Framework 4.6, System.Globalization.CultureInfo.CurrentCulture and System.Globalization.CultureInfo.CurrentUICulture are stored in the thread's System.Threading.ExecutionContext, which flows across asynchronous operations.This means that changes to System.Globalization.CultureInfo.CurrentCulture or System.Globalization.CultureInfo.CurrentUICulture will be reflected in tasks which are later run asynchronously. This is different from the behavior of previous .NET Framework versions (which would reset System.Globalization.CultureInfo.CurrentCulture and System.Globalization.CultureInfo.CurrentUICulture in all asynchronous tasks).

Suggestion

Apps affected by this change may work around it by explicitly setting the desired System.Globalization.CultureInfo.CurrentCulture or System.Globalization.CultureInfo.CurrentUICulture as the first operation in an async Task. Alternatively, the old behavior (of not flowing System.Globalization.CultureInfo.CurrentCulture/System.Globalization.CultureInfo.CurrentUICulture) may be opted into by setting the following compatibility switch:

AppContext.SetSwitch("Switch.System.Globalization.NoAsyncCurrentCulture", true);

This issue has been fixed by WPF in .NET Framework 4.6.2. It has also been fixed in .NET Frameworks 4.6, 4.6.1 through KB 3139549. Applications targeting .NET Framework 4.6 or later will automatically get the right behavior in WPF applications - System.Globalization.CultureInfo.CurrentCulture/System.Globalization.CultureInfo.CurrentUICulture) would be preserved across Dispatcher operations.

Name Value
Scope Minor
Version 4.6
Type Retargeting

Affected APIs

ETW event names cannot differ only by a "Start" or "Stop" suffix

Details

In the .NET Framework 4.6 and 4.6.1, the runtime throws an ArgumentException when two Event Tracing for Windows (ETW) event names differ only by a "Start" or "Stop" suffix (as when one event is named LogUser and another is named LogUserStart). In this case, the runtime cannot construct the event source, which cannot emit any logging.

Suggestion

To prevent the exception, ensure that no two event names differ only by a "Start" or "Stop" suffix.This requirement is removed starting with the .NET Framework 4.6.2; the runtime can disambiguate event names that differ only by the "Start" and "Stop" suffix.

Name Value
Scope Edge
Version 4.6
Type Retargeting

Long path support

Details

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

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

Suggestion

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

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

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

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

Path colon checks are stricter

Details

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

Suggestion

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

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

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

    Name Value
    Scope Edge
    Version 4.6.2
    Type Retargeting

    Affected APIs

    Security

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

    Details

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

    Suggestion

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

    Name Value
    Scope Edge
    Version 4.6.2
    Type Retargeting

    Affected APIs

    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

    Windows Communication Foundation (WCF)

    Deadlock may result when using Reentrant services

    Details

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

    [ServiceBehavior(ConcurrencyMode = ConcurrencyMode.Reentrant)]
    

    Suggestion

    To address this issue, you can do the following:

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

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

    Name Value
    Scope Minor
    Version 4.6.2
    Type Retargeting

    Affected APIs

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

    Details

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

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

    Suggestion

    To address this issue, you can do the following:

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

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

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

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

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

    Affected APIs

    WCF transport security supports certificates stored using CNG

    Details

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

    Suggestion

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

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

    This can also be done programmatically with the following code:

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

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

    Name Value
    Scope Minor
    Version 4.6.2
    Type Retargeting

    Windows Forms

    Incorrect implementation of MemberDescriptor.Equals

    Details

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

    Suggestion

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

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

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

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

    Affected APIs

    Windows Presentation Foundation (WPF)

    CurrentCulture is not preserved across WPF Dispatcher operations

    Details

    Beginning in the .NET Framework 4.6, changes to System.Globalization.CultureInfo.CurrentCulture or System.Globalization.CultureInfo.CurrentUICulture made within a System.Windows.Threading.Dispatcher will be lost at the end of that dispatcher operation. Similarly, changes to System.Globalization.CultureInfo.CurrentCulture or System.Globalization.CultureInfo.CurrentUICulture made outside of a Dispatcher operation may not be reflected when that operation executes.Practically speaking, this means that System.Globalization.CultureInfo.CurrentCulture and System.Globalization.CultureInfo.CurrentUICulture changes may not flow between WPF UI callbacks and other code in a WPF application.This is due to a change in System.Threading.ExecutionContext that causes System.Globalization.CultureInfo.CurrentCulture and System.Globalization.CultureInfo.CurrentUICulture to be stored in the execution context beginning with apps targeting the .NET Framework 4.6. WPF dispatcher operations store the execution context used to begin the operation and restore the previous context when the operation is completed. Because System.Globalization.CultureInfo.CurrentCulture and System.Globalization.CultureInfo.CurrentUICulture are now part of that context, changes to them within a dispatcher operation are not persisted outside of the operation.

    Suggestion

    Apps affected by this change may work around it by storing the desired System.Globalization.CultureInfo.CurrentCulture or System.Globalization.CultureInfo.CurrentUICulture in a field and checking in all Dispatcher operation bodies (including UI event callback handlers) that the correct System.Globalization.CultureInfo.CurrentCulture and System.Globalization.CultureInfo.CurrentUICulture are set. Alternatively, because the ExecutionContext change underlying this WPF change only affects apps targeting the .NET Framework 4.6 or newer, this break can be avoided by targeting the .NET Framework 4.5.2.Apps that target .NET Framework 4.6 or later can also work around this by setting the following compatibility switch:

    AppContext.SetSwitch("Switch.System.Globalization.NoAsyncCurrentCulture", true);
    

    This issue has been fixed by WPF in .NET Framework 4.6.2. It has also been fixed in .NET Frameworks 4.6, 4.6.1 through KB 3139549. Applications targeting .NET Framework 4.6 or later will automatically get the right behavior in WPF applications - System.Globalization.CultureInfo.CurrentCulture/System.Globalization.CultureInfo.CurrentUICulture) would be preserved across Dispatcher operations.

    Name Value
    Scope Minor
    Version 4.6
    Type Retargeting