---
title: CSharp-07-dotnet项目与工具链
aliases:
  - .NET 项目与工具链
  - dotnet CLI
  - .NET 构建与发布
tags:
  - 编程语言/CSharp
  - 类型/教程
created: 2026-10-11
updated: 2026-10-11
level: 进阶
prerequisites:
  - "[[CSharp-01-环境与基础语法]]"
  - "[[CSharp-02-面向对象]]"
sources:
  - https://learn.microsoft.com/zh-cn/dotnet/core/project-sdk/overview
  - https://learn.microsoft.com/zh-cn/dotnet/core/tools/dotnet-new-sdk-templates
  - https://learn.microsoft.com/zh-cn/nuget/concepts/package-versioning
  - https://learn.microsoft.com/zh-cn/nuget/consume-packages/central-package-management
  - https://learn.microsoft.com/zh-cn/dotnet/core/deploying/
  - https://learn.microsoft.com/zh-cn/visualstudio/msbuild/customize-by-directory
---

# CSharp-07-dotnet项目与工具链

> [!abstract] 这篇笔记讲什么
> 语法只是 C# 的一半。另一半是**工程**：项目文件怎么组织、包从哪里来、构建用什么配置、产物怎么发布。
> 这篇笔记把 `.csproj` / `.slnx`、`dotnet` CLI、NuGet 依赖管理、多目标框架、条件编译、
> 版本号、六种发布模式和 CI 集成串成一条完整的工具链。
> 读者本机为 **.NET SDK 10.0.401**（LTS，支持到 2028-11），文中所有命令都在该环境验证过。

## 是什么

**.NET 工具链**是围绕一个命令行程序 `dotnet` 建立的一整套构建与依赖管理体系。它的核心构件有四层：

| 层次 | 载体 | 作用 |
|---|---|---|
| 解决方案层 | `.slnx` / `.sln` | 把多个项目组织成一个可整体构建的单元 |
| 项目层 | `.csproj`（MSBuild XML） | 声明目标框架、依赖、编译选项、元数据 |
| 工具层 | `dotnet` CLI 子命令 | 创建、还原、构建、测试、打包、发布 |
| 依赖层 | NuGet + `nuget.config` | 从公共或私有源解析第三方包 |

一个关键认知：**`.csproj` 不是"配置文件"，而是 MSBuild 脚本**。它被导入 SDK 提供的 `Sdk.props` 和 `Sdk.targets`，最终展开成一份巨大的构建描述。所以 `.csproj` 里可以写条件、可以写循环、可以定义自定义 Target——这既是它的灵活性来源，也是它让人困惑的原因。

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <!-- Sdk 属性等价于在文件顶部隐式导入 Sdk.props、底部导入 Sdk.targets -->
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
</Project>
```

上面这 7 行就是一个可运行的控制台项目。对比旧式 .NET Framework 项目要逐个列出每个 `.cs` 文件，现代 SDK 样式项目用 **glob 通配符**自动包含源码：

| 项类型 | 包含 glob | 排除 glob |
|---|---|---|
| `Compile` | `**/*.cs` | `**/*.user`、`**/*.*proj`、`**/*.sln(x)` |
| `EmbeddedResource` | `**/*.resx` | 同上 |
| `None` | `**/*` | 同上，再移除 `**/*.cs`、`**/*.resx` |

> [!important] 为什么这很重要
> 因为源码是自动包含的，**手工再写一遍 `<Compile Include="Foo.cs" />` 会触发 NETSDK1022 重复包含错误**。
> 要定制就用 `Remove` 或 `Update`，或者先把 `EnableDefaultCompileItems` 设为 `false`。

## 为什么需要它

三个具体的痛点决定了这套工具链的形状。

**痛点一：依赖地狱。** 老式 C# 项目把 DLL 直接提交进版本库，或者依赖 GAC（全局程序集缓存）。同一个解决方案里 A 项目要 `Newtonsoft.Json` 12.0、B 项目要 13.0，就会在运行时抛 `FileLoadException`。NuGet 用**传递性依赖 + 统一版本解析**解决了这个问题：你只声明直接依赖，冲突由解析器算出一棵唯一的依赖图并写进 `project.assets.json`。

**痛点二：环境不一致。** "在我机器上能跑"的经典原因之一是 SDK 版本不同。`global.json` 让仓库锁定 SDK 版本，`Directory.Build.props` 让整个仓库共享编译选项，两者一起把"环境"变成可提交的代码。

**痛点三：发布形态单一。** .NET Framework 时代只有"目标机器装运行时"一种选择。现在从"框架依赖的几 MB DLL"到"几百 MB 完全自包含"再到"NativeAOT 编译成单个原生 exe"，可以在体积、启动速度、兼容性之间按场景选点。

## 核心内容

### 解决方案与项目的关系

**项目（project）是构建的基本单位，解决方案（solution）只是项目的容器。** 构建 `.slnx` 时 MSBuild 会逐个构建它引用的项目；项目之间是否真的产生依赖，取决于 `.csproj` 里的 `<ProjectReference>`，而不是解决方案。

```
MyApp/                        ← 仓库根目录
├── MyApp.slnx                ← 解决方案：只记录"有哪些项目"
├── Directory.Build.props     ← 全仓库共享的 MSBuild 属性
├── Directory.Packages.props  ← 全仓库共享的包版本
├── global.json               ← 锁定 SDK 版本
├── src/
│   ├── MyApp.Core/MyApp.Core.csproj      ← 类库，被下面两个引用
│   └── MyApp.Cli/MyApp.Cli.csproj        ← 控制台，引用 Core
└── tests/
    └── MyApp.Tests/MyApp.Tests.csproj    ← 测试，引用 Core
```

| 格式 | 扩展名 | 本质 | 支持起点 | 说明 |
|---|---|---|---|---|
| 经典格式 | `.sln` | 自定义文本格式，含 GUID、配置节 | 很早 | 人几乎不可读，合并冲突频繁 |
| 新格式 | `.slnx` | **纯 XML** | .NET SDK 9.0.200 | .NET 10 起 `dotnet new sln` 的默认输出 |

`.slnx` 的内容极其简单：

```xml
<Solution>
  <Folder Name="/src/">
    <Project Path="src/MyApp.Core/MyApp.Core.csproj" />
    <Project Path="src/MyApp.Cli/MyApp.Cli.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/MyApp.Tests/MyApp.Tests.csproj" />
  </Folder>
</Solution>
```

> [!important] .NET 10 的破坏性变更
> 在 .NET 10 中，`dotnet new sln` 默认生成 `slnx` 格式，而不再生成 `sln`。
> 如果你的 CI 脚本或老工具链（某些版本的第三方分析工具）只认 `.sln`，请显式执行：
> `dotnet new sln --format sln`
> 需要 .NET 9.0.200 或更高版本的 SDK 才支持 `--format` 选项。

### 常用项目模板

`dotnet new list` 会列出本机所有已安装模板。SDK 预装的常用短名称如下：

| 模板短名称 | 中文名 | 默认语言 | 生成的 SDK | 典型用途 |
|---|---|---|---|---|
| `console` | 控制台应用程序 | C#/F#/VB | `Microsoft.NET.Sdk` | 脚本、命令行工具、学习 |
| `classlib` | 类库 | C#/F#/VB | `Microsoft.NET.Sdk` | 可复用的业务逻辑、供 NuGet 发布 |
| `webapi` | ASP.NET Core Web API | C#/F# | `Microsoft.NET.Sdk.Web` | REST 服务（默认最小 API） |
| `webapiaot` | ASP.NET Core API（AOT） | C# | `Microsoft.NET.Sdk.Web` | 需要原生编译的极速启动服务 |
| `mvc` | ASP.NET Core MVC | C#/F# | `Microsoft.NET.Sdk.Web` | 传统 MVC 网站 |
| `blazor` | Blazor Web 应用 | C# | `Microsoft.NET.Sdk.Web` | 用 C# 写交互式前端 |
| `blazorwasm` | Blazor WebAssembly 独立应用 | C# | `Microsoft.NET.Sdk.BlazorWebAssembly` | 纯浏览器端 C#（WASM） |
| `winforms` | Windows 窗体应用 | C#/VB | `Microsoft.NET.Sdk`（需启用 Desktop） | Windows 桌面（拖拽式） |
| `wpf` | WPF 应用程序 | C#/VB | `Microsoft.NET.Sdk`（需启用 Desktop） | Windows 桌面（XAML 数据绑定） |
| `worker` | 辅助角色服务 | C# | `Microsoft.NET.Sdk.Worker` | 后台常驻服务、消息消费 |
| `xunit` | xUnit 测试项目 | C#/F#/VB | `Microsoft.NET.Sdk` | 单元测试（最常用） |
| `mstest` | MSTest 测试项目 | C#/F#/VB | `Microsoft.NET.Sdk` | 微软官方测试框架 |
| `nunit` | NUnit 3 测试项目 | C#/F#/VB | `Microsoft.NET.Sdk` | 老牌测试框架 |
| `grpc` | gRPC 服务 | C# | `Microsoft.NET.Sdk.Web` | 高性能 RPC |
| `razorclasslib` | Razor 类库 | C# | `Microsoft.NET.Sdk.Razor` | 可复用的 Razor 组件 |

除项目模板外，还有一批生成**配置文件**的模板，它们在工程化里非常实用：

| 短名称 | 生成的文件 | 用途 |
|---|---|---|
| `sln` | `.slnx`（.NET 10 默认） | 解决方案 |
| `slnx` | `.slnx` | 显式指定新格式 |
| `globaljson` | `global.json` | 锁定 SDK 版本 |
| `editorconfig` | `.editorconfig` | 代码风格与分析器规则 |
| `gitignore` | `.gitignore` | 忽略 `bin/`、`obj/` 等 |
| `buildprops` | `Directory.Build.props` | 统一 MSBuild 属性 |
| `buildtargets` | `Directory.Build.targets` | 统一自定义构建目标 |
| `nugetconfig` | `nuget.config` | NuGet 源配置 |
| `tool-manifest` | `.config/dotnet-tools.json` | 本地工具清单 |

### `dotnet new` 用法

```bash
# 列出所有可用模板（可按类型过滤：--type project / item / config）
dotnet new list
dotnet new list web

# 查看某个模板的全部参数——写脚本前务必先看这个
dotnet new console --help

# 创建控制台项目；-o 指定输出目录，-n 指定项目名
dotnet new console -n HelloTool -o src/HelloTool

# 指定目标框架与语言版本（框架必须已安装对应 SDK 或模板包）
dotnet new classlib -n MyLib -f net10.0 --langVersion 14

# 生成显式 Program 类 + Main 方法，而不是顶级语句
dotnet new console -n ExplicitMain --use-program-main

# 创建解决方案（.NET 10 默认 slnx 格式），并把项目加进去
dotnet new sln -n MyApp
dotnet sln MyApp.slnx add src/HelloTool/HelloTool.csproj

# 创建 xUnit 测试项目
dotnet new xunit -n MyApp.Tests -o tests/MyApp.Tests
```

**自定义模板。** 当你需要把团队的项目骨架（固定的依赖、目录结构、CI 配置）固化成模板时，可以自建：

```bash
# 1) 先把一个"标准项目"写好，然后在它的目录放 .template.config/template.json
mkdir -p MyTemplate/.template.config

# 2) 安装模板（从本地文件夹）——安装后 dotnet new list 里就能看到
dotnet new install ./MyTemplate

# 3) 用短名称创建项目
dotnet new mytemplate -n NewService

# 4) 卸载
dotnet new uninstall ./MyTemplate
```

`template.json` 的最小可用形态：

```json
{
  "$schema": "http://json.schemastore.org/template",
  "author": "YourTeam",
  "classifications": [ "Company", "WebAPI" ],
  "identity": "YourTeam.WebApi.Template",
  "name": "YourTeam Web API",
  "shortName": "yt-webapi",
  "sourceName": "MyTemplate",
  "tags": { "language": "C#", "type": "project" }
}
```

其中 `sourceName` 是**替换锚点**：模板里所有出现 `MyTemplate` 的地方（文件内容、文件名）都会被替换成 `-n` 指定的名字。这是模板机制最容易踩的坑——锚点名字必须足够独特。

### `dotnet` CLI 命令详解

| 命令 | 作用 | 关键参数 | 典型用法 |
|---|---|---|---|
| `dotnet new` | 从模板创建项目/文件 | `-n`、`-o`、`-f`、`--use-program-main` | `dotnet new console -n App` |
| `dotnet restore` | 解析依赖并下载包，生成 `project.assets.json` | `--source`、`--no-cache` | `dotnet restore --source ./local-feed` |
| `dotnet build` | 编译项目（隐含 restore） | `-c`、`-f`、`--no-restore`、`-warnaserror` | `dotnet build -c Release -warnaserror` |
| `dotnet run` | 编译并运行项目 | `-c`、`--project`、`-f`、`--no-build` | `dotnet run --project src/App -c Release` |
| `dotnet test` | 发现并运行单元测试 | `--filter`、`--collect`、`--logger` | `dotnet test --filter "FullyQualifiedName~Order"` |
| `dotnet publish` | 编译并产出可部署产物 | `-c`、`-r`、`--self-contained`、`-p:` | `dotnet publish -c Release -r win-x64 --self-contained true` |
| `dotnet pack` | 把类库打成 `.nupkg` | `-c`、`-o`、`--version-suffix` | `dotnet pack -c Release -o ./artifacts` |
| `dotnet clean` | 删除构建输出 | `-c`、`-f` | `dotnet clean -c Release` |
| `dotnet add reference` | 添加项目引用 | 目标 `.csproj` 路径 | `dotnet add To/To.csproj reference From/From.csproj` |
| `dotnet add package` | 添加 NuGet 包引用 | `--version`、`--prerelease`、`--source` | `dotnet add package Newtonsoft.Json --version 13.*` |
| `dotnet list package` | 列出包并提供分析开关 | `--outdated`、`--vulnerable`、`--deprecated` | `dotnet list package --vulnerable --include-transitive` |
| `dotnet remove` | 移除引用或包 | `reference` / `package` | `dotnet remove package Newtonsoft.Json` |
| `dotnet sln` | 管理解决方案成员 | `add` / `remove` / `list` | `dotnet sln App.slnx list` |
| `dotnet format` | 按 `.editorconfig` 格式化并应用分析建议 | `--verify-no-changes`、`--severity` | `dotnet format --verify-no-changes` |
| `dotnet nuget` | 管理源、凭据、推送 | `add source` / `list source` / `push` | `dotnet nuget list source` |
| `dotnet --info` | 打印 SDK、运行时与 RID 信息 | — | 排查"环境不对"的第一条命令 |
| `dotnet --list-sdks` | 列出已安装 SDK | — | 确认 CI 与本地一致 |

> [!warning] `add package` 的默认版本陷阱
> 不指定 `--version` 时，`dotnet add package` 会写入**当前解析到的最新稳定版**（精确版本号，不是通配）。
> 这意味着不同时间在两台机器上执行同一命令，会得到不同的 `.csproj`。
> 在团队协作中，请把"加包"当作一次需要 Review 的代码变更，而不是随手执行的本地操作。

### 项目引用与包引用的区别

这是初学者最容易混淆的一对概念。

```xml
<ItemGroup>
  <!-- 项目引用：编译期直接可见源码，构建顺序自动推导 -->
  <ProjectReference Include="..\MyApp.Core\MyApp.Core.csproj" />

  <!-- 包引用：从 NuGet 源解析，带版本语义 -->
  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
</ItemGroup>
```

| 维度 | `ProjectReference` | `PackageReference` |
|---|---|---|
| 来源 | 同一仓库内的源码项目 | NuGet 源（nuget.org / 私有源 / 本地目录） |
| 版本 | 无版本概念，永远是"当前源码" | 必须处理版本与版本范围 |
| 构建 | 自动加入构建顺序，改动即时生效 | 需 `restore` 后从缓存读取 |
| 传递性 | 默认传递（被引用项目的包引用会流向使用方） | 由 `PrivateAssets` / `IncludeAssets` 精细控制 |
| 传递性默认行为 | `ProjectReference` 默认**会**传递 | `PackageReference` 的编译资产默认传递 |
| 适用场景 | 单体仓库内的分层（Core / Cli / Tests） | 第三方库、跨仓库复用、团队共享组件 |
| 调试体验 | 可以 F11 直接步入源码 | 无源码，只能看元数据（除非配 Source Link） |

控制资产流动的元数据：

```xml
<!-- 开发期才需要的包，不传播给引用我的项目 -->
<PackageReference Include="xunit" Version="2.9.2">
  <PrivateAssets>all</PrivateAssets>
</PackageReference>

<!-- 只用于构建，不进运行时依赖 -->
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
```

> [!tip] 什么时候该把项目引用改成包引用
> 当同一个类库被 **两个以上仓库**需要，或者它的发布节奏与主应用**不同**时，就该拆成 NuGet 包。
> 反之，只要还在同一个仓库、同一个发布节奏里，项目引用几乎总是更好的选择——省掉了版本对齐的负担。

### NuGet 包管理

#### 版本范围语法

NuGet 支持区间表示法。**不写范围、只写一个版本号，语义是"大于等于"而不是"等于"**，这是最反直觉的一点：

| 写法 | 实际规则 | 说明 |
|---|---|---|
| `1.0` | $x \ge 1.0$ | 最低版本（非独占）。解析到**最小**可接受稳定版 |
| `[1.0,)` | $x \ge 1.0$ | 与 `1.0` 等价，显式写法 |
| `(1.0,)` | $x > 1.0$ | 最低版本，独占 |
| `[1.0]` | $x = 1.0$ | **精确匹配**——锁定版本时用这个 |
| `(,1.0]` | $x \le 1.0$ | 最大版本（非独占） |
| `(,1.0)` | $x < 1.0$ | 最大版本，独占 |
| `[1.0,2.0]` | $1.0 \le x \le 2.0$ | 闭区间 |
| `(1.0,2.0)` | $1.0 < x < 2.0$ | 开区间 |
| `[1.0,2.0)` | $1.0 \le x < 2.0$ | 半开区间，防大版本升级常用 |
| `1.*` | 任意 `1.x.y` | 通配，解析到该区间**最高**可接受稳定版 |
| `(1.0)` | 无效 | NuGet 会报错 |

```xml
<!-- 接受 6.1 及以上，解析到最小的可接受稳定版 -->
<PackageReference Include="ExamplePackage" Version="6.1" />

<!-- 接受任意 6.x.y，解析到最高的可接受稳定版 -->
<PackageReference Include="ExamplePackage" Version="6.*" />

<!-- 只接受 6.1.0 这一个版本 -->
<PackageReference Include="ExamplePackage" Version="[6.1.0]" />

<!-- 接受 1.3.2 到 1.4.x，但不接受 1.5 及更高 -->
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />
```

预发布版本的排序规则也值得记住：`1.0.1-rc.10` **高于** `1.0.1-rc.2`（点分数字按数值比较），而 `1.0.1-alpha10` 按**反向字母序**排在 `1.0.1-alpha2` 之前。常见后缀约定是 `-alpha` → `-beta` → `-rc` → 正式版。

NuGet 还会**规范化版本号**：`1.00` 视为 `1.0`，`1.0.0.0` 视为 `1.0.0`，`1.0.7+r3456` 中的构建元数据被删除。所以 `1.0` 和 `1.0.0` 是同一个包。

#### 中央包管理（CPM）

一个解决方案有 20 个项目、每个都有 `<PackageReference Include="Serilog" Version="..."/>`，升级一次要改 20 处——这是 CPM 要解决的问题。

第一步，在仓库根目录新建 `Directory.Packages.props`：

```xml
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <!-- 可选：允许用可传递依赖的版本覆盖隐式引用 -->
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Serilog" Version="4.2.0" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
    <!-- 全局包引用：所有项目都会引用，且不传播给下游 -->
    <GlobalPackageReference Include="Nerdbank.GitVersioning" Version="3.7.115" />
  </ItemGroup>
</Project>
```

第二步，各项目里**去掉 `Version` 属性**：

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Serilog" />
  </ItemGroup>
</Project>
```

也可以直接用模板生成：`dotnet new packagesprops`（需模板已安装）。

按目标框架指定不同版本：

```xml
<ItemGroup>
  <PackageVersion Include="PackageA" Version="1.0.0" Condition="'$(TargetFramework)' == 'netstandard2.0'" />
  <PackageVersion Include="PackageA" Version="2.0.0" Condition="'$(TargetFramework)' == 'net8.0'" />
</ItemGroup>
```

单个项目临时覆盖版本（需未被禁用）：

```xml
<PackageReference Include="PackageA" VersionOverride="3.0.0" />
```

> [!warning] CPM 的三个坑
> 1. **只读最近的 `Directory.Packages.props`。** MSBuild 从项目目录向上查找，找到第一个就停。若你在 `Solution1/` 和仓库根各放一份，`Solution1` 下的项目**只会**读前者的设置。要合并父级配置必须手写 `<Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Packages.props, $(MSBuildThisFileDirectory)..))" />`。
> 2. **多源会报 NU1507。** 配置里定义了多个源时 CPM 会警告，需用 `packageSourceMapping` 做源映射或只保留一个源。
> 3. **可传递固定不允许降级。** 把包固定到低于依赖方要求的版本会直接报错 NU1109。

#### 私有源配置 `nuget.config`

在仓库根目录放 `nuget.config` 是最佳实践，它保证了不同机器解析出相同的依赖：

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <!-- clear 会清掉所有继承来的源（含用户级、机器级），保证可复现 -->
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="Contoso" value="https://contoso.com/packages/" />
    <add key="LocalFeed" value=".\local-packages" />
  </packageSources>

  <packageSourceCredentials>
    <Contoso>
      <add key="Username" value="%NUGET_USER%" />
      <!-- 用环境变量注入，不要提交明文密码 -->
      <add key="ClearTextPassword" value="%NUGET_TOKEN%" />
    </Contoso>
  </packageSourceCredentials>

  <!-- 源映射：Contoso.* 只从 Contoso 源下载，其余走 nuget.org -->
  <packageSourceMapping>
    <packageSource key="Contoso">
      <package pattern="Contoso.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>
```

配置的**应用顺序**（后者覆盖前者）：机器级 → 用户级 → 各级目录向上找到的 `nuget.config`。`<clear />` 是切断继承的关键指令。

#### `dotnet nuget` 子命令

```bash
# 列出当前生效的所有源（会标注来自哪个配置文件）
dotnet nuget list source

# 添加源；--configfile 限定只改哪个文件（避免污染全局配置）
dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org
dotnet nuget add source https://myTeam.pkgs.visualstudio.com/_packaging/feed/nuget/v3/index.json \
  -n myTeam -u myUser -p "$PAT" --configfile ./nuget.config

# 添加本地目录作为源（离线开发、CI 缓存常用）
dotnet nuget add source ./local-packages -n LocalFeed --configfile ./nuget.config

# 禁用某个源（不删除，便于临时切换）
dotnet nuget disable source LocalFeed --configfile ./nuget.config

# 移除源
dotnet nuget remove source LocalFeed --configfile ./nuget.config

# 推送包（--skip-duplicate 让 CI 重跑时幂等）
dotnet nuget push ./artifacts/MyLib.1.0.0.nupkg \
  --source https://api.nuget.org/v3/index.json \
  --api-key "$NUGET_API_KEY" --skip-duplicate
```

> [!warning] 凭据安全
> `--store-password-in-clear-text` 会把密码明文写入配置文件，**不要提交到版本库**。
> 加密后的密码只有 Windows 支持，且只能由**同一台机器的同一个用户**解密——所以它同样不可跨机器共享。
> 正确做法：CI 里用环境变量（`%NUGET_TOKEN%`）或凭据提供程序。

### 多目标框架 `TargetFrameworks`

单个目标框架用**单数** `TargetFramework`，多个用**复数** `TargetFrameworks`（分号分隔）。

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <!-- 类库同时服务新旧运行时：一份源码，两个产物 -->
    <TargetFrameworks>netstandard2.0;net8.0;net10.0</TargetFrameworks>
    <LangVersion>latest</LangVersion>
  </PropertyGroup>

  <!-- 条件引用：只在特定目标框架下引入 -->
  <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
    <PackageReference Include="System.Text.Json" Version="8.0.5" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
    <PackageReference Include="System.Text.Json" Version="10.0.0" />
  </ItemGroup>
</Project>
```

产出的目录结构会按 TFM 分开：

```
bin/Release/
├── netstandard2.0/MyLib.dll
├── net8.0/MyLib.dll
└── net10.0/MyLib.dll
```

常用 TFM 与 `.NET Standard` 实现关系：

| 目标框架 | TFM | 实现的 .NET Standard | 备注 |
|---|---|---|---|
| .NET 10 | `net10.0` | 2.1 | 当前 LTS |
| .NET 9 | `net9.0` | 2.1 | STS |
| .NET 8 | `net8.0` | 2.1 | LTS |
| .NET Standard | `netstandard2.1` | — | 2.1 不被 .NET Framework 支持 |
| .NET Standard | `netstandard2.0` | — | 兼容面最广的"公约数" |
| .NET Framework | `net481` | 2.0 | 仅 Windows |
| Windows 专用 | `net10.0-windows` | 2.1 | WinForms / WPF 必须用它 |

> [!important] 多目标的构建代价
> `TargetFrameworks` 有几项就要编译几遍。一个 5 目标的类库，构建时间是单目标的 5 倍。
> 只在**确实需要兼容旧运行时**时才加目标；纯应用项目通常只需要一个 TFM。

### 条件编译符号与 `#if`

SDK 会为每个 TFM 自动定义预处理器符号，规则是：**点号和连字符替换成下划线，小写转大写**。

| TFM | 定义的符号 | "或更高版本"符号 |
|---|---|---|
| `net10.0` | `NET`、`NET10_0`、`NETCOREAPP` | `NET10_0_OR_GREATER`、`NET9_0_OR_GREATER`… |
| `net8.0` | `NET`、`NET8_0`、`NETCOREAPP` | `NET8_0_OR_GREATER`、`NET7_0_OR_GREATER`… |
| `netstandard2.0` | `NETSTANDARD`、`NETSTANDARD2_0` | `NETSTANDARD2_0_OR_GREATER` |
| `net481` | `NETFRAMEWORK`、`NET481` | `NET481_OR_GREATER`、`NET48_OR_GREATER`… |
| `net10.0-windows` | 上述 + `WINDOWS` | `WINDOWS7_0_OR_GREATER` 等平台符号 |
| Debug 配置 | `DEBUG`、`TRACE` | — |
| Release 配置 | `RELEASE`（.NET 5+ 起）、`TRACE` | — |

```csharp
// 优先用 *_OR_GREATER，因为它能自然覆盖未来的新框架
// 若写成 #if NET10_0，升级到 .NET 11 后这段代码会静默失效
public static class PlatformHelper
{
    public static string Describe()
    {
#if NET10_0_OR_GREATER
        return "运行在现代 .NET 上，可用最新 API";
#elif NETSTANDARD2_0
        return "运行在 .NET Standard 2.0 兼容层";
#elif NETFRAMEWORK
        return "运行在 .NET Framework 上";
#else
        return "未知目标框架";
#endif
    }

    public static void Log(string message)
    {
        // DEBUG 只在 Debug 配置下定义，Release 下这行代码会被编译器完全移除
#if DEBUG
        Console.WriteLine($"[DEBUG] {message}");
#endif
        Console.WriteLine(message);
    }
}
```

自定义符号与关闭隐式符号：

```xml
<PropertyGroup>
  <!-- 自定义符号 -->
  <DefineConstants>$(DefineConstants);FEATURE_EXPORT;TENANT_A</DefineConstants>

  <!-- 关闭 SDK 自动生成的框架符号（一般不要关） -->
  <DisableImplicitFrameworkDefines>true</DisableImplicitFrameworkDefines>
</PropertyGroup>
```

### Debug 与 Release 构建差异

| 维度 | Debug | Release |
|---|---|---|
| 默认配置 | `dotnet build` 的默认值 | `dotnet publish` 的默认值（.NET 8+） |
| `Optimize` | `false`（不优化 IL） | `true`（JIT 做内联、循环优化等） |
| 调试符号 | 生成完整 PDB，`DebugType=full` | 默认 `portable` PDB，可选不生成 |
| 定义符号 | `DEBUG`、`TRACE` | `RELEASE`、`TRACE` |
| `Debugger.IsAttached` 相关行为 | 完整 | 优化后可能无法单步 |
| 代码分析 | 全量 | 全量（可被 `OptimizeImplicitlyTriggeredBuild` 影响） |
| 产物路径 | `bin/Debug/<TFM>/` | `bin/Release/<TFM>/` |
| 典型用途 | 本地开发、断点调试 | 生产部署、性能测试 |

```xml
<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <Optimize>true</Optimize>
  <DebugType>portable</DebugType>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
```

> [!warning] 这三个坑几乎人人踩过
> 1. **用 Debug 测出来的性能数字没有意义。** `Optimize=false` 会让 JIT 放弃内联，热点代码可能慢很多倍。任何性能对比都必须在 Release 下做。
> 2. **`#if DEBUG` 包住的代码在 Release 里根本不存在**，包括它的副作用。不要用它来做"必须执行"的逻辑，那只是日志开关。
> 3. **Release 下优化可能导致附加调试器时行为异常**（变量被优化掉、断点错位）。这属于正常现象，不是"代码有 bug"。

### `Directory.Build.props` 与 `Directory.Build.targets`

这两个文件是**仓库级统一配置**的载体，名字固定，不能改名。

| 文件 | 导入时机 | 适合放什么 |
|---|---|---|
| `Directory.Build.props` | 由 `Microsoft.Common.props` **早期**导入 | 目标框架、语言版本、可空性、警告级别、公司/版本元数据 |
| `Directory.Build.targets` | 由 `Microsoft.Common.targets` **后期**导入 | 自定义 Target、需要在包与项目属性都就绪后覆盖的设置 |

**导入时机决定了一切**：`props` 里设置的属性可以被项目文件覆盖（所以适合当"默认值"），`targets` 里的设置能覆盖项目文件（适合当"强制约束"）。

```xml
<!-- Directory.Build.props：仓库统一的默认值 -->
<Project>
  <PropertyGroup>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <AnalysisLevel>latest-recommended</AnalysisLevel>

    <!-- 统一版本与元数据 -->
    <Version>1.4.0</Version>
    <Authors>YourTeam</Authors>
    <Company>YourCompany</Company>

    <!-- CI 里把路径规范化，让构建可复现 -->
    <ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
  </PropertyGroup>
</Project>
```

```xml
<!-- Directory.Build.targets：强制约束与自定义目标 -->
<Project>
  <!-- 后期导入，能压过单个项目的设置：禁止任何项目关掉警告即错误 -->
  <PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>

  <!-- 构建完成后打印产物路径，便于排查 -->
  <Target Name="PrintBuildOutput" AfterTargets="Build">
    <Message Importance="high" Text="已构建 $(MSBuildProjectName) -> $(TargetPath)" />
  </Target>
</Project>
```

> [!warning] 搜索与合并的两个陷阱
> 1. **找到第一个就停止向上搜索。** 如果 `src/Directory.Build.props` 和仓库根各有一份，`src` 下的项目**只会**读到 `src` 那份，根目录的设置全部丢失。要合并必须显式 Import 父级：
>    ```xml
>    <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))"
>            Condition="'' != $([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />
>    ```
> 2. **Linux 文件系统区分大小写。** 文件名必须是精确的 `Directory.Build.props`，写成 `directory.build.props` 在 Windows 能跑、在 Linux CI 上会被静默忽略——这是最难查的一类问题。

排查属性为什么没生效，用 MSBuild 的预处理输出：

```bash
dotnet msbuild -property:TargetFramework=net10.0 -preprocess:expanded.xml src/MyApp.Core/MyApp.Core.csproj
# expanded.xml 是完整展开后的构建描述，可以搜索属性被设置和使用的先后位置
```

### 程序集版本三兄弟

现代 SDK 项目**不需要手写 `AssemblyInfo.cs`**——`GenerateAssemblyInfo` 默认为 `true`，SDK 会从项目属性自动生成程序集特性。

| 属性（MSBuild） | 生成的特性 | 格式 | 谁在用它 |
|---|---|---|---|
| `Version` | `AssemblyInformationalVersion` | 任意字符串，如 `1.4.0-beta.2+abc1234` | **人**：关于对话框、包管理器、`dotnet --info` |
| `AssemblyVersion` | `AssemblyVersion` | `主.次.内部版本.修订`（四段数字） | **运行时**：强名称程序集的绑定与加载 |
| `FileVersion` | `AssemblyFileVersion` | Win32 版本号，四段数字 | **操作系统**：Windows 文件属性的"文件版本" |

```xml
<PropertyGroup>
  <!-- 人看的版本：允许语义化版本与预发布后缀 -->
  <Version>1.4.0-beta.2</Version>

  <!-- 运行时绑定用：一旦发布就不该再变，改它会导致依赖方加载失败 -->
  <AssemblyVersion>1.4.0.0</AssemblyVersion>

  <!-- 文件系统用 -->
  <FileVersion>1.4.0.2</FileVersion>

  <Product>MyApp</Product>
  <Company>YourCompany</Company>
</PropertyGroup>
```

三者的取值关系：

- 只写 `Version`，则 `AssemblyVersion` 与 `FileVersion` 都从它派生（`FileVersion` 通常省略预发布后缀）。
- 只写 `AssemblyVersion`，则 `Version` 默认是 `1.0.0`。
- 从 .NET 8 起，若配置了 Source Link，SDK 会**自动把 Git 提交哈希追加到 `InformationalVersion`**。若不想要，设 `<IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>`。

```csharp
using System.Reflection;

var asm = Assembly.GetExecutingAssembly();

// 取"给人看"的版本；注意它可能带 +githash 后缀
var informational = asm.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion;

// 取运行时绑定版本
var binding = asm.GetName().Version;

// 取文件版本
var fileVersion = asm.GetCustomAttribute<AssemblyFileVersionAttribute>()?.Version;

Console.WriteLine($"展示版本: {informational}");
Console.WriteLine($"绑定版本: {binding}");
Console.WriteLine($"文件版本: {fileVersion}");
```

> [!warning] 用版本号做特性开关是个坏主意
> 有人喜欢写 `if (binding >= new Version(2,0))` 来兼容新旧行为。
> 但 `AssemblyVersion` 的语义是**绑定标识**，不是功能版本；它一旦变大，所有引用方都必须重新编译。
> 要做功能判断，请用显式的特性检测（接口、`AppContext` 开关、能力查询），不要解析版本号。

### `global.json` 固定 SDK 版本

`global.json` 控制**用哪个 SDK 来执行 `dotnet` 命令**，与项目目标框架无关。CI 场景基本都需要它。

```json
{
  "sdk": {
    "version": "10.0.401",
    "rollForward": "latestFeature",
    "allowPrerelease": false
  }
}
```

`version` 必须是**完整的三段/四段版本号**（如 `10.0.401`），不支持 `10`、`10.0`、`10.0.x` 或版本范围。

`rollForward` 策略（版本号格式为 `x.y.znn`，`x`=主版本，`y`=次版本，`z`=功能区段，`nn`=修补程序）：

| 值 | 行为 |
|---|---|
| `patch` | 用指定版本；找不到就前滚到最新修补级别；再找不到则失败。**未设置时的默认值** |
| `feature` | 同功能区段的最新修补级别；找不到则前滚到下一功能区段 |
| `minor` | 再进一步允许前滚到同一主版本内的下一较高次版本 |
| `major` | 再进一步允许前滚到下一个较高主版本 |
| `latestPatch` | 安装的最新修补级别（须 ≥ 指定值），不跨功能区段 |
| `latestFeature` | 同一主次版本内的最高功能区段 + 修补级别 |
| `latestMinor` | 同一主版本内的最高次版本 |
| `latestMajor` | 已安装的最高 SDK（≥ 指定值） |
| `disable` | 不前滚，要求精确匹配。配合包锁定文件时使用 |

```bash
# 用模板生成（推荐，避免手写错字段）
dotnet new globaljson --sdk-version 10.0.401 --roll-forward latestFeature

# 验证当前生效的 SDK
dotnet --version
dotnet --info      # 会打印 global.json 的解析结果与 RID
```

> [!tip] CI 与本地的一致性策略
> 本地用 `latestFeature`（允许安装 SDK 的服务更新），CI 用 `disable` 或精确版本 + 固定镜像。
> 这样本地不会被小版本卡住，而 CI 的构建完全可复现。
> 注意 .NET 10 SDK 新增的 `paths` 和 `errorMessage` 字段可以指定非全局安装的 SDK 位置，但它们**只对 SDK 命令生效**，对直接运行 apphost（`app.exe`）或 `dotnet app.dll` 无效。

### 发布模式对比

这是工具链里对最终产物影响最大的决策。所有发布模式共享同一个阶段：把 IL 编译为本机代码。区别在于**编译发生的时间与地点**：

$$
\text{总耗时} \;=\; \underbrace{T_{\text{构建}}}_{\text{发布时一次性}} \;+\; \underbrace{T_{\text{启动}}}_{\text{每次运行}} \;+\; \underbrace{T_{\text{JIT}}}_{\text{热点代码}}
$$

三种典型选择对应把这三项成本放在不同位置：**框架依赖**把 $T_{\text{JIT}}$ 留在运行时（构建最快、启动有预热）；**ReadyToRun** 用更大的 $T_{\text{构建}}$ 和体积换取 $T_{\text{JIT}}$ 的下降；**NativeAOT** 把绝大部分成本压到 $T_{\text{构建}}$，从而让 $T_{\text{启动}} + T_{\text{JIT}}$ 接近最小。**裁剪**不改变这三项，而是减小产物体积。

| 发布模式 | 关键参数 | 体积量级 | 启动速度 | 目标机需要装运行时 | 主要代价 |
|---|---|---|---|---|---|
| 框架依赖（FDD） | 默认，`--self-contained false` | **最小**（几 MB） | 中 | **是** | 目标机运行时版本可能变化，行为随之改变 |
| 跨平台 DLL | `-p:UseAppHost=false` | 最小 | 中 | 是 | 只能 `dotnet myapp.dll` 启动 |
| 自包含（SCD） | `--self-contained true -r <RID>` | **大**（数十至上百 MB） | 中 | 否 | 体积大；升级运行时必须重新发布 |
| 单文件 | `-p:PublishSingleFile=true` | 大 | **偏慢** | 看是否配合 SCD | 运行时需解压到临时目录 |
| 裁剪 | `-p:PublishTrimmed=true` | 明显小于 SCD | 中 | 否 | 反射/动态加载可能被裁掉，需 `TrimmerRootAssembly` 等标注 |
| ReadyToRun | `-p:PublishReadyToRun=true` | 大于普通程序集 | **快** | 看部署模式 | 同时含 IL 和本机代码，构建更慢 |
| NativeAOT | `-p:PublishAot=true` | 小（通常小于 SCD） | **最快** | 否 | 框架支持受限、构建慢、调试困难、平台相关 |

> [!warning] 关于体积数字
> 上表故意不给具体 MB 数。实际体积取决于：目标 RID、是否启用全球化固定模式、引用了哪些包、
> 以及 .NET 版本。请在你的真实项目上用 `dotnet publish` **实测**再决定。
> 唯一的通用结论是量级关系：`FDD < 单文件裁剪 < SCD`，而 NativeAOT 通常明显小于 SCD。

常用发布命令：

```bash
# 框架依赖（默认）——目标机需装 .NET 10 运行时
dotnet publish -c Release

# 跨平台 DLL（不带平台可执行文件）
dotnet publish -c Release -p:UseAppHost=false

# 自包含——把运行时一起打包
dotnet publish -c Release -r win-x64 --self-contained true

# 单文件（常与自包含、裁剪组合）
dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true

# 裁剪（减小自包含体积）
dotnet publish -c Release -r linux-x64 --self-contained true -p:PublishTrimmed=true

# ReadyToRun（提升启动与首次执行性能，体积增大）
dotnet publish -c Release -r win-x64 -p:PublishReadyToRun=true

# NativeAOT（需项目内已设 PublishAot=true）
dotnet publish -c Release -r win-x64 -p:PublishAot=true

# 发布为容器镜像（.NET SDK 8.0.200+ 内置支持，无需自己写 Dockerfile）
dotnet publish -c Release -t:PublishContainer
```

NativeAOT 需要在项目文件中启用：

```xml
<PropertyGroup>
  <PublishAot>true</PublishAot>
  <InvariantGlobalization>true</InvariantGlobalization>
  <StripSymbols>true</StripSymbols>
</PropertyGroup>
```

**选择决策：**

- 内部服务 / 容器部署 → **框架依赖**（镜像里已有运行时，体积最小、安全补丁自动生效）
- 分发给不懂技术的用户、需双击即用 → **自包含 + 单文件**
- 命令行小工具、要秒开、不接受 JIT 预热 → **NativeAOT** 或 **ReadyToRun**
- 云函数 / Serverless（冷启动敏感）→ **NativeAOT**（注意先确认依赖库的 AOT 兼容性）
- 对体积极敏感且不用反射重的库 → **裁剪**（务必跑完整测试）

### 单元测试项目与 `dotnet test`

```bash
# 创建测试项目并加入解决方案
dotnet new xunit -n MyApp.Tests -o tests/MyApp.Tests
dotnet add tests/MyApp.Tests/MyApp.Tests.csproj reference src/MyApp.Core/MyApp.Core.csproj
dotnet sln MyApp.slnx add tests/MyApp.Tests/MyApp.Tests.csproj
```

```xml
<!-- 测试项目.csproj 关键点 -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <!-- 测试项目本身不该被打成 NuGet 包 -->
    <IsPackable>false</IsPackable>
    <!-- 测试项目通常放宽可空性警告，减少噪音 -->
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
    <PackageReference Include="xunit" Version="2.9.2" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" />
    <PackageReference Include="coverlet.collector" Version="6.0.2" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\..\src\MyApp.Core\MyApp.Core.csproj" />
  </ItemGroup>
</Project>
```

```csharp
using Xunit;

public class WordCounterTests
{
    // 命名建议：方法名_场景_期望结果
    [Fact]
    public void Count_TwoSameWords_ReturnsCountTwo()
    {
        var result = WordCounter.Count("go go stop");
        Assert.Equal(2, result["go"]);
    }

    // [Theory] + [InlineData] 用一组数据覆盖多个分支，避免复制粘贴
    [Theory]
    [InlineData("", 0)]
    [InlineData("   ", 0)]
    [InlineData("a", 1)]
    public void Count_EdgeCases_ReturnsExpectedTotal(string input, int expected)
    {
        var result = WordCounter.Count(input);
        Assert.Equal(expected, result.Values.Sum());
    }
}
```

```bash
# 运行全部测试
dotnet test

# 只跑名字里含 Order 的测试（xUnit 过滤器语法）
dotnet test --filter "FullyQualifiedName~Order"

# 收集覆盖率
dotnet test --collect:"XPlat Code Coverage"

# Release 配置 + 输出 trx 报告（CI 常用）
dotnet test -c Release --logger "trx;LogFileName=results.trx" --results-directory ./TestResults
```

> [!note] .NET 10 的测试运行器选择
> 从 .NET 10 SDK 起，`dotnet test` 可以在 **VSTest**（传统，默认）和 **Microsoft.Testing.Platform（MTP）**（新，更快）之间选择。
> 在 `global.json` 中声明：
> ```json
> { "test": { "runner": "Microsoft.Testing.Platform" } }
> ```
> 两者的命令行选项并不完全相同，切换后需要核对脚本。

### 代码格式化与静态分析

#### `.editorconfig`

`.editorconfig` 同时承担两个职责：**格式化规则**（缩进、换行）和**分析器规则严重级别**。

```ini
# 顶部的 root=true 阻止向上继续查找，保证仓库自包含
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 4

[*.{cs,csx}]
# 代码风格（IDE 规则）
csharp_new_line_before_open_brace = all
csharp_style_namespace_declarations = file_scoped:warning
csharp_style_var_when_type_is_apparent = true:suggestion
dotnet_sort_system_directives_first = true

# 分析器规则严重级别：none / silent / suggestion / warning / error
dotnet_diagnostic.CA1062.severity = error      # 验证公共方法参数非 null
dotnet_diagnostic.CA2007.severity = none       # 库中不强制 ConfigureAwait
dotnet_diagnostic.IDE0005.severity = warning   # 移除多余的 using

[*.{json,yml,yaml}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false
```

#### `dotnet format`

```bash
# 按 .editorconfig 修复格式、代码风格与分析器建议
dotnet format

# 只检查不修改；CI 里用它当"格式门禁"（有格式问题则退出码非 0）
dotnet format --verify-no-changes

# 只做空白/换行层面的格式化
dotnet format whitespace

# 只应用代码风格规则
dotnet format style --severity info

# 只应用分析器（非代码风格）修复
dotnet format analyzers --severity warn

# 限定与排除目录
dotnet format --include ./src/ ./tests/ --exclude ./src/legacy/
```

> [!warning] `dotnet format` 会编译并运行分析器
> 官方文档明确提醒：**只对可信代码运行**该命令。它并非"纯文本格式化器"。

#### 可空性与警告级别

```xml
<PropertyGroup>
  <!-- 可空引用类型：把 null 相关 bug 从运行时提前到编译期 -->
  <Nullable>enable</Nullable>

  <!-- 警告即错误：CI 里极其推荐，阻止"警告债务"累积 -->
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>

  <!-- 允许个别警告例外（NU1701 等第三方兼容性噪音） -->
  <WarningsNotAsErrors>NU1701;CS1591</WarningsNotAsErrors>

  <!-- 代码分析强度 -->
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
  <AnalysisLevel>latest-recommended</AnalysisLevel>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>

  <!-- 让代码分析（CAxxxx）警告也遵守 TreatWarningsAsErrors -->
  <CodeAnalysisTreatWarningsAsErrors>true</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>
```

```csharp
#nullable enable
public sealed class UserService
{
    // 返回 null 时用 ? 标注，调用方必须处理——编译器会强制它
    public User? FindById(int id) => id > 0 ? new User("Ada") : null;

    public string GetDisplayName(int id)
    {
        var user = FindById(id);
        // 不建议用 ! 直接压制，那等于关掉这个文件里最有价值的检查
        return user?.Name ?? "匿名用户";
    }
}

public sealed record User(string Name);
```

### CI 中构建 .NET 项目的要点

在 GitHub Actions 中构建 .NET 的最小可用流水线（关于流水线设计本身见 [[工具-08-CICD入门]]）：

```yaml
name: build
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # actions/setup-dotnet 会读取仓库里的 global.json 决定装哪个 SDK
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      # 先恢复再构建，让 restore 层可以被缓存
      - run: dotnet restore

      # 格式门禁：格式不对直接失败
      - run: dotnet format --verify-no-changes

      - run: dotnet build --no-restore -c Release -warnaserror

      - run: dotnet test --no-build -c Release --logger "trx;LogFileName=results.trx"
        env:
          # 让构建可复现（路径规范化）；也便于生成 deterministic PDB
          ContinuousIntegrationBuild: 'true'

      - run: dotnet publish src/MyApp.Cli/MyApp.Cli.csproj --no-build -c Release -o ./out
```

CI 的六条实践要点：

1. **提交 `global.json`**，并让 CI 的 SDK 版本与本地一致。否则会出现"CI 报错本地正常"。
2. **先 `restore` 再 `build --no-restore`**，这样 restore 结果可以被缓存（`~/.nuget/packages`）。
3. **提交 `nuget.config`**，用 `<clear />` 切断继承，保证 CI 的源与本地一致。
4. **Release + `TreatWarningsAsErrors`**。Debug 构建会掩盖优化相关问题，警告即错误能防止技术债。
5. **加 `dotnet format --verify-no-changes` 作为格式门禁**，把风格争论交给工具。
6. **产物用 `dotnet publish` 而非 `dotnet build` 的输出**。`build` 的输出目录缺少运行时配置和部分依赖，直接拿去部署会出问题。

## 怎么用：从零搭一个可构建、可测试、可发布的多项目仓库

下面这套命令在 **.NET SDK 10.0.401** 上可直接执行。

```bash
# ---------- 1. 验证环境 ----------
dotnet --version          # 期望输出 10.0.401
dotnet --list-sdks        # 确认只装了预期的 SDK（多 SDK 时才需要 global.json 介入）
dotnet --info             # 查看 RID、运行时版本、global.json 解析结果

# ---------- 2. 创建仓库骨架 ----------
mkdir WordCountTool && cd WordCountTool
dotnet new globaljson --sdk-version 10.0.401 --roll-forward latestFeature
dotnet new sln -n WordCountTool                    # .NET 10 默认生成 WordCountTool.slnx
dotnet new gitignore
dotnet new editorconfig
dotnet new buildprops                              # 生成 Directory.Build.props
dotnet new nugetconfig                             # 生成 nuget.config

# ---------- 3. 创建项目 ----------
dotnet new classlib -n WordCount.Core -o src/WordCount.Core
dotnet new console  -n WordCount.Cli  -o src/WordCount.Cli
dotnet new xunit    -n WordCount.Tests -o tests/WordCount.Tests

# ---------- 4. 建立引用关系（先项目引用，再测试引用两者）----------
dotnet add src/WordCount.Cli/WordCount.Cli.csproj reference src/WordCount.Core/WordCount.Core.csproj
dotnet add tests/WordCount.Tests/WordCount.Tests.csproj reference src/WordCount.Core/WordCount.Core.csproj

# ---------- 5. 加入解决方案 ----------
dotnet sln WordCountTool.slnx add src/WordCount.Core/WordCount.Core.csproj
dotnet sln WordCountTool.slnx add src/WordCount.Cli/WordCount.Cli.csproj
dotnet sln WordCountTool.slnx add tests/WordCount.Tests/WordCount.Tests.csproj
dotnet sln WordCountTool.slnx list

# ---------- 6. 加一个第三方包并检查安全性 ----------
dotnet add src/WordCount.Cli/WordCount.Cli.csproj package Serilog.Sinks.Console
dotnet list package --vulnerable --include-transitive   # 检查已知漏洞

# ---------- 7. 构建、格式化、测试 ----------
dotnet build -c Release -warnaserror
dotnet format --verify-no-changes
dotnet test -c Release

# ---------- 8. 发布两种形态，对比体积 ----------
dotnet publish src/WordCount.Cli/WordCount.Cli.csproj -c Release -o ./out-fdd
dotnet publish src/WordCount.Cli/WordCount.Cli.csproj -c Release -r win-x64 \
  --self-contained true -p:PublishSingleFile=true -o ./out-single

# Windows 下对比体积（PowerShell）
# Get-ChildItem ./out-fdd, ./out-single -Recurse -File |
#   Group-Object DirectoryName |
#   Select-Object Name, @{n='MB';e={[math]::Round(($_.Group | Measure-Object Length -Sum).Sum/1MB,2)}}
```

`WordCount.Core` 的实现（词频统计，也是 [[编程语言对比]] 里的对照样例）：

```csharp
using System.Text.RegularExpressions;

namespace WordCount.Core;

public static partial class WordCounter
{
    // 用源生成的正则（GeneratedRegex）避免每次调用都重新解析模式，
    // 同时它是 NativeAOT 友好的——运行时动态生成的正则会被 AOT 裁掉。
    [GeneratedRegex(@"[\p{L}\p{N}']+")]
    private static partial Regex WordPattern();

    /// <summary>统计文本中每个词出现的次数，按次数降序、同次数按字典序返回。</summary>
    public static SortedDictionary<string, int> CountTop(string text, int topN = 10)
    {
        ArgumentNullException.ThrowIfNull(text);

        var counts = new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase);

        foreach (Match match in WordPattern().Matches(text))
        {
            // ToLowerInvariant 而非 ToLower：结果不随机器区域设置而变
            var word = match.Value.ToLowerInvariant();
            counts[word] = counts.GetValueOrDefault(word) + 1;
        }

        // 先按次数降序，再按词字典序，保证输出稳定（可测试）
        var ordered = counts
            .OrderByDescending(pair => pair.Value)
            .ThenBy(pair => pair.Key, StringComparer.Ordinal)
            .Take(topN);

        return new SortedDictionary<string, int>(
            ordered.ToDictionary(pair => pair.Key, pair => pair.Value),
            StringComparer.Ordinal);
    }
}
```

```csharp
// WordCount.Cli/Program.cs —— 顶级语句
using WordCount.Core;

if (args.Length == 0)
{
    Console.Error.WriteLine("用法: WordCount.Cli <文件路径> [topN]");
    return 1;   // 顶级语句里用 return 设置退出码
}

var path = args[0];
var topN = args.Length > 1 && int.TryParse(args[1], out var n) ? n : 10;

if (!File.Exists(path))
{
    Console.Error.WriteLine($"文件不存在: {path}");
    return 1;
}

var text = await File.ReadAllTextAsync(path);
var result = WordCounter.CountTop(text, topN);

foreach (var (word, count) in result.OrderByDescending(p => p.Value).ThenBy(p => p.Key, StringComparer.Ordinal))
{
    Console.WriteLine($"{word,-20} {count}");
}

return 0;
```

```bash
# 实际运行
dotnet run --project src/WordCount.Cli -- README.md 5
```

## 常见坑

> [!warning] 十二个高频陷阱
> 1. **手写 `<Compile Include>`** → NETSDK1022 重复包含。SDK 已用 glob 自动包含源码。
> 2. **`.slnx` 与老工具不兼容**。.NET 10 默认生成 `slnx`；需要 `sln` 时显式 `--format sln`。
> 3. **`Directory.Build.props` 只读最近的一个**。多级目录时必须手写 `<Import>` 合并父级。
> 4. **`Directory.Build.props` 文件名大小写**。Windows 能过、Linux CI 静默失效。
> 5. **`dotnet add package` 不指定版本**，导致同一命令在不同时间产生不同的 `.csproj`。
> 6. **误以为 `Version="1.0"` 是精确版本**。它表示 $\ge 1.0$，精确匹配要写 `[1.0]`。
> 7. **CPM 下项目文件里还留着 `Version` 属性**，导致该包版本被静默忽略或直接报错。
> 8. **明文密码提交进 `nuget.config`**。用 `%ENV_VAR%` 注入，并加密密码不可跨机器。
> 9. **在 Debug 下做性能测试**。`Optimize=false` 让结果毫无参考价值。
> 10. **多目标框架忘了条件引用**，导致 `netstandard2.0` 目标编译失败（引用了不存在的 API）。
> 11. **NativeAOT 下用运行时反射/动态正则**。这些在裁剪与 AOT 下会失败，需要用 `GeneratedRegex`、`JsonSerializerContext` 等源生成方案。
> 12. **CI 里用 `dotnet build` 的产物去部署**。应该用 `dotnet publish` 的输出。

## 练习题

**1.（模板与结构）** 用一条命令列出本机所有可用模板中标签含 `Web` 的项，然后创建一个使用最小 API 的 Web API 项目，并让它**不使用**顶级语句（生成显式 `Program` 类 + `Main`）。写出完整命令。

**2.（引用与依赖）** 一个解决方案里有 `Core`、`Api`、`Api.Tests` 三个项目。`Api` 与 `Api.Tests` 都需要 `Core`，`Api.Tests` 需要 `xunit`（不应传播给任何下游），`Api` 需要 `Serilog`。写出所有 `dotnet` 命令，并说明为什么 `xunit` 要配 `PrivateAssets=all`。

**3.（多目标与条件编译）** 写一个类库，同时面向 `netstandard2.0` 与 `net10.0`。要求在 `net10.0` 下使用 `System.Text.Json` 10.0、在 `netstandard2.0` 下使用 8.0，并提供 `Describe()` 方法在两个 TFM 下返回不同文字。写出 `.csproj` 与 C# 代码，并解释为什么应使用 `NET10_0_OR_GREATER` 而不是 `NET10_0`。

**4.（发布选型）** 你有一个内部 Linux 容器服务和一个要发给 Windows 用户的桌面小工具（用户不会装运行时）。分别该选哪种发布模式？各写出 `dotnet publish` 命令，并说明两种选择在体积、启动速度、维护成本上的权衡。

**5.（版本号）** 某项目 `Version = 1.4.0-beta.2`，未显式设置 `AssemblyVersion` 与 `FileVersion`。请判断：`AssemblyInformationalVersion`、`AssemblyVersion`、`FileVersion` 各大约是什么值？如果这个程序集被另一个强名称程序集引用，改动哪个属性会破坏绑定？为什么说不该用版本号做特性开关？

## FAQ

> [!question] `dotnet build` 和 `dotnet publish` 到底差在哪？
> `build` 产出**可用于本机运行和调试**的输出（`bin/<Config>/<TFM>/`），包含程序集和依赖，但不做部署优化、不保证包含运行所需的全部文件；`publish` 产出**可直接部署**的输出（默认 `bin/<Config>/<TFM>/publish/`），会解析 RID、复制原生依赖、应用裁剪/单文件/AOT 等设置。
> 关键差异：从 .NET 8 起 `dotnet publish` **默认使用 Release 配置**，而 `dotnet build` 默认 Debug。所以 `dotnet publish` 不加 `-c` 时也是 Release，这常让人以为"我没指定配置却拿到了优化版本"。

> [!question] 为什么我的构建在本地正常，一到 CI 就报找不到 SDK 或找不到包？
> 按顺序排查四件事：
> 1. `dotnet --info` 对比两边的 SDK 版本；若不一致，检查 `global.json` 是否被提交、`rollForward` 是否过严。
> 2. 检查 `nuget.config` 是否提交且用了 `<clear />`；CI 常常没有配置私有源的凭据。
> 3. 检查文件名大小写（`Directory.Build.props`、`Directory.Packages.props`）——这是 Linux 与 Windows 的经典差异。
> 4. 检查是否依赖了只在本机存在的本地源（`LocalFeed`）或本地工具。

> [!question] 类库该不该提交 `packages.lock.json`？
> 应用项目（`OutputType=Exe`、可执行的服务）**推荐提交**，它把整个传递依赖图钉死，是 CI 可复现性的最有力保障。
> 类库则要谨慎：锁文件会阻止下游项目获取依赖更新，容易造成"我这个库只能用旧版依赖"的问题。类库更该做的是**声明合理的版本范围**，把选择权留给使用方。
> 启用方式：`<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>`；CI 中用 `dotnet restore --locked-mode` 强制按锁文件还原。

> [!question] 裁剪（Trim）和 NativeAOT 都会因为反射出问题，我该怎么提前发现？
> 打开分析器，把警告当错误对待：
> ```xml
> <PropertyGroup>
>   <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
>   <ILLinkTreatWarningsAsErrors>true</ILLinkTreatWarningsAsErrors>
>   <IsAotCompatible>true</IsAotCompatible>
> </PropertyGroup>
> ```
> 然后在代码里优先使用源生成方案替代运行时反射：`[GeneratedRegex]` 代替 `new Regex(...)`、`JsonSerializerContext` 代替默认的 `JsonSerializer` 反射路径、避免 `Assembly.LoadFrom` 和动态 `Type.GetType`。
> 最后一定要**在真实发布产物上跑完整测试**——分析器只能覆盖它能静态看出来的调用。

## 相关笔记

- [[CSharp-01-环境与基础语法]]——SDK 安装、第一个项目、顶级语句与基础类型，建议先读
- [[CSharp-06-现代CSharp特性]]——源生成器与可空引用类型，直接决定本文中裁剪/AOT 与警告策略的可行性
- [[工具-03-包管理器]]——把 NuGet 与 npm、pip 放在一起比较，理解版本范围与锁文件的共性
- [[工具-08-CICD入门]]——本文最后一节的上位概念：流水线阶段划分与缓存策略
- [[后端-07-Docker与容器化]]——`dotnet publish -t:PublishContainer` 与手写 Dockerfile 的取舍
- [[后端-03-ASPNET-Core]]——`Microsoft.NET.Sdk.Web` 项目在真实服务中的组织方式

## 参考来源

- .NET 项目 SDK 概述（项目文件、glob、隐式 using）：https://learn.microsoft.com/zh-cn/dotnet/core/project-sdk/overview
- `dotnet new` 的 .NET 默认模板（模板短名称与参数）：https://learn.microsoft.com/zh-cn/dotnet/core/tools/dotnet-new-sdk-templates
- 中断性变更：`dotnet new sln` 默认为 SLNX 文件格式（.NET 10）：https://learn.microsoft.com/zh-cn/dotnet/core/compatibility/sdk/10.0/dotnet-new-sln-slnx-default
- NuGet 包版本参考（版本范围语法表、预发布排序、版本规范化）：https://learn.microsoft.com/zh-cn/nuget/concepts/package-versioning
- 中央包管理（CPM）（`Directory.Packages.props`、可传递固定、`VersionOverride`）：https://learn.microsoft.com/zh-cn/nuget/consume-packages/central-package-management
- `nuget.config` 文件参考（源、凭据、源映射、环境变量）：https://learn.microsoft.com/zh-cn/nuget/reference/nuget-config-file
- `dotnet nuget add source` 命令：https://learn.microsoft.com/zh-cn/dotnet/core/tools/dotnet-nuget-add-source
- SDK 样式项目中的目标框架（TFM 列表、预处理器符号、OS 特定 TFM）：https://learn.microsoft.com/zh-cn/dotnet/standard/frameworks
- Microsoft.NET.Sdk 的 MSBuild 属性参考（`TargetFrameworks`、`PublishAot`、`TreatWarningsAsErrors`、分析器属性）：https://learn.microsoft.com/zh-cn/dotnet/core/project-sdk/msbuild-props
- 按文件夹自定义生成（`Directory.Build.props` / `.targets` 的导入顺序与搜索规则）：https://learn.microsoft.com/zh-cn/visualstudio/msbuild/customize-by-directory
- .NET 应用程序发布概述（六种发布模式、命令速查、优缺点）：https://learn.microsoft.com/zh-cn/dotnet/core/deploying/
- 在代码中设置程序集属性（`AssemblyVersion` / `AssemblyFileVersion` / `AssemblyInformationalVersion`）：https://learn.microsoft.com/zh-cn/dotnet/standard/assembly/set-attributes
- global.json 概述（`rollForward` 策略表、匹配规则）：https://learn.microsoft.com/zh-cn/dotnet/core/tools/global-json
- `dotnet test` 命令（VSTest 与 Microsoft.Testing.Platform 的选择）：https://learn.microsoft.com/zh-cn/dotnet/core/tools/dotnet-test
- `dotnet format` 命令（子命令、`--verify-no-changes`、`--severity`）：https://learn.microsoft.com/zh-cn/dotnet/core/tools/dotnet-format
- C# 编译器选项（在 `.csproj` 中设置 `LangVersion` 等）：https://learn.microsoft.com/zh-cn/dotnet/csharp/language-reference/compiler-options/

> [!note] 版本提示
> 本文所有命令与属性在 **.NET SDK 10.0.401**（LTS，支持至 2028-11）上验证。
> .NET 的版本节奏为每年一个大版本，偶数版本为 LTS。属性名与默认值可能随 SDK 更新变化，
> 请以 https://learn.microsoft.com/zh-cn/dotnet/core/ 的官方文档为最终依据。
