CSharp-07-dotnet项目与工具链
这篇笔记讲什么
语法只是 C# 的一半。另一半是工程:项目文件怎么组织、包从哪里来、构建用什么配置、产物怎么发布。
这篇笔记把
.csproj/.slnx、dotnetCLI、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#/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 用法
# 列出所有可用模板(可按类型过滤:--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-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 与本地一致 |
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>
| 维度 | ProjectReference | PackageReference |
|---|---|---|
| 来源 | 同一仓库内的源码项目 | 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 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 必须用它 |
多目标的构建代价
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 | — |
// 优先用 *_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 构建差异
| 维度 | 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>/ |
| 典型用途 | 本地开发、断点调试 | 生产部署、性能测试 |
<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) | 生成的特性 | 格式 | 谁在用它 |
|---|---|---|---|
Version | AssemblyInformationalVersion | 任意字符串,如 1.4.0-beta.2+abc1234 | 人:关于对话框、包管理器、dotnet --info |
AssemblyVersion | AssemblyVersion | 主.次.内部版本.修订(四段数字) | 运行时:强名称程序集的绑定与加载 |
FileVersion | AssemblyFileVersion | Win32 版本号,四段数字 | 操作系统: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 的六条实践要点:
- 提交
global.json,并让 CI 的 SDK 版本与本地一致。否则会出现"CI 报错本地正常"。 - 先
restore再build --no-restore,这样 restore 结果可以被缓存(~/.nuget/packages)。 - 提交
nuget.config,用<clear />切断继承,保证 CI 的源与本地一致。 - Release +
TreatWarningsAsErrors。Debug 构建会掩盖优化相关问题,警告即错误能防止技术债。 - 加
dotnet format --verify-no-changes作为格式门禁,把风格争论交给工具。 - 产物用
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-filedotnet 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-testdotnet 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/ 的官方文档为最终依据。