.NET Core 2.1 中的中断性变更

  • 项目

若要迁移到 2.1 版 .NET Core，本文中列出的中断性变更可能会影响到你的应用。

Core .NET 库

路径 API 对无效字符不引发异常

如果找到无效字符，涉及文件路径的 API 将不再验证路径字符或引发 ArgumentException。

更改说明

在 .NET Framework 和 .NET Core 1.0-2.0 中，如果路径参数包含无效路径字符，受影响的 API 部分中列出的方法便会引发 ArgumentException。 从 .NET Core 2.1 开始，如果找到无效字符，这些方法就不再检查无效路径字符或引发异常。

更改原因

主动验证路径字符会对某些跨平台场景形成阻碍。 引入此更改是为了使 .NET 不尝试复制或预测操作系统 API 调用的结果。 有关详细信息，请参阅博客文章 .Net Core 2.1 中的 System.IO 速览。

引入的版本

.NET Core 2.1

如果代码依赖这些 API 来检查无效字符，则可以添加对 Path.GetInvalidPathChars 的调用。

受影响的 API

另请参阅

添加到内置结构类型的私有字段

私有字段已添加到引用程序集中的特定结构类型。 因此，在 C# 中，必须始终使用 new 运算符或默认文本来实例化结构类型。

更改描述

在 .NET Core 2.0 和早期版本中，某些提供的结构类型（例如 ConsoleKeyInfo）可以在不使用 new 运算符或默认文本的情况下在 C# 中实例化。 这是因为 C# 编译器使用的引用程序集不包含结构的私有字段。 从 .NET Core 2.1 开始，.NET 结构类型的所有私有字段都将添加到引用程序集。

例如，下面的 C# 代码在 .NET Core 2.0 中编译，但不在 .Net core 2.1 中编译：

ConsoleKeyInfo key;    // Struct type

if (key.ToString() == "y")
{
    Console.WriteLine("Yes!");
}

在 .NET Core 2.1 中，之前的代码会导致以下编译器错误：CS0165 - 使用了未赋值的局部变量“key”

引入的版本

2.1

使用 new 运算符或默认文本实例化结构类型。

例如：

ConsoleKeyInfo key = new ConsoleKeyInfo();    // Struct type.

if (key.ToString() == "y")
    Console.WriteLine("Yes!");

ConsoleKeyInfo key = default;    // Struct type.

if (key.ToString() == "y")
    Console.WriteLine("Yes!");

类别

Core .NET 库

受影响的 API

macOS 上的 OpenSSL 版本

对于 AesCcm、AesGcm、DSAOpenSsl、ECDiffieHellmanOpenSsl、ECDsaOpenSsl、RSAOpenSsl 和 SafeEvpPKeyHandle 类型，macOS 上的 .NET Core 3.0 及更高版本的运行时现在首选 OpenSSL 1.1.x 版而非 OpenSSL 1.0.x 版。

.NET Core 2.1 运行时现在支持 OpenSSL 1.1.x 版本，但仍首选 OpenSSL 1.0.x 版。

更改描述

以前，.NET Core 运行时在 macOS 上使用 OpenSSL 1.0.x 版处理与 OpenSSL 交互的类型。 最新的 OpenSSL 1.0.x 版 OpenSSL 1.0.2 现已不受支持。 若要在支持的 OpenSSL 版本上保留使用 OpenSSL 的类型，.NET Core 3.0 及更高版本的运行时现需在 macOS 上使用较新版本的 OpenSSL。

通过此更改，macOS 上的 .NET Core 运行时的行为如下所示：

  • .NET Core 3.0 及更高版本运行时使用 OpenSSL 1.1.x（如果可用），并且仅在没有 1.1.x 版本可用的情况下才回退到 OpenSSL 1.0.x。

    对于将 OpenSSL 互操作类型与自定义 P/Invoke 一起使用的调用方，请按照 SafeEvpPKeyHandle.OpenSslVersion 注释中的指南进行操作。 如果不检查 OpenSslVersion 值，你的应用可能会出现故障。

  • .NET Core 2.1 运行时使用 OpenSSL 1.0.x（如果可用），并且仅在没有 1.0.x 版本可用的情况下才回退到 OpenSSL 1.1.x。

    2\.1 运行时首选早期版本的 OpenSSL，因为 .NET Core 2.1 中不存在 SafeEvpPKeyHandle.OpenSslVersion 属性，因此无法在运行时可靠地确定 OpenSSL 版本。

引入的版本

  • .NET Core 2.1.16
  • .NET Core 3.0.3
  • .NET Core 3.1.2

类别

Core .NET 库

受影响的 API

MSBuild

SDK 现已包含项目工具

.NET Core 2.1 SDK 现包括常见 CLI 工具，你无需再从项目中引用这些工具。

更改描述

在 .NET Core 2.0 中，项目通过 <DotNetCliToolReference> 项目设置引用外部 .NET 工具。 在 .NET Core 2.1 中，其中的某些工具包含在 .NET Core SDK 中，不再需要设置。 如果在项目中包含对这些工具的引用，则会收到如下所示的错误：“Microsoft.EntityFrameworkCore.Tools.DotNet”工具现包含在 .NET Core SDK 中。

.NET Core 2.1 SDK 中现在包含的工具：

<DotNetCliToolReference> 值 工具
Microsoft.DotNet.Watcher.Tools dotnet-watch
Microsoft.Extensions.SecretManager.Tools dotnet-user-secrets
Microsoft.Extensions.Caching.SqlConfig.Tools dotnet-sql-cache
Microsoft.EntityFrameworkCore.Tools.DotNet dotnet-ef

引入的版本

.NET Core SDK 2.1.300

从项目中删除 <DotNetCliToolReference> 设置。

类别

MSBuild

受影响的 API

不可用

请参阅