C#新版本风格项目文件（SDK风格项目 SDK-style project）

Posted 2021-10-02 dotNET跨平台

在VisualStudio中创建NetCore以上版本的项目，使用的都是新版本风格的项目文件。
和旧版本.NetFramework版本的项目文件区别：

1. 双击项目可直接打开csproj文件进行编辑配置

2. 项目文件内容的改变

3. 项目属性文件夹图标更改

4. 项目引用去除，改成依赖项

5. Nuget包引用区别

6. 新版C#语法支持

7. 多目标框架版本支持

8. ...

其中最大的区别可以说是引用的改变，
在旧版本的项目文件中，项目所有的引用（dll/nuget/com/项目）全部糅杂在一起（后续有个版本会用图标区别nuget，但是有bug），对人来说很不友好。
并且nuget包的引用全部保存在项目的packages.config文件中，但是包还原时却是还原在解决方案文件(sln)同目录的packages目录下，导致大型项目有多个解决方案同时引用一个项目时导致包路径错误的问题。

对比如图，很明显，新版本的项目文件依赖项更加简洁明了。

并且除了依赖项，如果你用记事本打开过.csproj文件，你会发现.NetFramework版本的项目文件内容非常多，他把整个项目的文件引用都记录在其中，并且还有大量MSBuild相关的编译配置等。

但是在新版风格（NetCore）的项目文件中，大大减少，文件默认使用文件系统引用，不再显示记录在csproj文件中，这样可以解决以前增删了代码文件而没提交项目文件导致的编译错误，并且使得项目文件可以很容易的手动修改各种配置。

各种优点都说完了，但是很多人会疑问，这是NetCore风格的项目文件，并不是所有.NetFramework的项目都可以升级为Core，无须担心，即使是.NetFramework也可以使用新版的项目文件，只需要安装了NetCore或者更高版本的SDK就行，最后编译出来的程序集并不需要依赖NetCore的Runtime。
并且新版本的项目文件支持多目标框架版本，一个项目即可编译出多个目标框架版本的程序集，

如何迁移

如果是简单的项目，没有各种骚操作，直接新建一个NetCore的项目，把csproj文件替换即可

<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net40</TargetFramework>
    <ApplicationIcon />
    <StartupObject />
    <!-- <UseWPF>true</UseWPF> -->
    <!-- <UseWindowsForms>true</UseWindowsForms> -->
  </PropertyGroup>
</Project>

还可使用try-convert工具升级

下面是一些升级遇到过的问题

1. AssemblyInfo.cs文件冲突

注意默认的AssemblyInfo文件需要删除，因为新的项目文件会隐式生成程序集信息，如果需要显示指定，需要配置GenerateAssemblyInfo为false，并且需要使用版本通配符的话还需要配置Deterministic为false。

2. Nuget引用方式

nuget引用需要从package.config迁移到项目文件的PackageReference节点。

2. 生成路径带有版本框架的文件夹

.NetFramework的项目默认生成路径为bin/Debug，但是Core之后会再加一层框架版本文件夹，这是因为新版本的项目文件支持多目标框架版本，如果不需要这层文件夹只要修改AppendTargetFrameworkToOutputPath配置为false即可。

3. 使用多版本目标框架

NetCore风格的项目文件支持多目标框架版本，就是一个项目可以生成多个目标框架版本的程序集，而不需要创建多个项目，该功能只需要把原本的TargetFramework节点修改成TargetFrameworks就行，使用分号分隔框架版本，例如<TargetFrameworks>net40;netcoreapp2.1;netcoreapp3.1;net5.0;net5.0-windows</TargetFrameworks>。

4. 项目构建时自动生成nuget包

NetCore风格的项目文件只需配置好包信息，可以在每次构建时自动生成Nuget包，并且会根据项目依赖自动生成包依赖，无须手动编写nuspec文件，更多配置可参考官方文档。也可参照我的实例

    <!--自动生成Nuget包-->
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <!--生成项目Xml文档（包）-->
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <!--调试符号文件嵌入到dll中，以便附加调试nuget包程序（项目生成nuget包默认不含pdb文件，想要调试需要用符号包或者下面方式）-->
    <!-- https://docs.microsoft.com/zh-cn/dotnet/core/deploying/single-file#include-pdb-files-inside-the-bundle -->
    <!-- https://docs.microsoft.com/zh-cn/nuget/create-packages/symbol-packages-snupkg -->
    <DebugType>embedded</DebugType>

    <!--包信息-->
    <PackageIcon>Logo.png</PackageIcon>
    <Authors>XXXX</Authors>
    <Company>XXXX</Company>
    <Description>XXXX</Description>

    <!--包版本-->
    <Version Condition="'$(Configuration)' == 'Debug'">0.1.5-$(Time)</Version>
    <Version Condition="'$(Configuration)' == 'Release'">0.1.5</Version>

5. 无法用命令dotnet build编译带资源文件的项目

如果是Winform或在WPF项目，大概率会有资源文件，如果使用vs功能菜单生成则没有此问题，但是使用dotent cli进行编译则会出现以下错误，但是这是NetCore项目才会出现的问题和处理方式，目前暂时不知道有什么解决方法，由于没有CI/CD的需求，也就没有过多深究了。

C:\\Program Files\\dotnet\\sdk\\5.0.400\\Microsoft.Common.CurrentVersion.targets(3162,5): error MSB3823: 非字符串资源要求将属性 GenerateResourceUsePreserializedResources 设置为 true。 [E:\\xxxx.csproj]
C:\\Program Files\\dotnet\\sdk\\5.0.400\\Microsoft.Common.CurrentVersion.targets(3162,5): error MSB3822: 非字符串资源要求在运行时使用 System.Resources.Extensions 程序集，但未在此项目的引用中找到它。 [E:\\xxxx.csproj]

6. 低版本框架使用高版本C#语法

.NetFramework的项目最高只能支持C#7.3（貌似？不太记得了），许多C#8/C#9以及即将发布的C#10的新特性无法使用，升级后如果不指定会默认支持框架版本兼容的C#版本，但是可以手动配置项目项目的LangVersion指定使用相应版本的C#。除了一些需要框架支持的新特性，大部分语法特性都可以支持。例如单行using，switch表达式，顶级语句，init关键字，匹配模式，解构表达式，ref加强等等。

暂时只想起这些，后续会持续更新
。。。。。。。。。。。。。。。。。

参考文档

Microsoft官方文档

修改.csproj文件_从.NET Core将现有.NET项目文件升级为精益的新CSPROJ格式

.net core 选择文件_.net core迁移实践：项目文件csproj的转换

从以前的项目格式迁移到 VS2017 新项目格式