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

2025-06-19

本文列出了 .NET Framework 4.8 和 4.8.1 中引入的应用兼容性问题。

.NET Framework 4.8

核心

托管加密类不会在 FIPS 模式下引发 CryptographyException

详细信息

在 .NET framework 4.7.2 及更低版本中，当在 FIPS 模式下配置系统加密库时，SHA256Managed 等托管加密提供程序类会引发 CryptographicException。引发这些异常的原因是托管版本未经过 FIPS（联邦信息处理标准）140-2 认证，以及没有阻止根据 FIPS 规则规定未被认可的加密算法。由于很少有开发人员将其开发计算机置于 FIPS 模式下，因此这些异常通常仅在生产系统上引发。面向 .NET Framework 4.8 及更高版本的应用程序会自动切换到新的且宽松的策略，以便在这种情况下默认不再引发 CryptographicException。相反，托管加密类会将加密作重定向到系统加密库。此策略更改实际上消除了开发人员环境与生产环境之间的潜在混淆差异，并使本机组件和托管组件在同一加密策略下运行。

建议

如果不希望出现这种情况，可以选择退出该行为并还原上述行为，方法是将以下 CryptographicException 配置设置添加到应用程序配置文件的 > 部分中，以便在 FIPS 模式下引发：

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

如果应用程序以 .NET Framework 4.7.2 或更早版本为目标，则还可以通过将以下 AppContextSwitchOverrides 配置设置添加到应用程序配置文件的<运行时>部分来选择加入此更改：

<runtime>
  <AppContextSwitchOverrides value="Switch.System.Security.Cryptography.UseLegacyFipsThrow=false" />
</runtime>

名称	价值
范围	Microsoft Edge
版本	4.8
类型	重定目标

受影响的 API

Windows 窗体

适用于 .NET 4.8 的 Windows 窗体控件中的辅助功能改进

详细信息

Windows 窗体框架将继续改进它与辅助功能技术配合使用的方式，以更好地支持 Windows 窗体客户。其中包括以下更改：

更改以提高高对比度模式期间的显示效果。
对讲述人交互的更改。
无障碍层次结构中的更改（改进通过 UI 自动化树的导航）。

建议

如何选择加入或退出这些更改 为了使应用程序受益于这些更改，它必须在 .NET Framework 4.8 上运行。应用程序可以通过以下任一方式选择加入这些更改：

该程序已重新编译以面向 .NET Framework 4.8。默认情况下，这些无障碍功能更改在面向 .NET Framework 4.8 的 Windows 窗体应用程序中启用。
它面向 .NET Framework 4.7.2 或更低版本，通过向应用配置文件的部分添加以下 <runtime>并将其设置为 false，可选择弃用旧版辅助功能行为，如下例所示。

<?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;Switch.UseLegacyAccessibilityFeatures.3=false" />
  </runtime>
</configuration>

请注意，若要选择加入 .NET Framework 4.8 中添加的辅助功能，还必须选择加入 .NET Framework 4.7.1 和 4.7.2 的辅助功能。面向 .NET Framework 4.8 且希望保留旧版辅助功能行为的应用程序可以通过将此 AppContext 开关显式设置为 true 来选择加入使用旧版辅助功能。启用键盘 ToolTip 调用支持需要将 Switch.System.Windows.Forms.UseLegacyToolTipDisplay=false 行添加到 AppContextSwitchOverrides 值：

<AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures=false;Switch.UseLegacyAccessibilityFeatures.2=false;Switch.UseLegacyAccessibilityFeatures.3=false;Switch.System.Windows.Forms.UseLegacyToolTipDisplay=false" />

请注意，启用此功能需要选择加入上述 .NET Framework 4.7.1 到 4.8 的辅助功能。此外，如果未选择加入任何辅助功能，但选择加入了工具提示显示功能，则首次访问这些功能时将引发运行时 NotSupportedException。异常消息表明键盘工具提示需要启用第 3 级辅助功能改进。

在高对比度主题中使用由操作系统定义的颜色

改进了高对比度主题。

改进了讲述人支持

在说出 DataGridViewColumn 的辅助功能名称时，讲述人现在会说出 DataGridViewCell 的排序方向。

改进了 CheckedListBox 的无障碍支持

改进了 CheckedListBox 控件的讲述人支持。使用键盘导航到 CheckedListBox 控件时，讲述人会聚焦于 CheckedListBox 项目并读出它。
控件变得聚焦时，空的 CheckedListBox 控件现包含为第一个虚拟项绘制的焦点矩形。

改进了 ComboBox 无障碍功能支持

已启用对控件的 ComboBox UI 自动化支持，并且能够使用 UI 自动化通知和其他 UI 自动化功能。 改进了 DataGridView 辅助功能支持
已启用对DataGridView控件的 UI 自动化支持，能够使用 UI 自动化通知和其他 UI 自动化功能。
与DataGridViewComboBoxEditingControl或DataGridViewTextBoxEditingControl对应的 UI 自动化元素现在是相应编辑单元格的子元素。

改进了 LinkLabel 辅助功能支持

改进了 LinkLabel 控件可访问性：如果禁用了相应的 LinkLabel 控件，讲述人将报出链接的禁用状态。

提升了 ProgressBar 的无障碍支持

启用了 UI 自动化对 ProgressBar 控件的支持，并且能够使用 UI 自动化通知和其他 UI 自动化功能。开发人员现在能够使用讲述人可以宣布的 UI 自动化通知来指示进度。有关 UI 自动化事件概述（包括 UI 自动化通知事件）的概述，请参阅 UI 自动化事件概述。

改进了 PropertyGrid 辅助功能支持

已启用对控件的 PropertyGrid UI 自动化支持，并且能够使用 UI 自动化通知和其他 UI 自动化功能。
对应于当前编辑属性的 UI 自动化元素现在是相应属性项 UI 自动化元素的子元素。
如果父 PropertyGrid 控件设置为类别视图，则 UI 自动化属性项元素现在是相应类别元素的子元素。

改进了 ToolStrip 支持

已启用对控件的 ToolStrip UI 自动化支持，并且能够使用 UI 自动化通知和其他 UI 自动化功能。
改进了对 ToolStrip 项的导航。
在项目模式下，讲述人焦点不会消失，也不会转到隐藏的项目。

改进了视觉指示

现在，空的 CheckedListBox 控件在获得焦点时会显示焦点指示器。注意：UI 自动化支持在运行时为控件启用，但在设计时未使用。有关 UI 自动化的概述，请参阅 UI 自动化概述。

使用键盘调用控件的工具提示

现在可以通过使用键盘将控件聚焦来调用控件工具提示。需要为应用程序显式启用此功能（请参阅 “如何选择加入或退出这些更改”部分）

名称	价值
范围	主要
版本	4.8
类型	重定目标

Windows Presentation Foundation （WPF）

WPF 中辅助功能的改进

详细信息

高对比度改进

Expander 控件的焦点现在可见。在早期版本的 .NET Framework 中，它不是。
CheckBox 和 RadioButton 控件中的文本在选中时，比之前的 .NET Framework 版本更易查看。
禁用 ComboBox 的边框现在与禁用的文本的颜色相同。在早期版本的 .NET Framework 中，它不是。
禁用和聚焦按钮现在使用正确的主题颜色。在早期版本的 .NET Framework 中，这种情况没有发生。
当 ComboBox 控件的样式设置为 ToolBar.ComboBoxStyleKey 时，下拉按钮现在可见。在早期版本的 .NET Framework 中，它不是。
DataGrid 控件中的排序指示器箭头现在使用主题颜色。在先前版本的 .NET Framework 中，并非如此。
默认超链接样式现在会在鼠标悬停时更改为正确的主题颜色。在先前版本的 .NET Framework 中，并非如此。
单选按钮上的键盘焦点现在可见。在早期版本的 .NET Framework 中，它不是。
现在 DataGrid 控件的复选框列对键盘焦点反馈使用预期的颜色。在先前版本的 .NET Framework 中，并非如此。
键盘焦点视觉对象现在在 ComboBox 和 ListBox 控件上可见。在早期版本的 .NET Framework 中，它不是。

屏幕阅读器交互改进

屏幕阅读器现在正确地将 Expander 控件称为组（展开/折叠）。
屏幕阅读器现在正确地将 DataGridCell 控件称为数据网格单元格（已本地化）。
屏幕阅读器现在将宣布可编辑的 ComboBox 的名称。
PasswordBox 控件不再被屏幕阅读器称为“视图中没有任何项”。

LiveRegion 支持

屏幕阅读器（如讲述人）通常通过描述当前具有焦点的 UI 元素来帮助人们了解应用程序的用户界面（UI）。但是，如果 UI 元素在屏幕中的某个位置发生更改，并且没有焦点，则可能不会通知用户并错过重要信息。 LiveRegions 旨在解决此问题。开发人员可以使用它们通知屏幕阅读器或任何其他 UI 自动化客户端对 UI 元素进行了重要更改。然后，屏幕阅读器可以决定如何以及何时通知用户此更改。 LiveSetting 属性还使屏幕阅读器知道通知用户对 UI 所做的更改有多重要。

建议

如何选择加入或退出这些更改

为了使应用程序受益于这些更改，它必须在 .NET Framework 4.7.1 或更高版本上运行。应用程序可以通过以下任一方式受益于这些更改：

面向 .NET Framework 4.7.1。这是建议的方法。对于面向 .NET Framework 4.7.1 或更高版本的 WPF 应用程序，这些辅助功能默认启用。

通过向应用配置文件的部分添加以下 <runtime>并将其设置为 false，可选择弃用旧版辅助功能行为，如下例所示。

<?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" />
  </runtime>
</configuration>

如果应用程序面向 .NET Framework 4.7.1 或更高版本并希望保留旧版辅助功能行为，则它们可通过将此 AppContext 开关显式设置为 true 来选择启用旧版辅助功能。有关 UI 自动化的概述，请参阅 UI 自动化概述。

名称	价值
范围	主要
版本	4.7.1
类型	重定目标

受影响的 API

将 SelectionTextBrush 公共属性添加到 TextBox/PasswordBox 非装饰器选择功能

详细信息

在使用和 TextBox 的PasswordBox的 WPF 应用程序中，开发人员现在可以设置新添加的 SelectionTextBrush 属性，以便更改所选文本的呈现。默认情况下，此颜色随 HighlightTextBrushKey 一起变化。如果未启用基于非修饰器的文本选择功能，则此属性不执行任何操作。

建议

启用非装饰器文本选择后，可以使用 PasswordBox.SelectionTextBrush 和 SelectionTextBrush 属性更改所选文本的外观。可以使用 XAML 实现此目的：

<TextBox SelectionBrush="Red" SelectionTextBrush="White"  SelectionOpacity="0.5"
Foreground="Blue" CaretBrush="Blue">
This is some text.
</TextBox>

名称	价值
范围	主要
版本	4.8
类型	重定目标

受影响的 API

HwndHost 现可在 DPI 更改期间正确重设子 HWND 的大小

详细信息

在 .NET Framework 4.7.2 及更低版本中，当 WPF 在 Per-Monitor 感知模式下运行时，DPI 更改后托管的 HwndHost 控件未正确调整大小，例如将应用程序从一个监视器移动到另一个监视器时。此修补程序可确保适当调整托管控件的大小。

建议

为了使应用程序受益于这些更改，它必须在 .NET Framework 4.7.2 或更高版本上运行，并且必须通过在应用配置文件的节中将以下<runtime>设置为false来启用此行为，如以下示例所示。

<?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 &#39;key1=true/false;key2=true/false  -->
<AppContextSwitchOverrides value="Switch.System.Windows.DoNotUsePresentationDpiCapabilityTier2OrGreater=false" />
</runtime>
</configuration>

名称	价值
范围	主要
版本	4.8
类型	重定目标

Windows Workflow Foundation （WF）

Windows Workflow Foundation （WF）工作流设计器中的无障碍功能改进

详细信息

Windows Workflow Foundation （WF）工作流设计器正在改进它与辅助功能技术配合使用的方式。这些改进包括以下更改：

选项卡顺序在一些控件中更改为从左到右和从上到下：
设置 InitializeCorrelation 活动相关数据的初始化相关窗口
Receive、Send、SendReply和 ReceiveReply 活动的内容定义窗口
可通过键盘获取更多功能：
编辑活动的属性时，属性组在第一次聚焦时可以通过键盘折叠。
现在可通过键盘访问警告图标。
“属性”窗口中的“更多属性”按钮现在可通过键盘访问。
键盘用户现在可以访问工作流设计器的“参数”和“变量”窗格中的标题项。
提升了聚焦项的可见性，例如当：
向工作流设计器和活动设计器使用的数据网格添加行。
在 ReceiveReply 和 SendReply 活动中按 Tab 键切换字段。
设置变量或参数的默认值
屏幕阅读器现在可以正确识别：
工作流设计器中设置的断点。
FlowSwitch<T>、FlowDecision 和 CorrelationScope 活动。
Receive 活动的内容。
InvokeMethod 活动的目标类型。
TryCatch 活动中的“异常”组合框和“最终”部分。
消息传递活动（Receive、Send、SendReply 和 ReceiveReply）中的“消息类型”组合框、“添加相关初始化表达式”窗口中的拆分器、“内容定义”窗口和“CorrelatesOn 定义”窗口。
状态机转换和转换目标。
FlowDecision 活动上的注释和连接器。
活动的上下文（右键单击）菜单。
属性值编辑器、“清除搜索”按钮、“按类别”和“按字母顺序排序”按钮，以及属性网格中的“表达式编辑器”对话框。
工作流设计器中的缩放百分比。
Parallel 和 Pick 活动中的分隔符。
InvokeDelegate 活动。
字典活动的“选择类型”窗口（Microsoft.Activities.AddToDictionary<TKey,TValue>、Microsoft.Activities.RemoveFromDictionary<TKey,TValue>等）。
“浏览并选择 .NET 类型”窗口。
工作流设计器中的痕迹导航。
选择高对比度主题的用户将看到工作流设计器及其控件的可见性的许多改进，例如元素之间的更好的对比度以及用于焦点元素的更明显的选择框。

建议

如果应用程序具有重新托管的工作流设计器，则应用程序可以通过执行以下任一操作来受益于这些更改：

重新编译应用程序以面向 .NET Framework 4.7.1。这些辅助功能更改在默认情况下启用。
如果应用程序面向 .NET Framework 4.7 或更早版本，但在 .NET Framework 4.7.1 上运行，则可以通过将以下 AppContext switch 添加到 app.config 文件的 <runtime> 部分并将其设为 false（如以下示例所示），选择弃用这些旧版辅助功能行为。

<?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" />
  </runtime>
</configuration>

面向 .NET Framework 4.7.1 或更高版本并希望保留旧版辅助功能行为的应用程序，可通过将此 AppContext 开关显式设置为 true 来选择启用旧版辅助功能。

名称	价值
范围	轻微
版本	4.7.1
类型	重定目标

符号的工作流 XAML 校验和从 SHA1 更改为 SHA256

详细信息

为了支持使用 Visual Studio 进行调试，工作流运行时使用哈希算法为工作流 XAML 文件生成校验和。在 .NET Framework 4.6.2 及更早版本中，工作流校验和哈希使用 MD5 算法，这导致了启用 FIPS 的系统的问题。从 .NET Framework 4.7 开始，默认算法已更改为 SHA1。从 .NET Framework 4.8 开始，默认算法已更改为 SHA256。

建议

如果由于校验和失败，代码无法加载工作流实例或找不到相应符号，请尝试将 AppContext 开关“Switch.System.Activities.UseSHA1HashForDebuggerSymbols”设置为 true。在代码中：

System.AppContext.SetSwitch("Switch.System.Activities.UseSHA1HashForDebuggerSymbols", true);

或在配置中：

<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.Activities.UseSHA1HashForDebuggerSymbols=true" />
  </runtime>
</configuration>

名称	价值
范围	轻微
版本	4.8
类型	重定目标

工作流 XOML 定义和 SqlTrackingService 缓存密钥从 MD5 更改为 SHA256

详细信息

工作流运行时环境保留一个在 XOML 中定义的工作流定义的缓存。 SqlTrackingService 还会保留由字符串键键的缓存。由包含校验和哈希值的值键入这些缓存。在 .NET Framework 4.7.2 及更早版本中，此校验和哈希使用 MD5 算法，这导致了启用 FIPS 的系统出现问题。从 .NET Framework 4.8 开始，使用的算法是 SHA256。不应出现此更改的兼容性问题，因为每次启动工作流运行时和 SqlTrackingService 时都会重新计算这些值。但是，我们提供了可以让客户恢复使用旧版哈希算法的例外做法（如有必要）。

建议

如果此更改在执行工作流时出现问题，请尝试设置一个或两个 AppContext 开关：

将“Switch.System.Workflow.Runtime.UseLegacyHashForWorkflowDefinitionDispenserCacheKey”设为 true。
将“Switch.System.Workflow.Runtime.UseLegacyHashForSqlTrackingCacheKey”设为 true。在代码中：

System.AppContext.SetSwitch("Switch.System.Workflow.Runtime.UseLegacyHashForWorkflowDefinitionDispenserCacheKey", true);
System.AppContext.SetSwitch("Switch.System.Workflow.Runtime.UseLegacyHashForSqlTrackingCacheKey", true);

或在配置文件中（这需要位于正在创建对象的 WorkflowRuntime 应用程序的配置文件中）：

<configuration>
<runtime>
<AppContextSwitchOverrides value="Switch.System.Workflow.Runtime.UseLegacyHashForWorkflowDefinitionDispenserCacheKey=true" />
<AppContextSwitchOverrides value="Switch.System.Workflow.Runtime.UseLegacyHashForSqlTrackingCacheKeytrue" />
</runtime>
</configuration>

名称	价值
范围	轻微
版本	4.8
类型	重定目标

工作流 XOML 文件校验和已从 MD5 更改为 SHA256

详细信息

若要支持在 Visual Studio 中调试基于 XOML 的工作流，当构建包含 XOML 文件的工作流项目时，XOML 文件内容的校验和会包含在生成的代码中，作为 WorkflowMarkupSourceAttribute.MD5Digest 值。在 .NET Framework 4.7.2 及更早版本中，此校验和哈希使用 MD5 算法，这导致了启用 FIPS 的系统出现问题。从 .NET Framework 4.8 开始，使用的算法是 SHA256。若要与 WorkflowMarkupSourceAttribute.MD5Digest 兼容，仅使用生成的校验和的前 16 个字节。这可能会导致调试过程中出现问题。可能需要重新生成项目。

建议

如果重新生成项目没有解决问题，请尝试在代码中将 AppContext 开关 Switch.System.Workflow.ComponentModel.UseLegacyHashForXomlFileChecksum 设置为 true：

System.AppContext.SetSwitch("Switch.System.Workflow.ComponentModel.UseLegacyHashForXomlFileChecksum", true);

或者在配置文件中设置（需要位于正在使用的 MSBuild.exe 的 MSBuild.exe.config 中）：

<configuration>
<runtime>
<AppContextSwitchOverrides value="Switch.System.Workflow.ComponentModel.UseLegacyHashForXomlFileChecksum=true" />
</runtime>
</configuration>

名称	价值
范围	轻微
版本	4.8
类型	重定目标

.NET Framework 4.8.1

.NET Framework 4.8.1 中未引入任何应用兼容性问题。

通过

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

.NET Framework 4.8

核心

托管加密类不会在 FIPS 模式下引发 CryptographyException

详细信息

建议

受影响的 API

Windows 窗体

适用于 .NET 4.8 的 Windows 窗体控件中的辅助功能改进

详细信息

建议

Windows Presentation Foundation （WPF）

WPF 中辅助功能的改进

详细信息

建议

受影响的 API

将 SelectionTextBrush 公共属性添加到 TextBox/PasswordBox 非装饰器选择功能

详细信息

建议

受影响的 API

HwndHost 现可在 DPI 更改期间正确重设子 HWND 的大小

详细信息

建议

Windows Workflow Foundation （WF）

Windows Workflow Foundation （WF） 工作流设计器中的无障碍功能改进

详细信息

建议

符号的工作流 XAML 校验和从 SHA1 更改为 SHA256

详细信息

建议

工作流 XOML 定义和 SqlTrackingService 缓存密钥从 MD5 更改为 SHA256

详细信息

建议

工作流 XOML 文件校验和已从 MD5 更改为 SHA256

详细信息

建议

.NET Framework 4.8.1

反馈

其他资源

Windows Workflow Foundation （WF）工作流设计器中的无障碍功能改进