从 .NET Core 3.0 Preview 8 开始，我一直在研究博客从 .NET Core 2.2 到 .NET Core 3.0的迁移。大多数迁移路径可以遵循微软官方文档。但众所周知，常规ASP.NET 项目绝不会只使用来自微软或 .NET 本身的 API 和包。有很多第三方包可能尚未更新以支持 .NET Core 3.0。某些库仍将在 .NET Core 3.0 上运行，但并不是每个库都可以完全没有任何问题地运行。

典型的 ASP.NET Core 项目的迁移可能卡在这些第三方包上，因此请在迁移之前查看这些包是否有新版本发布。

我不会在这里重复微软文档中已有的迁移步骤。请按照正式文档上的所有内容首先将项目迁移到 .NET Core 3.0。但是到目前为止，以下内容并不在文档中，您可能需要注意。

微软官方迁移文档：https://docs.microsoft.com/en-us/aspnet/core/migration/22-to-30?view=aspnetcore-3.0&tabs=visual-studio

运行时及SDK

.NET Core 3.0 运行时可以和旧版本同时安装在一台机器上。例如，你可以同时具有 1.1, 2.1, 2.2 以及 3.0 的运行时，互相不会干扰。

对于 SDK，从3.0开始，安装新版 SDK 会自动卸载旧版本（仅3.0）的SDK，因此你的程序列表里不会出现一大坨SDK。

可以参阅微软官方博客对 SDK 安装改进的说明：https://devblogs.microsoft.com/dotnet/improving-net-core-installation-in-visual-studio-and-on-windows/

要在 Windows Server 的 IIS 上承载一个 .NET Core 3.0 应用，你依然需要安装 Runtime and Hosting Bundle (ANCM 模块)。

Visual Studio 及工具

有许多朋友在微信群里问过，为啥安装了 .NET Core 3.0 SDK，VS里依旧不显示？这是因为只有最新的16.3版的VS2019才完整支持开发.NET Core 3.0程序。因此请确保你先升级到VS2019 16.3。

至于 Visual Studio Code，无需额外的处理，依旧运行得很香。

C# 8 及工程文件

C# 8 与.NET Core 3.0同时发布，当前的SDK及编译器支持最新语法。因此以前我为了让项目在编译服务器上通过而采用的变通方案可以删了：

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">    <LangVersion>7.3</LangVersion> </PropertyGroup>

被砍的 ASP.NET Core 包

如果你针对 .NET Core 2.x 或者 .NET Standard 2.x 写了个类库，正好用到了像这样的 ASP.NET 包：

<PackageReference Include="Microsoft.AspNetCore.Mvc.Core" Version="2.2.5" />

你是肯定找不到他们的3.0版本的，因为大家太喜欢，所以砍了。

详见官方说明：https://github.com/aspnet/AspNetCore/issues/3756

然而仍然有一些漏网之鱼是有3.0版本的，比如这个：

<PackageReference Include="Microsoft.AspNetCore.Http.Features" Version="3.0.0" />

因此，如果你找不到对应包的3.0版本，现在的解决方式也很简单，直接将他们替换成一个单独的 Microsoft.AspNetCore.App 的FrameworkRefrence，即可干掉一切ASP.NET Core的包，就算算有3.0版本也可以无视。

<FrameworkReference Include="Microsoft.AspNetCore.App" />

Json.NET vs System.Text.Json

我个人是个极端微软主义战士，倡导尽可能迁移到 System.Text.Json。事实上，我博客除了引用库依赖以外的用户代码里，已经没有任何 Json.NET 的痕迹了。但是，目前 System.Text.Json 有一些已知的限制和巨坑，比如我在 GitHub 上提出的这个：https://github.com/dotnet/corefx/issues/41102 。诸如此类的问题容易让你的代码瞬间爆炸，而你死活不知道为啥。

不抛出异常的代码也不一定意味着能像以前一样运行。例如，有一些特殊字符会被转义。这会让你的API用户或者前端程序员爆进ICU。

var obj = new { Id = 1, BlowUp = @"Make \things blow / <up>" };

var jsonNetResult = Newtonsoft.Json.JsonConvert.SerializeObject(obj);

var systemTextJsonResult = System.Text.Json.JsonSerializer.Serialize(obj);

这段代码的结果竟然是：

jsonNetResult

{"Id":1,"BlowUp":"Make \\things blow / <up>"}

systemTextJsonResult

{"Id":1,"BlowUp":"Make \\things blow / \u003Cup\u003E"}

因此请格外小心这些转义，一定要在发布到正式环境之前用足够的数据完整测试你的代码。

此外，不仅仅序列化会爆，反序列化也有行为上的差异，容易让你996进ICU。

class BlowUp

{

public int Id { get; set; }

public string Name { get; set; }

}

static void Main(string[] args)

{

string rawJson = "{\"id\":1,\"name\":\"996ICU\"}";

var obj1 = Newtonsoft.Json.JsonConvert.DeserializeObject<BlowUp>(rawJson);

var obj2 = System.Text.Json.JsonSerializer.Deserialize<BlowUp>(rawJson);

Console.WriteLine(obj1.Name);

Console.WriteLine(obj2.Name);

}

猜猜结果是啥？

只有 obj1.Name 有值。因为 obj2 的所有属性都是默认值或null。

这是因为我们传入的JSON字符串用了小写开头的属性名。Json.NET默认会处理这种情况，但是 System.Text.Json 必须使用这样的参数：

var obj2 = System.Text.Json.JsonSerializer.Deserialize<BlowUp>(rawJson, new JsonSerializerOptions

{

PropertyNameCaseInsensitive = true

});

在真实项目里，ASP.NET Core Web API 或者异教徒的API产品通常返回小写开头的JSON字符串。当我们使用这些API时，System.Text.Json 的默认行为就会让我们爆进ICU。

就像刚才这两个例子一样，新版JSON API有太多意外行为，因此在迁移到 System.Text.Json 前，请确保你有充分的测试数据覆盖所有情况再上线。

Azure 应用程序监控迁移

请参阅我之前的文章：Migrate Azure Application Insights to ASP.NET Core 3.0

https://edi.wang/post/2019/9/2/migrate-azure-application-insights-to-aspnet-core-30

（中文版还没来得及翻译，先凑合看看吧）

Azure DevOps 大爆炸

Azure DevOps 的编译管线里还没有部署 .NET Core 3.0，因此目前你提交一个 .NET Core 3.0 的程序到CI管线里肯定编译不过。解决方案是添加一个安装 .NET Core 3.0 SDK的步骤。

Azure App Service 大爆炸

Azure App Service 也还没有部署 .NET Core 3.0。因此如果你直接将项目用默认编译形式部署在Azure上，会直接产生一个ANCM的启动异常，爆进ICU。解决方案是使用SCD部署。

如果你使用的是 Azure DevOps，修改发布参数，添加 SCD 参数，如：--self-contained -r win-x64

结束语

以上就是我迁移 .NET Core 3.0 时遇到的所有问题及技巧。还有很多其他我没遇到过的场景，欢迎大家留言补充。