.NET Core项目从xproj+project.json向csproj迁移简介

Posted 2020-09-05 dax.net

3月7日，微软发布了Visual Studio 2017 RTM，与之一起发布的还有.NET Core Runtime 1.1.0以及.NET Core SDK 1.0.0，尽管这些并不是最新版，但也已经从preview版本升级到了正式版。所以，在安装Visual Studio 2017时如果启用了.NET Core开发的相关功能，那么在安装完成后，你可以在命令行直接执行dotnet.exe，此时你可以看到.NET Core版本是1.1.0，而如果是执行dotnet.exe --version命令，那么你看到的SDK版本将会是1.0.0（并不带preview字样）。

在此介绍如何查看.NET Core SDK版本，主要是源于一件非常有趣的事情，而这件事对于.NET Core项目从老的xproj+project.json迁移到csproj有一定的影响。如果你曾经使用Visual Studio 2015 + .NET Core Tools for Visual Studio + .NET Core SDK开发过项目，并希望在全新的Visual Studio 2017中继续开发的话，了解一下这方面的内容还是很有必要的。

总的来说，迁移一个.NET Core项目，大致有以下几个步骤：

• 迁移准备
• 使用Visual Studio 2017对项目进行单项升级
• 在Jenkins CI服务器上安装最新版的.NET Core SDK
• 修改Jenkins CI系统编译任务，成功完成编译与发布

下面我就以自己的一个开源项目HAL为例，简单介绍一下各个步骤的做法。

迁移准备

HAL项目本来就是托管在Github上的一个开源项目，为了能够平滑地实现项目迁移，并确保Jenkins CI能够正常工作，在进行项目迁移之前，我首先在Github上新建了一个分支（branch）。Github中创建分支的成本是很低的，在一切调试通过之后，将分支合并（merge）到主分支后，直接删掉就行了。

Github中分支创建完成后，更新本地代码库，完成代码同步。

在Visual Studio 2017中打开并升级.NET Core项目

在我之前有篇简文中介绍过，在安装了Visual Studio 2017 RC之后，如何还能继续在Visual Studio 2015中打开并编译xproj项目，因为当安装完Visual Studio 2017后，dotnet.exe已经升级到1.0.0的版本，此时的dotnet.exe已经是使用MSBuild进行项目编译，它并不认识xproj+project.json这样的项目类型和文档组织结构，因此，在Visual Studio 2015中即使能够打开xproj项目文件，也无法正常编译。当时的解决方案是，在项目的根目录级别创建一个global.json文件，在文件中显式指定.NET Core SDK的版本，使得在项目编译时，强制使用老版本的.NET Core SDK，于是问题也就得到了解决。对于如何修改global.json以指定SDK的版本，这里就不多介绍了，请参考这篇文章。

对于这个问题，我们可以做一个实验，假定你的机器上装有Visual Studio 2015 + .NET Core Tools for Visual Studio 2015 + preview版本的.NET Core SDK，同时装有Visual Studio 2017。那么，当你直接在命令行执行dotnet.exe --version命令，你会看到，.NET Core SDK的版本为1.0.0：

如果你进入到一个在global.json中指定了SDK版本的项目的根目录下，同样执行dotnet.exe --version命令，你会发现，此时的SDK版本却是global.json中指定的版本：

OK，如果你之前有修改global.json文件使得xproj项目能够继续在Visual Studio 2015中打开并编译的话，现在就需要去掉global.json文件中对SDK版本的显式声明，否则，在Visual Studio 2017中进行项目迁移的时候，将无法正常完成。因为此时Visual Studio会使用旧版本的SDK，而这个版本的SDK没有migrate功能。

总的来说，在Visual Studio 2017中迁移xproj还是比较平滑稳定的，一般不会遇到稀奇古怪的问题，只需要确认单向迁移就行了。在迁移完成后，会产生新的解决方案文件（sln）。

在Jenkins服务器上安装新的.NET Core SDK

当Visual Studio 2017成功完成项目迁移之后，就可以把代码提交到Github上的临时分支了，这样就能在Jenkins上进行构建测试。在此之前，需要安装新版本的.NET Core SDK。安装过程很简单，到dotnet官方网站上根据Jenkins master或者slave的操作系统选择相应的.NET Core SDK进行下载安装即可。安装完成后，可以使用dotnet --version命令，确认.NET Core SDK已经正确安装。

修改Jenkins系统编译任务

就HAL项目而言，我首先在Jenkins中克隆了编译任务（build job），然后修改这个编译任务，使得它能从Github中的临时分支获取代码。整个过程也没有出现什么难以解决的问题，原有的dotnet restore/build/pack等命令也能够正常继续使用，不过你会发现，编译过程已经使用Microsoft Build Engine（MSBuild）了。

需要注意的是，原来基于xUnit的dotnet test，有一个-xml的隐藏参数，它能够产生JUnit XML格式的单元测试结果报告，但在.NET Core SDK 1.0下，这个参数就不能用了，有个解决办法是使用-l（--logger）参数，它能够产生MSTest格式的单元测试报告，此时，在Jenkins中安装一个MSTest的插件，就能够继续将测试报告显示在主页上。

最后，在Github中，将临时分支合并到主线分支，并在Jenkins中手动修改主线分支对应的build job，最后把克隆的build job删除即可。不建议继续沿用克隆的build job，那样会造成编译版本的混乱。