.NET 5 中的中断性变更

  • 项目

如果要将应用迁移到 .NET 5，则此处列出的中断性变更可能会影响到你。 变更按技术领域分组，例如 ASP.NET Core 或加密。

本文指出每个中断性变更是二进制兼容还是源兼容：

  • 二进制兼容 - 现有二进制文件无需重新编译即可成功加载和执行，并且运行时行为不会更改。
  • 源兼容 - 面向新运行时或使用新 SDK 或组件时，源代码将成功编译，且不会发生更改。

ASP.NET Core

标题 二进制兼容 源兼容
ASP.NET Core 应用反序列化带引号的数字 ✔ ❌
标记为已过时的 AzureAD.UI 和 AzureADB2C.UI API ✔ ❌
BinaryFormatter 序列化方法已过时 ✔ ❌
终结点路由中的资源为 HttpContext ✔ ❌
Microsoft 预先指定的 Azure 集成包已删除 ❌ ✔
Blazor：Blazor 应用中已更改路由优先逻辑 ✔ ❌
Blazor：更新的浏览器支持 ✔ ✔
Blazor：编译器剪裁掉的无意义空格 ✔ ❌
Blazor：JSObjectReference 和 JSInProcessObjectReference 类型是内部类型 ✔ ❌
Blazor：NuGet 包的目标框架已更改 ❌ ✔
Blazor：ProtectedBrowserStorage 功能已移动到共享框架 ✔ ❌
Blazor：RenderTreeFrame 只读公共字段现在是属性 ❌ ✔
Blazor：更新的静态 Web 资产的验证逻辑 ❌ ✔
浏览器不支持的加密 API ❌ ✔
扩展：包引用更改 ❌ ✔
Kestrel 和 IIS BadHttpRequestException 类型已过时 ✔ ❌
IHttpClientFactory 创建的 HttpClient 实例记录整数状态代码 ✔ ❌
HttpSys：默认情况下禁用客户端证书重新协商 ✔ ❌
IIS：保留 UrlRewrite 中间件查询字符串 ✔ ❌
Kestrel：默认检测的配置更改 ✔ ❌
Kestrel：默认支持的 TLS 协议版本已更改 ✔ ❌
Kestrel：在不兼容的 Windows 版本上通过 TLS 禁用 HTTP/2 ✔ ✔
Kestrel：Libuv 传输标记为已过时 ✔ ❌
ConsoleLoggerOptions 上已过时的属性 ✔ ❌
ResourceManagerWithCultureStringLocalizer 类和 WithCulture 接口成员已删除 ✔ ❌
已删除 Pubternal API ✔ ❌
请求本地化中间件中删除了已过时的构造函数 ✔ ❌
中间件：数据库错误页标记为已过时 ✔ ❌
异常处理程序中间件会引发原始异常 ✔ ✔
ObjectModelValidator 调用验证的新重载 ✔ ❌
Cookie 名称编码已删除 ✔ ❌
IdentityModel NuGet 包版本已更新 ❌ ✔
SignalR：MessagePack 中心协议选项类型已更改 ✔ ❌
SignalR：MessagePack 中心协议已变动 ✔ ❌
UseSignalR 和 UseConnections 方法已删除 ✔ ❌
CSV 内容类型已更改为符合标准 ✔ ❌

代码分析

标题 二进制兼容 源兼容
CA1416 警告 ✔ ❌
CA1417 警告 ✔ ❌
CA1831 警告 ✔ ❌
CA2013 警告 ✔ ❌
CA2014 警告 ✔ ❌
CA2015 警告 ✔ ❌
CA2200 警告 ✔ ❌
CA2247 警告 ✔ ❌

Core .NET 库

标题 二进制兼容 源兼容
适用于单文件发布的与程序集相关的 API 更改 ❌ ✔
BinaryFormatter 序列化方法已过时 ✔ ❌
代码访问安全性 API 已过时 ✔ ❌
CreateCounterSetInstance 会引发 InvalidOperationException ✔ ❌
默认 ActivityIdFormat 为 W3C ❌ ✔
Environment.OSVersion 返回正确的版本 ❌ ✔
FrameworkDescription 的值是 .NET 而不是 .NET Core ✔ ❌
GAC API 已过时 ✔ ❌
硬件内在 IsSupported 检查 ❌ ✔
IntPtr 和 UIntPtr 实现 IFormattable ✔ ❌
LastIndexOf 处理空搜索字符串 ❌ ✔
Unix 上包含非 ASCII 字符的 URI 路径 ❌ ✔
API 已过时并带有非默认诊断 ID ✔ ❌
ConsoleLoggerOptions 上已过时的属性 ✔ ❌
LINQ OrderBy.First 的复杂性 ❌ ✔
已重命名或已删除 OSPlatform 属性 ✔ ❌
Microsoft.DotNet.PlatformAbstractions 包已删除 ❌ ✔
PrincipalPermissionAttribute 已过时 ✔ ❌
来自预览版本的参数名称更改 ✔ ❌
引用程序集中的参数名称更改 ✔ ❌
远程处理 API 已过时 ❌ ✔
Activity.Tags 列表的顺序是相反的 ✔ ❌
SSE 和 SSE2 比较方法处理 NaN ✔ ❌
Thread.Abort 已过时 ✔ ❌
Unix 上 UNC 路径的 URI 识别 ❌ ✔
UTF-7 代码路径已过时 ✔ ❌
Vector2.Lerp 和 Vector4.Lerp 的行为变更 ✔ ❌
向量<T> 引发 NotSupportedException ❌ ✔

密码

标题 二进制兼容 源兼容
浏览器不支持的加密 API ❌ ✔
Cryptography.Oid 仅限 init ✔ ❌
Linux 上的默认 TLS 密码套件 ❌ ✔
对加密抽象的 Create() 重载已过时 ✔ ❌
默认 FeedbackSize 值已更改 ✔ ❌

Entity Framework Core

EF Core 5.0 中的中断性变更

全球化

标题 二进制兼容 源兼容
在 Windows 上使用 ICU 库 ❌ ✔
StringInfo 和 TextElementEnumerator 与 UAX29 兼容 ❌ ✔
Latin-1 字符的 Unicode 类别已更改 ✔ ❌
TextInfo.ListSeparator 值已更改 ✔ ❌

Interop

标题 二进制兼容 源兼容
已删除对 WinRT 的支持 ❌ ✔
将 RCW 强制转换为 InterfaceIsIInspectable 会引发异常 ❌ ✔
不在非 Windows 平台上探测 A/W 后缀 ❌ ✔

网络

标题 二进制兼容 源兼容
Cookie 路径处理符合 RFC 6265 ✔ ❌
调用 SendToAsync 后更新 LocalEndPoint ✔ ❌
MulticastOption.Group 不接受 NULL ✔ ❌
流允许后续开始操作 ❌ ✔
已从 .NET 运行时中删除 WinHttpHandler ❌ ✔

SDK 中 IsInRole 中的声明

标题 二进制兼容 源兼容
默认已导入 Directory.Packages.props 文件 ❌ ✔
可执行项目引用不匹配的可执行文件时生成错误 ✔
FrameworkReference 替换为适用于 Windows SDK 的 WindowsSdkPackageVersion ✔ ❌
未定义 NETCOREAPP3_1 预处理器符号 ✔ ❌
OutputType 已设置为 WinExe ❌ ✔
PublishDepsFilePath 行为变更 ❌ ✔
TargetFramework 从 netcoreapp 更改为 net ❌ ✔
WinForms 和 WPF 应用使用 Microsoft.NET.Sdk ❌ ✔

安全性

标题 二进制兼容 源兼容
代码访问安全性 API 已过时 ✔ ❌
PrincipalPermissionAttribute 已过时 ✔ ❌
UTF-7 代码路径已过时 ✔ ❌

序列化

标题 二进制兼容 源兼容
BinaryFormatter.Deserialize 重新包装异常 ✔ ❌
JsonSerializer.Deserialize 需要单字符的字符串 ✔ ❌
ASP.NET Core 应用反序列化带引号的数字 ✔ ❌
JsonSerializer.Serialize 引发 ArgumentNullException ✔ ❌
非公共的无参数构造函数不用于反序列化 ✔ ❌
序列化键值对时可以采用选项 ✔ ❌

Windows 窗体

标题 二进制兼容 源兼容
本机代码无法访问 Windows 窗体对象 ✔ ❌
OutputType 已设置为 WinExe ❌ ✔
DataGridView 未重置自定义字体 ✔ ❌
方法引发 ArgumentException ✔ ❌
方法引发 ArgumentNullException ✔ ❌
属性引发 ArgumentOutOfRangeException ✔ ❌
TextFormatFlags.ModifyString 已过时 ✔ ❌
DataGridView API 引发 InvalidOperationException ✔ ❌
WinForms 应用使用 Microsoft.NET.Sdk ❌ ✔
已删除的状态栏控件 ✔ ❌

WPF

标题 二进制兼容 源兼容
OutputType 已设置为 WinExe ❌ ✔
WPF 应用使用 Microsoft.NET.Sdk ❌ ✔

另请参阅