Retargeting Changes for Migration from .NET Framework 4.0 to 4.5

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.0 to 4.5, review the following topics for application compatibility issues that may affect your app:

ASP.NET

MachineKey.Encode and MachineKey.Decode methods are now obsolete

Details These methods are now obsolete. Compilation of code that calls these methods produces a compiler warning.
Suggestion The recommended alternatives are Protect(Byte[], String[]) and Unprotect(Byte[], String[]). Alternatively, the build warnings can be suppressed, or they can be avoided by using an older compiler. The APIs are still supported.
Scope Minor
Version 4.5
Type Retargeting
Affected APIs

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

Details In .NET Framework 4.0, extra lines were inserted between lines of a multi-line text box on postback, if using the AntiXssEncoder. In .NET Framework 4.5, those extra line breaks are not included, but only if the web app is targeting .NET Framework 4.5
Suggestion Be aware that 4.0 web apps retargeted to .NET Framework 4.5 may have multi-line text boxes improved to no longer insert extra line breaks. If this is not desirable, the app can have the old behavior when running on .NET Framework 4.5 by targeting the .NET Framework 4.0.
Scope Minor
Version 4.5
Type Retargeting

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

Details For applications that target the .NET Framework 4.5, characters that are outside the Basic Multilingual Plane (BMP) round-trip correctly when they are passed to the HtmlDecode(String) methods.
Suggestion This change should have no effect on current applications, but to restore the original behavior, set the targetFramework attribute of the <httpRuntime> element to a string other than "4.5". You can also set the unicodeEncodingConformance and unicodeDecodingConformance attributes of the <webUtility> configuration element to control this behavior independently of the targeted version of the .NET Framework.
Scope Edge
Version 4.5
Type Retargeting
Affected APIs

ClickOnce

Apps published with ClickOnce that use a SHA-256 code-signing certificate may fail on Windows 2003

Details The executable is signed with SHA256. Previously, it was signed with SHA1 regardless of whether the code-signing certificate was SHA-1 or SHA-256. This applies to:
  • All applications built with Visual Studio 2012 or later.
  • Applications built with Visual Studio 2010 or earlier on systems with the .NET Framework 4.5 present.
In addition, if the .NET Framework 4.5 or later is present, the ClickOnce manifest is also signed with SHA-256 for SHA-256 certificates regardless of the .NET Framework version against which it was compiled.
Suggestion The change in signing the ClickOnce executable affects only Windows Server 2003 systems; they require that KB 938397 be installed. The change in signing the manifest with SHA-256 even when an app targets the .NET Framework 4.0 or earlier versions introduces a runtime dependency on the .NET Framework 4.5 or a later version.
Scope Edge
Version 4.5
Type Retargeting

Core

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

Details Beginning with C# 5 (Visual Studio 2012), foreach iterator variables are scoped within the iteration. This can cause breaks if code was previously depending on the variables to not be included in the foreach's closure. The symptom of this change is that an iterator variable passed to a delegate is treated as the value it has at the time the delegate is created, rather than the value it has at the time the delegate is invoked.
Suggestion Ideally, code should be updated to expect the new compiler behavior. If the old semantics are required, the iterator variable can be replaced with a separate variable which is explicitly placed outside of the loop's scope.
Scope Major
Version 4.5
Type Retargeting

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

Details When calling TaskFactory.FromAsync, the implementation of the CompletedSynchronously property must be correct for the resulting task to complete. That is, the property must return true if, and only if, the implementation completed synchronously. Previously, the property was not checked.
Suggestion If IAsyncResult implementations correctly return true for the CompletedSynchronously property only when a task completed synchronously, then no break will be observed. Users should review IAsyncResult implementations they own (if any) to ensure that they correctly evaluate whether a task completed synchronously or not.
Scope Edge
Version 4.5
Type Retargeting
Affected APIs

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

Details Beginning in .NET Framework 4.5, a ForEach(Action<T>) enumerator will throw an InvalidOperationException exception if an element in the calling collection is modified. Previously, this would not throw an exception but could lead to race conditions.
Suggestion Ideally, code should be fixed to not modify lists while enumerating their elements because that is never a safe operation. To revert to the previous behavior, though, an app may target .NET Framework 4.0.
Scope Edge
Version 4.5
Type Retargeting
Affected APIs

System.Uri parsing adheres to RFC 3987

Details URI parsing has changed in several ways in .NET Framework 4.5. Note, however, that these changes only affect code targeting .NET Framework 4.5. If a binary targets .NET Framework 4.0, the old behavior will be observed. Changes to URI parsing in .NET Framework 4.5 include:
  • URI parsing will perform normalization and character checking according to the latest IRI rules in RFC 3987.
  • Unicode normalization form C will only be performed on the host portion of the URI.
  • Invalid mailto: URIs will now cause an exception.
  • Trailing dots at the end of a path segment are now preserved.
  • file:// URIs do not escape the ? character.
  • Unicode control characters U+0080 through U+009F are not supported.
  • Comma characters , or %2c are not automatically unescaped.
Suggestion If the old .NET Framework 4.0 URI parsing semantics are necessary (they often aren't), they can be used by targeting .NET Framework 4.0. This can be accomplished by using a TargetFrameworkAttribute on the assembly, or through Visual Studio's project system UI in the 'project properties' page.
Scope Major
Version 4.5
Type Retargeting
Affected APIs

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

Details Beginning with the .NET Framework 4.5, IsWellFormedUriString(String, UriKind) will treat relative URIs with a : in their first segment as not well formed. This is a change from IsWellFormedUriString(String, UriKind) behavior in the .NET Framework 4.0 that was made to conform to RFC3986.
Suggestion This change (like many other URI changes) will only affect applications targeting the .NET Framework 4.5 (or later). To keep using the old behavior, target the app against the .NET Framework 4.0. Alternatively, scan URI's prior to calling IsWellFormedUriString(String, UriKind) looking for : characters that you may want to remove for validation purposes, if the old behavior is desirable.
Scope Minor
Version 4.5
Type Retargeting
Affected APIs

Entity Framework

Entity Framework version must match the .NET Framework version

Details The entity framework version should be matched with the .NET framework version. Entity Framework 5 is recommended for .NET Framework 4.5. There are some known issues with EF 4.x in a .NET Framework 4.5 project around System.ComponentModel.DataAnnotations. In .NET 4.5, these were moved to a different assembly, so there are issues determining which annotations to use.
Suggestion Upgrade to Entity Framework 5 for .NET Framework 4.5
Scope Major
Version 4.5
Type Retargeting

Windows Forms

EncoderParameter ctor is obsolete

Details The EncoderParameter(Encoder, Int32, Int32, Int32, Int32) constructor is obsolete now and will introduce build warnings if used.
Suggestion Although the EncoderParameter(Encoder, Int32, Int32, Int32, Int32)constructor will continue to work, the following constructor should be used instead to avoid the obsolete build warning when re-compiling code with .NET Framework 4.5 tools: EncoderParameter(Encoder, Int32, EncoderParameterValueType, IntPtr).
Scope Minor
Version 4.5
Type Retargeting
Affected APIs

Windows Presentation Foundation (WPF)

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

Details In some cases, the Text property reflects a previous value of the databound property value if the property is modified during a databinding write operation.
Suggestion This should have no negative impact. However, you can restore the previous behavior by setting the KeepTextBoxDisplaySynchronizedWithTextProperty property to false.
Scope Edge
Version 4.5
Type Retargeting
Affected APIs

Windows Workflow Foundation (WF)

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

Details The .NET Framework 4.5 adds new overloads to Dispatcher.Invoke that include a parameter of type Action. When existing code is recompiled, compilers may resolve calls to Dispatcher.Invoke methods that have a Delegate parameter as calls to Dispatcher.Invoke methods with an Action parameter. If a call to a Dispatcher.Invoke overload with a Delegate parameter is resolved as a call to a Dispatcher.Invoke overload with an Action parameter, the following differences in behavior may occur:
Suggestion To avoid ambiguity (and potential differences in exception handling or blocking behaviors), code calling Dispatcher.Invoke can pass an empty object[] as a second parameter to the Invoke call to be sure of resolving to the .NET Framework 4.0 method overload.
Scope Minor
Version 4.5
Type Retargeting
Affected APIs

Some WorkFlow drag-and-drop APIs are obsolete

Details This WorkFlow drag-and-drop API is obsolete and will cause compiler warnings if the app is rebuilt against 4.5.
Suggestion New DragDropHelper APIs that support operations with multiple objects should be used instead. Alternatively, the build warnings can be suppressed or they can be avoided by using an older compiler. The APIs are still supported.
Scope Minor
Version 4.5
Type Retargeting
Affected APIs

WorkFlow 3.0 types are obsolete

Details Windows Workflow Foundation (WWF) 3.0 APIs (those from the System.Workflow namespace) are now obsolete.
Suggestion New WWF 4.0 APIs (in System.Activities) should be used instead. An example of using the new APIs can be found here and further guidance is available here. Alternatively, since the WWF 3.0 APIs are still supported, they may be used and the build-time warning avoided either by suppressing it or by using an older compiler.
Scope Major
Version 4.5
Type Retargeting

WorkflowDesigner.Load doesn't remove symbol property

Details When targeting the .NET Framework 4.5 in the workflow designer, and loading a re-hosted 3.5 workflow with the Load() method, a XamlDuplicateMemberException is thrown while saving the workflow.
Suggestion This bug only manifests when targeting .NET Framework 4.5 in the workflow designer, so it can be worked around by setting the WorkflowDesigner.Context.Services.GetService<DesignerConfigurationService>().TargetFrameworkName to the 4.0 .NET Framework.Alternatively, the issue may be avoided by using the Load(String) method to load the workflow, instead of Load().
Scope Major
Version 4.5
Type Retargeting
Affected APIs

XML, XSLT

XML schema validation is stricter

Details In the .NET Framework 4.5, XML schema validation is more strict. If you use xsd:anyURI to validate a URI such as a mailto protocol, validation fails if there are spaces in the URI. In previous versions of the .NET Framework, validation succeeded. The change affects only applications that target the .NET Framework 4.5.
Suggestion If looser .NET Framework 4.0 validation is needed, the validating application can target version 4.0 of the .NET Framework. When retargeting to .NET Framework 4.5, however, code review should be done to be sure that invalid URIs (with spaces) are not expected as attribute values with the anyURI data type.
Scope Minor
Version 4.5
Type Retargeting