如何创建C#自定义NuGet包：安装/还原时添加.cs文件并设编译操作

要实现这个需求，核心是通过MSBuild配置文件修改项目的文件生成操作，而非仅依赖NuGet的content复制功能（后者只能默认设置为Content）。以下是具体步骤和示例：

一、NuGet包结构规划 #

按以下目录结构组织你的包源码：

YourPackageSource/
├── build/
│   └── YourPackageName.props
├── contentFiles/
│   └── cs/
│       └── any/
│           └── file.cs
└── YourPackageName.nuspec

二、编写MSBuild属性文件（.props） #

在build/YourPackageName.props中添加配置，将file.cs添加到项目的Compile项（对应“C# Compiler”生成操作）：

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- 检查文件是否存在，避免项目加载报错 -->
  <ItemGroup>
    <Compile Include="$(MSBuildProjectDirectory)\file.cs" 
             Condition="Exists('$(MSBuildProjectDirectory)\file.cs')" />
  </ItemGroup>
</Project>

• $(MSBuildProjectDirectory)是MSBuild内置变量，指向当前项目的根目录
• Condition确保仅在文件存在时添加配置，防止项目加载失败

三、编写NuSpec配置文件 #

在YourPackageName.nuspec中定义包元数据和文件包含规则：

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
  <metadata>
    <id>YourPackageName</id>
    <version>1.0.0</version>
    <authors>YourName</authors>
    <description>Automatically adds file.cs with C# Compiler build action</description>
    <!-- 配置contentFiles，用于PackageReference模式下的文件复制 -->
    <contentFiles>
      <files include="cs/any/file.cs" buildAction="None" copyToOutput="false" />
    </contentFiles>
  </metadata>
  <!-- 指定要打包的文件路径 -->
  <files>
    <file src="contentFiles/cs/any/file.cs" target="contentFiles/cs/any" />
    <file src="build/YourPackageName.props" target="build" />
  </files>
</package>

• contentFiles中的buildAction="None"是为了避免默认设置为Content，后续由props文件覆盖为Compile
• build目录下的props文件会被NuGet自动导入到目标项目中，修改项目配置

四、打包与验证 #

1. 执行打包命令生成NuGet包：

   nuget pack YourPackageName.nuspec
   

2. 在测试项目中安装该包：
   • 安装后，file.cs会被复制到项目根目录
   • 右键查看文件属性，生成操作会显示为“C# Compiler”（即Compile）
3. 验证还原功能：删除项目中的file.cs，执行dotnet restore，文件会自动恢复且生成操作保持正确

关键原理说明 #

NuGet的content或contentFiles仅负责文件复制，无法直接修改项目的生成操作。而build目录下的.props文件会被NuGet自动导入到目标项目的MSBuild流程中，通过添加Compile项的方式，强制将文件的生成操作设置为“C# Compiler”，无论安装还是还原阶段都会生效。

内容的提问来源于stack exchange，提问作者Leonardo Zambonelli