C# 项目（.NET Framework 4.7.2）配置与生成注意事项

本文档根据本仓库内 WinForms 示例工程（TelegramAuditViewer）的实际排错与调整整理，适用于 传统非 SDK 风格 的 .csproj（Visual Studio 2017 及以上工具链）。默认目标框架：.NET Framework 4.7.2。

1. 目标框架与工程类型

  • 推荐目标：<TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>（与运行环境、引用程序集路径一致）。
  • 输出类型：桌面程序为 WinExe，类库为 Library，控制台为 Exe。
  • 启动对象（可执行项目）：若存在多个 Main，在 csproj 中指定 <StartupObject>命名空间.Program</StartupObject>，避免歧义。

2. NuGet 包与程序集引用（最易出错）

2.1 原则

  • 仅写入 packages.config 或仅“在 VS 里安装了包”并不等于能编译：必须在 **.csproj 中体现对程序集的引用**。
  • 对 .NET Framework 传统项目，推荐在 csproj 中使用 **PackageReference**（见下节），与 msbuild /t:Restore、CI 行为一致，且无需维护 HintPath 指向 packages\ 目录。

2.2 推荐：PackageReference + RestoreProjectStyle

在首个 <PropertyGroup>（或独立 PropertyGroup）中加入：

<RestoreProjectStyle>PackageReference</RestoreProjectStyle>

在 <ItemGroup> 中加入包，例如：

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
</ItemGroup>

首次或清理后需还原包，再生成：

MSBuild YourProject.csproj /t:Restore
MSBuild YourProject.csproj /p:Configuration=Debug

在 Visual Studio 中打开解决方案时，通常会自动还原 NuGet 包。

2.3 若仍使用 packages.config

  • 必须在 csproj 中为每个 NuGet 包添加 <Reference Include="..."><HintPath>...\packages\...</HintPath></Reference>。
  • 团队需在解决方案目录执行 **nuget restore** 或等价还原，保证 packages 目录存在且路径与 HintPath 一致。

3. 勿随意添加 RuntimeIdentifier（VS2017 NuGet 陷阱）

  • 典型现象：使用 packages.config 且 csproj 中写了 <RuntimeIdentifier>win</RuntimeIdentifier> / <RuntimeIdentifiers>...</RuntimeIdentifiers> 时，可能触发 MSBuild 错误：
    Your project file doesn’t list ‘win’ as a “RuntimeIdentifier”…（与 VS2017 自带的 Microsoft.NuGet.targets 解析有关。）
  • 一般桌面 .NET Framework 4.7.2 程序不需要 RID；除非确实在做与 RID 相关的发布流程，否则不要在 csproj 里写 RuntimeIdentifier / RuntimeIdentifiers，以免与旧版 NuGet 目标冲突。

4. App.config 与绑定重定向

  • 若启用 <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>（常见于 net472 项目），生成时可能会自动写入/合并绑定重定向，以减少依赖版本冲突。
  • 若运行时出现“找不到某版本程序集”，检查生成输出目录下的 *.exe.config 与引用版本是否一致。

5. 编译环境建议

  • MSBuild：使用与已安装 Visual Studio 版本匹配的 MSBuild（例如 VS2017 对应 MSBuild\15.0\Bin\MSBuild.exe）。
  • 无 .NET SDK 时：仍可仅依赖 MSBuild + 目标框架引用程序集 编译传统 .NET Framework 项目；dotnet build 不是必需条件。
  • 路径含中文或非 ASCII：一般可正常编译；若 CI 或脚本异常，再排查编码与工作目录。

6. 版本控制与生成产物

  • 将 **bin/、obj/** 加入 .gitignore，避免将输出与 project.assets.json 等中间文件误提交（除非团队明确需要锁定某些生成物）。
  • PackageReference 还原会在 obj\ 下生成 project.assets.json 等文件，属本地/CI 生成内容，通常不提交。

7. 自检清单（新建或接手项目时）

检查项 说明
TargetFrameworkVersion 是否为 v4.7.2（或与团队约定一致）
代码中使用的第三方库 csproj 中是否有 Reference / PackageReference
还原 命令行能否 **/t:Restore** 成功；CI 是否在 Build 前 Restore
RID 非必要不写 **RuntimeIdentifier**
可执行文件 StartupObject、OutputType 是否正确