(因为自己想把 .NET Framework的应用迁移到.NET5，于是有了这个译文)

这篇文章描述了把win Forms桌面应用从.Net Framework迁移到.NET 5平台的方法。.NET5 SDK 已包含对winForm 程序的支持，不过.NET5 平台下的winForms 程序仍然只支持 windows 系统的框架，也只能运行在Windows系统。

从.NET Framework 迁移到 .NET 5，需要创建一个新的项目文件， .NET 5使用SDK风格的项目文件，而典型的.NET Framework框架则使用老的Visual Studio的项目文件(如.vbproj，.csproj)。如果你曾经用文本编辑器打开过一个Visual Studio的项目文件，你就知道它的语法是怎样的。SDK风格的项目文件体积更小，也不需要老的VS项目文件那么多的入口。

要更多了解NET5，参阅 。

迁移前提条件Visual Studio 2019 V16.8 或更高版本

o 选择 桌面应用程序类型

o 选择 .NET5 框架组件

· 在Visual Studio 中预览Winforms 截面设计器

选择设计器，转到菜单 Tools > Options > Environment > Preview Features 选择Use the preview Windows Forms designer for .NET Core apps 选项。

这篇文章以 “配对游戏”（Matching game）示例程序来讲解。（）如果你想跟着示例学习，可以下载这个程序并在VS中打开。或者你也可以用你自己开发的项目。需考虑的事项

.NET Framework迁移到.NET5 时，有以下一些事项需要注意

1. 首先需要检查你的程序是否适合迁移

使用.NET可移植性分析器.NET Portability Analyzer 来确定你的项目是否可迁移到.NET5. 如果你的项目与.NET5存在兼容问题，.NET可移植性分析器会帮你定位问题。.NET可移植性分析器是以Visual Studio扩展的形式安装使用，或者或者以命令行的形式使用。这里有分析器的详细介绍（）。

2. 你将使用一种不同版本的windows Forms

.NET Core 3.0发布时，Windows Forms在Github上开源。这个开源的.NET5上的WinForms 代码是.NET Framework 框架的Forms代码库的一个分支。这个分支可能存在一些不同，可能导致你的程序难以迁移。

3. Windows兼容包可能帮助你进行迁移操作

有一些在.NET Framework 上存在的API，在.NET5上并不存在。而windows 兼容包(Windows Compatibility Pack，)则添加了很多这种API，从而可能帮助你的WinForms程序与.NET5兼容。

4. 升级你项目中使用的NuGet包

一个较好的习惯做法是，在做任何迁移之前，先把所有使用的NuGet包升级到最新版本。如果你的程序引用了任何NuGet包，升级他们。但是也有确保你的程序能够正常创建：升级之后，如果存在任何包的错误，则需要把相应的包回退到那个能够让你的程序正常创建的最高版本。

备份你的项目

第一步先备份你的项目，在你动手迁移之前！如果发生什么错误，你还能恢复到最初的代码。不要过分依赖于.NET Portability Analyzer来备份你的项目。自己做个安全的备份是更好的。

NuGet 包配置

如果你的程序引用了NuGet包，你可能会在你的项目文件夹中看到一个单独的packages.config包配置文件。在SDK风格的项目中，NuGet包引用是在项目文件里配置的。对于Visual Studio的项目文件，也可以在项目文件中配置NuGet包，但不是默认的，而是可选做法。但.NET5 不使用单独的包配置文件，必须在迁移之前将NuGet包引用迁移到项目文件内。

按以下步骤迁移包配置文件：

1、 解决方案浏览窗口，找到你要迁移的项目

2、 找到packages.config文件并右键，选择 “将Package Config 迁移到PackageReference”

3、 在出来的窗口中，选择所有顶层依赖的NuGet包。

重生成你的项目，以确定NuGet包迁移是否存在问题。

项目文件

下一步，就是将前述的项目文件(例如.csproj/.vbproj)转换为.NET5的SDK风格的项目文件。不过，也有可能你已经在使用SDK风格的项目文件了。你可以很容易地在Visual Studio中确定你使用哪种项目文件。在VS的解决方案浏览窗口中，找到项目文件，右键单击，寻找“编辑项目文件”选项，如果没有这个选项，那么使用的是老的VS项目文件，从而需要升级。

按以下步骤升级项目文件：

1、 在解决方案浏览窗口，找到你要迁移的项目

2、 选中项目，右键“卸载项目”

3、 右键项目，选择“编辑项目文件”，或者直接在文件夹中用记事本打开项目文件

4、 把项目文件的XML文件内容复制到一个文本编辑器并备份；

5、 清空项目文件内容，复制以下内容到已被清空的项目文件

<Project Sdk="Microsoft.NET.Sdk">  <PropertyGroup>    <OutputType>WinExe</OutputType>    <TargetFramework>net5.0-windows</TargetFramework>    <UseWindowsForms>true</UseWindowsForms>    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>  </PropertyGroup></Project>

重要事项

对于DLL函数库项目，需要删除< OutputType > 项

以上XML内容定义了项目的基本结构。但是，它还不包含旧项目文件的任何设置信息。使用上一步备份的旧项目文件内容，按以下步骤操作：

1、从旧的项目文件复制以下元素到新项目文件的 < PropertyGroup >元素中

o <RootNamespace>

o <AssemblyName>

这时，你的项目文件看起来和下面的内容类似：

<Project Sdk="Microsoft.NET.Sdk">  <PropertyGroup>    <OutputType>WinExe</OutputType> ///(对于DLL库文件，删除此行)    <TargetFramework>net5.0-windows</TargetFramework>    <UseWindowsForms>true</UseWindowsForms>    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>    <RootNamespace>MatchingGame</RootNamespace>    <AssemblyName>MatchingGame</AssemblyName>  </PropertyGroup></Project>

把旧项目文件中包含 <ProjectReference>和 <PackageReference>元素的<ItemGroup>节点 复制到 新项目文件的 </PropertyGroup> 标签之后。

你的新项目文件应该看起来像这样：

<Project Sdk="Microsoft.NET.Sdk">  <PropertyGroup>    (contains settings previously described)  </PropertyGroup>  <ItemGroup>    <ProjectReference Include="..\MatchingGame.Logic\MatchingGame.Logic.csproj">      <Project>{36b3e6e2-a9ae-4924-89ae-7f0120ce08bd}</Project>      <Name>MatchingGame.Logic</Name>    </ProjectReference>  </ItemGroup>  <ItemGroup>    <PackageReference Include="MetroFramework">      <Version>1.2.0.3</Version>    </PackageReference>  </ItemGroup></Project>

对于<ProjectReference>元素，并不需要<Project>和<Name>子元素。所以你可以删除如下的内容

<ItemGroup>  <ProjectReference Include="..\MatchingGame.Logic\MatchingGame.Logic.csproj" /></ItemGroup>

.NET FrameWork框架的Windows Forms项目通常还包含类似于Properties/Settings.settings，Properties/Resources.resx等文件。这些文件，以及任何除了窗体资源文件外的resx资源文件，都需要迁移。

从旧的项目文件中复制对应的节点到新项目文件的 <ItemGroup> 元素内，然后修改任何：

任何 类似于 <Compile Include="value">或者<EmbeddedResource Include="value">节点内的 “Include” 为 “Update”.

导入Settings.settings 文件。 注意，在<Compile>节点内，Include 修改为 “Update”

<ItemGroup>  <None Include="Properties\Settings.settings">    <Generator>SettingsSingleFileGenerator</Generator>    <LastGenOutput>Settings.Designer.cs</LastGenOutput>  </None>  <Compile Update="Properties\Settings.Designer.cs">    <AutoGen>True</AutoGen>    <DependentUpon>Settings.settings</DependentUpon>    <DesignTimeSharedInput>True</DesignTimeSharedInput>  </Compile></ItemGroup>

导入任何resx file的配置信息，例如properties/Resources.resx 文件。注意<Compile> 和<EmbeddedResource> 元素内的“Include”修改为“Update”， 同时<SubType>元素要从<EmbeddedResource>中删除。

<ItemGroup>  <EmbeddedResource Update="Properties\Resources.resx">    <Generator>ResXFileCodeGenerator</Generator>    <LastGenOutput>Resources.Designer.cs</LastGenOutput>  </EmbeddedResource>  <Compile Update="Properties\Resources.Designer.cs">    <AutoGen>True</AutoGen>    <DependentUpon>Resources.resx</DependentUpon>    <DesignTime>True</DesignTime>  </Compile></ItemGroup>

转换解决方案下的每一个文件，如果你在使用前面提到的示例程序，MatchingGame.Logic项目将会被转换。

编辑App.config文件

如果你的程序有一个App.config file，需要删除其中的<supportedRuntime>节点。即类似如下节点：

<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />

对于App.config文件，有点内容你需要注意下。.NET Framework框架下的App.config文件不仅仅配置你的程序，同时也配置了运行时设置和行为，比如日志。但是在.NET5和.NET Core项目，App.config文件不再用于运行时配置。如果你的文件含有相应的节段，将不会起作用。

添加兼容包

如果编译失败，收到如下类似的错误信息：

· 无法找到 某某类型或命名空间<xxx>

· 在当前上下文中，<xxx>名称不存在

你可能需要添加 兼容包到你的程序中(Microsoft.Windows.Compatibility)。这个兼容包添加了约21000个.NET Framework 的API。比如System.Configuration.ConfigurationManager类和注册表交互的API。

按如下方法添加 兼容包：

<ItemGroup>  <PackageReference Include="Microsoft.Windows.Compatibility" Version="5.0.0-rc.2.20475.5" /></ItemGroup>

完成迁移后，你就可以测试你的程序了！