w wyl123ly 的博客
MD

CSharp-07-dotnet项目与工具链

59 KB 2026.10.11 原文件

CSharp-07-dotnet项目与工具链

这篇笔记讲什么

语法只是 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——这既是它的灵活性来源,也是它让人困惑的原因。

<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

为什么这很重要

因为源码是自动包含的,手工再写一遍 <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 的内容极其简单:

<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>

.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#/VBMicrosoft.NET.Sdk脚本、命令行工具、学习
classlib类库C#/F#/VBMicrosoft.NET.Sdk可复用的业务逻辑、供 NuGet 发布
webapiASP.NET Core Web APIC#/F#Microsoft.NET.Sdk.WebREST 服务(默认最小 API)
webapiaotASP.NET Core API(AOT)C#Microsoft.NET.Sdk.Web需要原生编译的极速启动服务
mvcASP.NET Core MVCC#/F#Microsoft.NET.Sdk.Web传统 MVC 网站
blazorBlazor Web 应用C#Microsoft.NET.Sdk.Web用 C# 写交互式前端
blazorwasmBlazor WebAssembly 独立应用C#Microsoft.NET.Sdk.BlazorWebAssembly纯浏览器端 C#(WASM)
winformsWindows 窗体应用C#/VBMicrosoft.NET.Sdk(需启用 Desktop)Windows 桌面(拖拽式)
wpfWPF 应用程序C#/VBMicrosoft.NET.Sdk(需启用 Desktop)Windows 桌面(XAML 数据绑定)
worker辅助角色服务C#Microsoft.NET.Sdk.Worker后台常驻服务、消息消费
xunitxUnit 测试项目C#/F#/VBMicrosoft.NET.Sdk单元测试(最常用)
mstestMSTest 测试项目C#/F#/VBMicrosoft.NET.Sdk微软官方测试框架
nunitNUnit 3 测试项目C#/F#/VBMicrosoft.NET.Sdk老牌测试框架
grpcgRPC 服务C#Microsoft.NET.Sdk.Web高性能 RPC
razorclasslibRazor 类库C#Microsoft.NET.Sdk.Razor可复用的 Razor 组件

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

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

dotnet new 用法

# 列出所有可用模板(可按类型过滤:--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 配置)固化成模板时,可以自建:

# 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 的最小可用形态:

{
  "$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-maindotnet new console -n App
dotnet restore解析依赖并下载包,生成 project.assets.json--source、--no-cachedotnet restore --source ./local-feed
dotnet build编译项目(隐含 restore)-c、-f、--no-restore、-warnaserrordotnet build -c Release -warnaserror
dotnet run编译并运行项目-c、--project、-f、--no-builddotnet run --project src/App -c Release
dotnet test发现并运行单元测试--filter、--collect、--loggerdotnet 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-suffixdotnet pack -c Release -o ./artifacts
dotnet clean删除构建输出-c、-fdotnet clean -c Release
dotnet add reference添加项目引用目标 .csproj 路径dotnet add To/To.csproj reference From/From.csproj
dotnet add package添加 NuGet 包引用--version、--prerelease、--sourcedotnet add package Newtonsoft.Json --version 13.*
dotnet list package列出包并提供分析开关--outdated、--vulnerable、--deprecateddotnet list package --vulnerable --include-transitive
dotnet remove移除引用或包reference / packagedotnet remove package Newtonsoft.Json
dotnet sln管理解决方案成员add / remove / listdotnet sln App.slnx list
dotnet format按 .editorconfig 格式化并应用分析建议--verify-no-changes、--severitydotnet format --verify-no-changes
dotnet nuget管理源、凭据、推送add source / list source / pushdotnet nuget list source
dotnet --info打印 SDK、运行时与 RID 信息—排查"环境不对"的第一条命令
dotnet --list-sdks列出已安装 SDK—确认 CI 与本地一致

add package 的默认版本陷阱

不指定 --version 时,dotnet add package 会写入当前解析到的最新稳定版(精确版本号,不是通配)。

这意味着不同时间在两台机器上执行同一命令,会得到不同的 .csproj。

在团队协作中,请把"加包"当作一次需要 Review 的代码变更,而不是随手执行的本地操作。

项目引用与包引用的区别

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

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

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

控制资产流动的元数据:

<!-- 开发期才需要的包,不传播给引用我的项目 -->
<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>

什么时候该把项目引用改成包引用

当同一个类库被 两个以上仓库需要,或者它的发布节奏与主应用不同时,就该拆成 NuGet 包。

反之,只要还在同一个仓库、同一个发布节奏里,项目引用几乎总是更好的选择——省掉了版本对齐的负担。

NuGet 包管理

版本范围语法

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

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

<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 属性:

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

也可以直接用模板生成:dotnet new packagesprops(需模板已安装)。

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

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

单个项目临时覆盖版本(需未被禁用):

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

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 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 子命令
# 列出当前生效的所有源(会标注来自哪个配置文件)
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

凭据安全

--store-password-in-clear-text 会把密码明文写入配置文件,不要提交到版本库。

加密后的密码只有 Windows 支持,且只能由同一台机器的同一个用户解密——所以它同样不可跨机器共享。

正确做法:CI 里用环境变量(%NUGET_TOKEN%)或凭据提供程序。

多目标框架 TargetFrameworks

单个目标框架用单数 TargetFramework,多个用复数 TargetFrameworks(分号分隔)。

<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 10net10.02.1当前 LTS
.NET 9net9.02.1STS
.NET 8net8.02.1LTS
.NET Standardnetstandard2.1—2.1 不被 .NET Framework 支持
.NET Standardnetstandard2.0—兼容面最广的"公约数"
.NET Frameworknet4812.0仅 Windows
Windows 专用net10.0-windows2.1WinForms / WPF 必须用它

多目标的构建代价

TargetFrameworks 有几项就要编译几遍。一个 5 目标的类库,构建时间是单目标的 5 倍。

只在确实需要兼容旧运行时时才加目标;纯应用项目通常只需要一个 TFM。

条件编译符号与 #if

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

TFM定义的符号"或更高版本"符号
net10.0NET、NET10_0、NETCOREAPPNET10_0_OR_GREATER、NET9_0_OR_GREATER…
net8.0NET、NET8_0、NETCOREAPPNET8_0_OR_GREATER、NET7_0_OR_GREATER…
netstandard2.0NETSTANDARD、NETSTANDARD2_0NETSTANDARD2_0_OR_GREATER
net481NETFRAMEWORK、NET481NET481_OR_GREATER、NET48_OR_GREATER…
net10.0-windows上述 + WINDOWSWINDOWS7_0_OR_GREATER 等平台符号
Debug 配置DEBUG、TRACE—
Release 配置RELEASE(.NET 5+ 起)、TRACE—
// 优先用 *_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);
    }
}

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

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

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

Debug 与 Release 构建差异

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

这三个坑几乎人人踩过

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 里的设置能覆盖项目文件(适合当"强制约束")。

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

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

搜索与合并的两个陷阱

1. 找到第一个就停止向上搜索。 如果 src/Directory.Build.props 和仓库根各有一份,src 下的项目只会读到 src 那份,根目录的设置全部丢失。要合并必须显式 Import 父级:

```xml

<Import Project="(MSBuildThisFileDirectory)../'))"

Condition="'' != (MSBuildThisFileDirectory)../'))" />

```

2. Linux 文件系统区分大小写。 文件名必须是精确的 Directory.Build.props,写成 directory.build.props 在 Windows 能跑、在 Linux CI 上会被静默忽略——这是最难查的一类问题。

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

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

程序集版本三兄弟

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

属性(MSBuild)生成的特性格式谁在用它
VersionAssemblyInformationalVersion任意字符串,如 1.4.0-beta.2+abc1234人:关于对话框、包管理器、dotnet --info
AssemblyVersionAssemblyVersion主.次.内部版本.修订(四段数字)运行时:强名称程序集的绑定与加载
FileVersionAssemblyFileVersionWin32 版本号,四段数字操作系统:Windows 文件属性的"文件版本"
<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>。
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}");

用版本号做特性开关是个坏主意

有人喜欢写 if (binding >= new Version(2,0)) 来兼容新旧行为。

但 AssemblyVersion 的语义是绑定标识,不是功能版本;它一旦变大,所有引用方都必须重新编译。

要做功能判断,请用显式的特性检测(接口、AppContext 开关、能力查询),不要解析版本号。

global.json 固定 SDK 版本

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

{
  "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不前滚,要求精确匹配。配合包锁定文件时使用
# 用模板生成(推荐,避免手写错字段)
dotnet new globaljson --sdk-version 10.0.401 --roll-forward latestFeature

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

CI 与本地的一致性策略

本地用 latestFeature(允许安装 SDK 的服务更新),CI 用 disable 或精确版本 + 固定镜像。

这样本地不会被小版本卡住,而 CI 的构建完全可复现。

注意 .NET 10 SDK 新增的 paths 和 errorMessage 字段可以指定非全局安装的 SDK 位置,但它们只对 SDK 命令生效,对直接运行 apphost(app.exe)或 dotnet app.dll 无效。

发布模式对比

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

三种典型选择对应把这三项成本放在不同位置:框架依赖把 留在运行时(构建最快、启动有预热);ReadyToRun 用更大的 和体积换取 的下降;NativeAOT 把绝大部分成本压到 ,从而让 接近最小。裁剪不改变这三项,而是减小产物体积。

发布模式关键参数体积量级启动速度目标机需要装运行时主要代价
框架依赖(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)最快否框架支持受限、构建慢、调试困难、平台相关

关于体积数字

上表故意不给具体 MB 数。实际体积取决于:目标 RID、是否启用全球化固定模式、引用了哪些包、

以及 .NET 版本。请在你的真实项目上用 dotnet publish 实测再决定。

唯一的通用结论是量级关系:FDD < 单文件裁剪 < SCD,而 NativeAOT 通常明显小于 SCD。

常用发布命令:

# 框架依赖(默认)——目标机需装 .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 需要在项目文件中启用:

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

选择决策:

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

单元测试项目与 dotnet test

# 创建测试项目并加入解决方案
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
<!-- 测试项目.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>
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());
    }
}
# 运行全部测试
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

.NET 10 的测试运行器选择

从 .NET 10 SDK 起,dotnet test 可以在 VSTest(传统,默认)和 Microsoft.Testing.Platform(MTP)(新,更快)之间选择。

在 global.json 中声明:

```json

{ "test": { "runner": "Microsoft.Testing.Platform" } }

```

两者的命令行选项并不完全相同,切换后需要核对脚本。

代码格式化与静态分析

.editorconfig

.editorconfig 同时承担两个职责:格式化规则(缩进、换行)和分析器规则严重级别。

# 顶部的 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
# 按 .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/

dotnet format 会编译并运行分析器

官方文档明确提醒:只对可信代码运行该命令。它并非"纯文本格式化器"。

可空性与警告级别
<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>
#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入门):

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 上可直接执行。

# ---------- 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 的实现(词频统计,也是 编程语言对比 里的对照样例):

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);
    }
}
// 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;
# 实际运行
dotnet run --project src/WordCount.Cli -- README.md 5

常见坑

十二个高频陷阱

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" 是精确版本。它表示 ,精确匹配要写 [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

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,这常让人以为"我没指定配置却拿到了优化版本"。

为什么我的构建在本地正常,一到 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)或本地工具。

类库该不该提交 packages.lock.json?

应用项目(OutputType=Exe、可执行的服务)推荐提交,它把整个传递依赖图钉死,是 CI 可复现性的最有力保障。

类库则要谨慎:锁文件会阻止下游项目获取依赖更新,容易造成"我这个库只能用旧版依赖"的问题。类库更该做的是声明合理的版本范围,把选择权留给使用方。

启用方式:<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>;CI 中用 dotnet restore --locked-mode 强制按锁文件还原。

裁剪(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/

版本提示

本文所有命令与属性在 .NET SDK 10.0.401(LTS,支持至 2028-11)上验证。

.NET 的版本节奏为每年一个大版本,偶数版本为 LTS。属性名与默认值可能随 SDK 更新变化,

请以 https://learn.microsoft.com/zh-cn/dotnet/core/ 的官方文档为最终依据。