有关迁移到 .NET Framework 4.5.x 的操作的重定向目标更改

项目
08/16/2023

本文列出了在 .NET Framework 4.5、4.5.1 和 4.5.2 中引入的应用兼容性问题。

.NET Framework 4.5

ASP.NET

MachineKey.Encode 和 MachineKey.Decode 方法现已过时

详细信息

这些方法现在已过时。调用这些方法的代码编译会产生编译器警告。

建议

建议的替代项为 Protect(Byte[], String[]) 和 Unprotect(Byte[], String[])。或者，可以禁止显示生成警告，也可以使用较早的编译器避免出现此类警告。 API 仍受支持。

“属性”	值
范围	次要
Version	4.5
类型	重定目标

受影响的 API

使用 AntiXSSEncoder 时，多行 ASP.NET 文本框间距已更改

详细信息

在 .NET Framework 4.0 中，如果使用 System.Web.Security.AntiXss.AntiXssEncoder，则多余行将插入回发的多行文本框中的各行之间。在 .NET Framework 4.5 中，不包括这些多余的换行符，仅在 Web 应用面向 .NET Framework 4.5 时才可包含

建议

请注意，重定向到 .NET Framework 4.5 的 4.0 Web 应用可能改进了多行文本框，从而不再插入多余的换行符。如果不需要这样做，当应用在 .NET Framework 4.5 上运行时，通过面向 .NET Framework 4.0 可使用旧行为。

名称	值
范围	次要
Version	4.5
类型	重定目标

WebUtility.HtmlEncode 和 WebUtility.HtmlDecode 正确往返 BMP

详细信息

对于面向 .NET Framework 4.5 的应用程序，当基本多语言平面 (BMP) 外的字符传递给 HtmlDecode(String) 方法时，这些字符可正确往返。

建议

此更改不应影响当前应用程序，但要还原原始行为，请将 <httpRuntime> 元素的 targetFramework 属性设置为“4.5”以外的字符串。还可以设置 unicodeEncodingConformance 配置元素的 unicodeDecodingConformance 和 <webUtility> 特性以单独控制 .NET Framework 的目标版本的行为。

“属性”	值
范围	边缘
Version	4.5
类型	重定目标

受影响的 API

ClickOnce

通过 ClickOnce 使用 SHA-256 代码签名证书发布的应用在 Windows 2003 中可能会失败

详细信息

使用 SHA256 对可执行文件签名。以前，无论代码签名证书是 SHA-1 还是 SHA-256，都使用 SHA1 进行签名。这适用于：

使用 Visual Studio 2012 或更高版本生成的所有应用程序。
使用 Visual Studio 2010 或更早版本在安装了 .NET Framework 4.5 的系统上生成的应用程序。此外，如果安装了 .NET Framework 4.5 或更高版本，则 ClickOnce 清单也会采用 SHA-256 签名，因为 SHA-256 证书与编译所采用的 .NET Framework 版本无关。

建议

更改 ClickOnce 可执行文件的签名仅影响 Windows Server 2003 系统；它们需要安装 KB 938397。即使应用是面向 .NET Framework 4.0 或早期版本，对使用 SHA-256 签名的清单进行更改，将引入依赖 .NET Framework 4.5 或更高版本的运行时。

“属性”	值
范围	边缘
Version	4.5
类型	重定目标

核心

Foreach 迭代器变量现在已在迭代范围内，因此闭包捕获语义会不同（在 C#5 中）

详细信息

从 C# 5 (Visual Studio 2012) 开始，foreach 迭代器变量在迭代范围内。如果代码以前依靠变量而不在 foreach 闭包内，这可能会导致中断。此更改的特征如下：传递到委托的迭代器变量将视为委托创建时它拥有的值，而非调用委托时它拥有的值。

建议

理想情况下，应更新代码以使用新的编译器行为。如果需要旧语义，迭代器变量可替换为显式置于循环范围外的单独变量。

“属性”	值
范围	主要
Version	4.5
类型	重定目标

IAsyncResult.CompletedSynchronously 属性必须正确，才能完成生成的任务

详细信息

在调用 TaskFactory.FromAsync 时，必须正确实现 CompletedSynchronously 属性，才能完成生成的任务。即，当且仅当同步完成实现时，该属性才应返回 true。之前，属性未被选中。

建议

如果仅在任务同步完成时，System.IAsyncResult 实现才为 System.IAsyncResult.CompletedSynchronously 属性正确返回 true，将观察不到任何中断。用户应查看所拥有的 System.IAsyncResult 实现（如果有），确保能够正确评估某项任务是否同步完成。

“属性”	值
范围	边缘
Version	4.5
类型	重定目标

受影响的 API

List<T>.ForEach 在修改列表项时可能会引发异常

详细信息

从 .NET Framework 4.5 开始，如果修改了调用集合中的元素，ForEach(Action<T>) 枚举器将引发 System.InvalidOperationException 异常。该操作在以前不会引发异常，但可能会导致争用条件。

建议

理想情况下，应修复代码以便在枚举列表元素时不会修改列表，因为这始终不是安全操作。但是，若要还原到以前的行为，应用可面向 .NET Framework 4.0。

“属性”	值
范围	边缘
Version	4.5
类型	重定目标

受影响的 API

List<T>.ForEach(Action<T>)

System.Uri 分析符合 RFC 3987

详细信息

在 .NET Framework 4.5 中，对 URI 分析做了几方面的更改。但请注意，这些更改仅影响面向 .NET Framework 4.5 的代码。如果二进制文件面向 .NET Framework 4.0，则将遵守旧行为。 .NET Framework 4.5 中对 URI 分析所做的更改包括：

URI 分析将根据 RFC 3987 中的最新 IRI 规则执行规范化和字符检查。
将仅对 URI 的主机部分执行 Unicode 范式 C。
无效 mailto：URI 现在会抛出异常。
现在将保留路径段末尾的尾随点。
file:// URI 不会转义 ? 字符。
不支持从 U+0080 到 U+009F 的 Unicode 控制字符。
逗号字符 , 或 %2c 不会自动取消转义。

建议

如果需要使用旧的 .NET Framework 4.0 URI 分析语义（通常不需要），可通过面向 .NET Framework 4.0 使用它们。这可通过在程序集上使用 System.Runtime.Versioning.TargetFrameworkAttribute 来实现，也可以通过“项目属性”页中 Visual Studio 的项目系统 UI 来实现。

“属性”	值
范围	主要
Version	4.5
类型	重定目标

受影响的 API

System.Uri.IsWellFormedUriString 方法为第一个段中具有冒号字符型的相对 URI 返回 false

详细信息

从 .NET Framework 4.5 开始，IsWellFormedUriString(String, UriKind) 会将第一个段中带有 : 的相对 URI 视为格式不正确。这是 .NET Framework 4.0 中 System.Uri.IsWellFormedUriString(String, UriKind) 行为的更改，以符合 RFC3986。

建议

此更改（与许多其他 URI 更改一样）仅影响以 .NET Framework 4.5（或更高版本）为目标的应用程序。要继续使用旧行为，请使应用以 .NET Framework 4.0 为目标。或者，调用 System.Uri.IsWellFormedUriString(String, UriKind) 前扫描 URI，查找出于验证目的想要删除的 : 字符（如果旧行为是可取的）。

“属性”	值
范围	次要
Version	4.5
类型	重定目标

受影响的 API

Uri.IsWellFormedUriString(String, UriKind)

Entity Framework

Entity Framework 版本必须与 .NET Framework 版本匹配

详细信息

Entity Framework (EF) 版本应与 .NET Framework 版本匹配。 Entity Framework 5 推荐用于 .NET Framework 4.5。在与 System.ComponentModel.DataAnnotations 相关的 .NET Framework 4.5 项目中，存在一些已知的 EF 4.x 问题。在 .NET Framework 4.5 中，它们被移动到了另一程序集，因此确定要使用的注释时会出现问题。

建议

对于 .NET Framework 4.5 升级到 Entity Framework 5

“属性”	值
范围	主要
Version	4.5
类型	重定目标

Windows 窗体

EncoderParameter ctor 已过时

详细信息

EncoderParameter(Encoder, Int32, Int32, Int32, Int32) 构造函数现已过时，使用它将引发生成警告。

建议

虽然 EncoderParameter(Encoder, Int32, Int32, Int32, Int32) 构造函数仍将继续有效，但还是应该改用以下构造函数，以避免在使用 .NET Framework 4.5 工具重新编译代码时出现已过时的生成警告：EncoderParameter(Encoder, Int32, EncoderParameterValueType, IntPtr)。

名称	值
范围	次要
Version	4.5
类型	重定目标

受影响的 API

EncoderParameter(Encoder, Int32, Int32, Int32, Int32)

Windows Communication Foundation (WCF)

使用 BodyWriter 编写二进制输出

详细信息

如果要从 System.ServiceModel.Channels.BodyWriter 类派生并使用 OnWriteBodyContents(XmlDictionaryWriter writer) 的实现来编写二进制输出，则当重定向到 .NET Framework 4.5 时，可能需要进行一些更改。检查写入状态，如果是 WriterState.Start，则发出 Binary 换行 XML 元素，如以下代码片段所示。

protected override void OnWriteBodyContents(XmlDictionaryWriter writer)
{
    bool wroteStartElement = false;
    if (writer.WriteState == WriteState.Start)
    {
        writer.WriteStartElement("Binary", string.Empty);
        wroteStartElement = true;
    }
    writer.WriteBase64(buffer, offset, count);
    if (wroteStartElement)
    {
        writer.WriteEndElement();
    }
}

此外，如果要从类 System.ServiceModel.Channels.StreamBodyWriter 派生并重写方法 OnWriteBodyContents(XmlDictionaryWriter writer)，可能需要进行一些更改。目标为 .NET Framework 4.0 时，重写此方法时必须显式写入 Binary 元素。目标为 .NET Framework 4.5 时，不再需要此操作，因为这样会导致无法写入正文。

Windows Presentation Foundation (WPF)

WPF TextBox.Text 可能与数据绑定不同步

详细信息

在某些情况下，如果在数据绑定的写入操作期间修改属性，则 Text 属性会反映数据绑定属性值的以前的值。

建议

这不应有负面影响。不过，你可以通过将 KeepTextBoxDisplaySynchronizedWithTextProperty 属性设置为 false 来还原以前的行为。

	值
范围	边缘
版本	4.5
类型	重定目标

受影响的 API

TextBox.Text

Windows Workflow Foundation (WF)

新的（不明确的）Dispatcher.Invoke 重载可能导致不同的行为

详细信息

.NET Framework 4.5 将新重载添加到包括 Action 类型参数的 Dispatcher.Invoke。在重新编译现有代码时，编译器可能将对具有 Delegate 参数的 Dispatcher.Invoke 方法的调用解析为对具有 Action 参数的 Dispatcher.Invoke 方法的调用。如果将对具有 Delegate 参数的 Dispatcher.Invoke 重载的调用解析为对具有 Action 参数的 Dispatcher.Invoke 重载的调用，可能出现以下行为差异：

如果出现异常，则不引发 UnhandledExceptionFilter 和 UnhandledException 事件。相反，通过 System.Threading.Tasks.TaskScheduler.UnobservedTaskException 事件处理异常。
对某些成员（如 Result）的调用会受阻，直到操作完成。

建议

若要避免出现多义性（以及异常处理或阻止行为中可能出现的差异），调用 Dispatcher.Invoke 的代码可传递空 object[] 作为 Invoke 调用的第二个参数，确保解析为 .NET Framework 4.0 方法重载。

“属性”	值
范围	次要
Version	4.5
类型	重定目标

受影响的 API

某些工作流拖放 API 已过时

详细信息

此工作流拖放 API 已过时，如果针对 4.5 重新生成应用，将引发编译器警告。

建议

应改用支持包含多个对象的操作的新 System.Activities.Presentation.DragDropHelper API。或者，可以禁止显示生成警告，也可以使用较早的编译器避免出现此类警告。 API 仍受支持。

“属性”	值
范围	次要
Version	4.5
类型	重定目标

受影响的 API

WorkFlow 3.0 类型已过时

详细信息

Windows Workflow Foundation (WWF) 3.0 API（来自于 System.Workflow 命名空间）现已过时。

建议

应改用新的 WWF 4.0 API（在 System.Activities 中）。可在此处找到使用新 API 的示例，此处还提供更深入的指导。或者，由于仍然支持 WWF 3.0 API，因此可能会使用它们，通过禁止显示生成时警告或使用较旧的编译器可以避免出现该警告。

“属性”	值
范围	主要
Version	4.5
类型	重定目标

WorkflowDesigner.Load 不会删除符号属性

详细信息

当在工作流设计器中面向 .NET Framework 4.5，并使用 Load() 方法加载重新托管的 3.5 工作流时，保存该工作流的同时将引发 System.Xaml.XamlDuplicateMemberException。

建议

此 bug 仅当在工作流设计器中面向 .NET Framework 4.5 时才显示，因此可通过将 WorkflowDesigner.Context.Services.GetService<DesignerConfigurationService>().TargetFrameworkName 设为 4.0 .NET Framework 进行解决。

或者，通过使用 Load(String) 方法（而不是 Load()）加载工作流，可以避免此问题。

名称	值
范围	主要
Version	4.5
类型	重定目标

受影响的 API

WorkflowDesigner.Load()

XML、XSLT

XML 架构验证更为严格

详细信息

在 .NET Framework 4.5 中，XML 架构验证更为严格。如果使用 xsd:anyURI 来验证 URL（如 mailto 协议），则当 URL 中有空格时，验证将失败。在 .NET Framework 的早期版本中，验证将成功。此更改仅影响面向 .NET Framework 4.5 的应用程序。

建议

如果需要更宽松的 .NET Framework 4.0 验证，该验证应用程序可以面向版本 4.0 的 .NET Framework。但是，重定向到 .NET Framework 4.5 时，应执行代码评审，确保无效的 URI（包含空格）不会作为 anyURI 数据类型的属性值。

“属性”	值
范围	次要
Version	4.5
类型	重定目标

.NET Framework 4.5.1

ADO.NET

DbParameter.Precision 和 DbParameter.Scale 现在是公共虚拟成员

详细信息

实现 Precision 和 Scale 将实现为公共虚拟属性。它们替换相应的显示接口实现、IDbDataParameter.Precision 和 IDbDataParameter.Scale。

建议

在重新生成 ADO.NET 数据库提供程序时，这些差异要求将“override”关键字应用到 Precision 和 Scale 属性。仅在重新生成组件时才需要这样做；现有二进制文件将继续运行。

“属性”	值
范围	次要
Version	4.5.1
类型	重定目标

受影响的 API

核心

ObsoleteAttribute 在 WinMD 方案中导出为 ObsoleteAttribute 和 DeprecatedAttribute

详细信息

创建 Windows 元数据库（.winmd 文件）时，System.ObsoleteAttribute 属性将导出为 System.ObsoleteAttribute 和 Windows.Foundation.DeprecatedAttribute。

建议

重新编译使用 System.ObsoleteAttribute 属性的现有源代码可能会在从 C++/CX 或 JavaScript 使用该代码时生成警告。我们不建议将 System.ObsoleteAttribute 和 Windows.Foundation.DeprecatedAttribute 同时用于托管程序集中的代码，这可能会导致生成警告。

“属性”	值
范围	边缘
Version	4.5.1
类型	重定目标

Entity Framework

如果使用 EntityDeploySplit 或 EntityClean 任务，使用 Visual Studio 2013 生成 Entity Framework edmx 会失败，错误编码为 MSB4062

详细信息

MSBuild 12.0 工具（包括在 Visual Studio 2013 中）更改了 MSBuild 文件位置，使得旧 Entity Framework 目标文件变为无效文件。结果是 EntityDeploySplit 和 EntityClean 任务失败，因为它们无法找到 Microsoft.Data.Entity.Build.Tasks.dll。请注意，此中断是由于工具集 (MSBuild/VS) 更改而引起的，并不是因为 .NET Framework 更改。它仅在升级开发人员工具时才会发生，仅升级 .NET Framework 不会发生。

建议

从 .NET Framework 4.6 开始，Entity Framework 目标文件已修复，可与新 MSBuild 布局一起使用。升级到该版本的 Framework 将解决此问题。或者，可使用此解决方法直接修补目标文件。

“属性”	值
范围	主要
Version	4.5.1
类型	重定目标

MSBuild

ResolveAssemblyReference 任务现在将对体系结构错误的依赖项发出警告

详细信息

此任务发出警告 MSB3270，它表示引用或任何依赖项不匹配应用程序的体系结构。例如，如果使用 AnyCPU 选项编译的应用程序包括 x86 引用，则会发生此情况。这样的情况可能导致运行时应用失败（在本例中为，如果应用部署为 x64 过程）。

建议

有两方面的影响：

重新编译将生成警告，当应用在以前版本的 MSBuild 下编译时，此类警告未显示。但是，由于该警告可标识运行时失败可能的来源，所以应该调查并处理它。
如果警告被视为错误，则应用将无法进行编译。

“属性”	值
范围	次要
Version	4.5.1
类型	重定目标

Windows Presentation Foundation (WPF)

不支持对具有非公共资源库的属性的双向数据绑定

详细信息

尝试将数据绑定到没有公共资源库的方案从未受支持。从 .NET Framework 4.5.1 开始，此方案将引发 System.InvalidOperationException。请注意，仅专门面向 .NET Framework 4.5.1 的应用会引发此新异常。如果应用面向 .NET Framework 4.5，将允许该调用。如果应用不面向特定 .NET Framework 版本，绑定将视为单向绑定。

建议

应更新应用以使用单向绑定，或公开公布属性的资源库。或者，面向 .NET Framework 4.5 将使应用展示旧行为。

“属性”	值
范围	次要
Version	4.5.1
类型	重定目标

受影响的 API

BindingMode.TwoWay

.NET Framework 4.5.2

Visual Basic .NET

VB.NET 不再支持 System.Windows API 的部分命名空间限定

详细信息

从 .NET Framework 4.5.2 开始，VB.NET 项目无法通过部分限定命名空间指定 System.Windows API。例如，对 Windows.Forms.DialogResult 的引用将失败。而代码必须引用完全限定名称 (DialogResult)，或导入特定命名空间并仅引用 System.Windows.Forms.DialogResult。

建议

应更新代码，以使用简单名称（并导入相关命名空间）或使用完全限定名称来引用 System.Windows API。

“属性”	值
范围	次要
Version	4.5.2
类型	重定目标

Windows 窗体

DataObject.GetData 现在将数据检索为 UTF-8

详细信息

对于面向 .NET Framework 4 或者在 .NET Framework 4.5.1 或更早版本上运行的应用，DataObject.GetData 将 HTML 格式的数据检索为 ASCII 字符串。因此，非 ASCII 字符（ASCII 代码大于 0x7F 的字符）由两个随机字符表示。

对于面向 .NET Framework 4.5 或更高版本以及在 .NET Framework 4.5.2 上运行的应用，DataObject.GetData 将 HTML 格式的数据检索为 UTF-8，从而可以正确表示大于 0x7F 的字符。

建议

如果使用 HTML 格式的字符串实现了编码问题的解决方法（例如，通过将其传递到 System.Text.UTF8Encoding.GetString(Byte[], Int32, Int32) 来显式编码从剪贴板检索的 HTML 字符串），而且要将应用的目标从版本 4 重定为 4.5，则应该删除该解决方法。如果出于某种原因需要使用以前的版本，该应用可面向 .NET Framework 4.0 来获取该行为。

“属性”	值
范围	边缘
Version	4.5.2
类型	重定目标

受影响的 API

Windows Workflow Foundation (WF)

WorkflowDesigner.Load 不会删除符号属性

详细信息

当在工作流设计器中面向 .NET Framework 4.5，并使用 Load() 方法加载重新托管的 3.5 工作流时，保存该工作流的同时将引发 System.Xaml.XamlDuplicateMemberException。

建议

或者，通过使用 Load(String) 方法（而不是 Load()）加载工作流，可以避免此问题。

名称	值
范围	主要
Version	4.5
类型	重定目标

受影响的 API

WorkflowDesigner.Load()