thecybercore-msbuild

.NET / ASP.NET 最常用的 80 条 MSBuild 命令模板，覆盖 restore、build、test、publish、pack 与 CI 诊断的完整 CLI 工作流。

## 概述（中文）

.NET / ASP.NET 最常用的 80 条 MSBuild 命令模板，覆盖 restore、build、test、publish、pack 与 CI 诊断的完整 CLI 工作流。

## 技能正文

# 技能：.NET / ASP.NET 最常用的 80 条 MSBuild 命令（CLI）

## 用途
本技能提供一套实用的、**按优先级排序**的 **80 条最有用命令模板**，用于在命令行通过 **MSBuild**（`dotnet msbuild` 或 `msbuild`）处理 .NET / ASP.NET 项目。流程贴近日常：restore → build → test → publish/pack → diagnose → CI 加固。

## 典型 ASP.NET 开发者工作流（命令优先级依据）
典型 ASP.NET CLI 工作流：
1. **Restore** 依赖（CI 中常用锁定模式）
2. **Build** 快速（Debug）且可靠（Release）
3. **Test** 反复运行（过滤器、日志、结果目录、CI 中 no-build/no-restore）
4. **Publish** 产物（RID、自包含、单文件、裁剪、ready-to-run）
5. **Package** 库（Pack）、版本管理
6. **Diagnose** 构建问题（binlog、verbosity、preprocess、graph build）
7. **CI 加固**（确定性、CI 标志、node reuse、并行、可复现性）

排序反映该流程中的频率与影响。

## 约定
- 优先跨平台：`dotnet msbuild`
- Windows 上若已安装 VS Build Tools 可改用：`msbuild`
- 目标：`/t:<Target>`
- 属性：`/p:Name=Value`
- 日志：`/v:<level>`、`/bl[:file]`、`/fl`、`/pp`
- 多进程：`/m[:n]`
- 说明：`dotnet test` 因是实用测试 CLI（底层调用 MSBuild）而包含在内。

---

## 前 80 条命令（1 = 最重要）

> 按需替换 `MySolution.sln` / `src/MyWeb/MyWeb.csproj` / `tests/...`。

### A) Restore / Build / Clean / Rebuild（日常）
1) 还原解决方案
```bash
dotnet msbuild MySolution.sln /t:Restore
```

2) 构建解决方案（Debug）

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Debug
```

3) 构建解决方案（Release）

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Release
```

4) 清理解决方案

```bash
dotnet msbuild MySolution.sln /t:Clean /p:Configuration=Debug
```

5) 重新构建解决方案（Clean + Build）

```bash
dotnet msbuild MySolution.sln /t:Rebuild /p:Configuration=Release
```

6) 一次调用 Restore + Build

```bash
dotnet msbuild MySolution.sln /restore /t:Build /p:Configuration=Debug
```

7) 不还原直接构建（CI 友好）

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Release /p:Restore=false
```

8) 并行构建（最大 CPU）

```bash
dotnet msbuild MySolution.sln /t:Build /m /p:Configuration=Release
```

9) 较安静的 CI 输出

```bash
dotnet msbuild MySolution.sln /t:Build /nologo /v:minimal /p:Configuration=Release
```

10) 构建单个项目

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Build /p:Configuration=Debug
```

11) 显式设置 Platform

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Release /p:Platform="Any CPU"
```

12) 将警告视为错误

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Release /p:TreatWarningsAsErrors=true
```

13) 确定性构建

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Release /p:Deterministic=true
```

14) CI 构建模式（SourceLink/版本行为）

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Release /p:ContinuousIntegrationBuild=true
```

15) 禁用增量 up-to-date 检查（强制构建行为）

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Release /p:DisableFastUpToDateCheck=true
```

16) 带预定义常量构建

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Build /p:Configuration=Debug /p:DefineConstants="TRACE;DEBUG;MYFLAG"
```

17) 设置 OutputPath（临时产物）

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Build /p:Configuration=Release /p:OutputPath=artifacts/bin/
```

18) 设置 BaseIntermediateOutputPath（obj 隔离 / CI 缓存）

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Build /p:Configuration=Release /p:BaseIntermediateOutputPath=artifacts/obj/
```

19) 禁用共享编译（调试异常构建行为）

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Debug /p:UseSharedCompilation=false
```

20) 显示 MSBuild 版本

```bash
dotnet msbuild -version
```

### B) 测试（实用 CLI；基于 MSBuild）

21) 运行测试（解决方案）

```bash
dotnet test MySolution.sln -c Release
```

22) 不构建直接测试

```bash
dotnet test MySolution.sln -c Release --no-build
```

23) 不还原直接测试

```bash
dotnet test MySolution.sln -c Release --no-restore
```

24) 测试单个测试项目

```bash
dotnet test tests/MyWeb.Tests/MyWeb.Tests.csproj -c Debug
```

25) 按完全限定名过滤测试

```bash
dotnet test MySolution.sln -c Release --filter "FullyQualifiedName~MyNamespace"
```

26) 按 trait/类别过滤测试（示例）

```bash
dotnet test MySolution.sln -c Release --filter "TestCategory=Integration"
```

27) TRX 日志记录器

```bash
dotnet test MySolution.sln -c Release --logger "trx"
```

28) 结果目录

```bash
dotnet test MySolution.sln -c Release --results-directory artifacts/testresults
```

29) 收集覆盖率（跨平台收集器）

```bash
dotnet test MySolution.sln -c Release --collect "XPlat Code Coverage"
```

30) 提高测试详细级别

```bash
dotnet test MySolution.sln -c Release -v normal
```

31) Blame/挂起诊断

```bash
dotnet test MySolution.sln -c Release --blame
```

32) 按名称运行特定测试

```bash
dotnet test MySolution.sln -c Release --filter "Name=MySpecificTest"
```

### C) 发布（ASP.NET 核心场景）

33) 发布（Release，框架依赖）

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release
```

34) 发布到指定目录

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:PublishDir=artifacts/publish/
```

35) 带 RuntimeIdentifier (RID) 发布

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:RuntimeIdentifier=linux-x64
```

36) 自包含发布

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:RuntimeIdentifier=linux-x64 /p:SelfContained=true
```

37) 框架依赖（显式）

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:SelfContained=false
```

38) 单文件发布

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:RuntimeIdentifier=win-x64 /p:PublishSingleFile=true
```

39) ReadyToRun 发布

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:PublishReadyToRun=true
```

40) 裁剪发布（谨慎使用）

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:PublishTrimmed=true
```

41) 单文件 + 裁剪（高级）

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:RuntimeIdentifier=linux-x64 /p:PublishSingleFile=true /p:PublishTrimmed=true
```

42) 标记环境属性（模式；应用须使用）

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:EnvironmentName=Production
```

43) 带版本标记发布

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:Version=1.2.3
```

44) 显式 TargetFramework 发布（多 TFM 项目）

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:TargetFramework=net8.0
```

45) 带 CI 属性发布

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:ContinuousIntegrationBuild=true /p:Deterministic=true
```

46) 发布：RID + 自包含 + 输出

```bash
dotnet msbuild src/MyWeb/MyWeb.csproj /t:Publish /p:Configuration=Release /p:RuntimeIdentifier=linux-x64 /p:SelfContained=true /p:PublishDir=artifacts/publish/linux-x64/
```

### D) Pack / NuGet / 版本管理

47) 打包库

```bash
dotnet msbuild src/MyLib/MyLib.csproj /t:Pack /p:Configuration=Release
```

48) 打包到自定义输出路径

```bash
dotnet msbuild src/MyLib/MyLib.csproj /t:Pack /p:Configuration=Release /p:PackageOutputPath=artifacts/nuget/
```

49) 带版本打包

```bash
dotnet msbuild src/MyLib/MyLib.csproj /t:Pack /p:Configuration=Release /p:Version=1.2.3
```

50) 设置 AssemblyVersion / FileVersion

```bash
dotnet msbuild src/MyLib/MyLib.csproj /t:Build /p:Configuration=Release /p:AssemblyVersion=1.2.0.0 /p:FileVersion=1.2.3.0
```

51) InformationalVersion（提交元数据）

```bash
dotnet msbuild src/MyLib/MyLib.csproj /t:Build /p:Configuration=Release /p:InformationalVersion=1.2.3+sha.abcdef
```

52) 还原并生成 packages.lock.json

```bash
dotnet msbuild MySolution.sln /t:Restore /p:RestorePackagesWithLockFile=true
```

53) 锁定模式还原（锁文件变更则失败）

```bash
dotnet msbuild MySolution.sln /t:Restore /p:RestoreLockedMode=true
```

54) 使用自定义 NuGet.config 还原

```bash
dotnet msbuild MySolution.sln /t:Restore /p:RestoreConfigFile=NuGet.config
```

55) 自定义 packages 文件夹还原（CI 缓存）

```bash
dotnet msbuild MySolution.sln /t:Restore /p:RestorePackagesPath=artifacts/nuget-packages
```

### E) 诊断 / 故障排除

56) 二进制日志 (binlog) — 首选步骤

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Release /bl
```

57) 指定路径的 binlog

```bash
dotnet msbuild MySolution.sln /t:Build /p:Configuration=Release /bl:artifacts/logs/build.binlog
```

58) 详细级别：detailed

```bash
dotnet msbuild MySolution.sln /t:Build /v:detailed
```

59) 详细级别：diagnostic（仅在需要