.NET CLI 备忘清单 & dotnet-cli cheatsheet & Quick Reference

介绍

.NET CLI 是随 .NET SDK 提供的跨平台工具链，用于开发、构建、运行、测试和发布 .NET 应用。

$ dotnet --info
$ dotnet --version
$ dotnet --list-sdks
$ dotnet --list-runtimes

dotnet 既可以运行 .NET 应用，也可以执行项目相关命令。所有命令都支持 --help 查看简要帮助。

命令结构

$ dotnet <command> [arguments] [options]
$ dotnet build --configuration Release
$ dotnet run --project src/MyApp
$ dotnet MyApp.dll

常见短选项包括 -c|--configuration、-f|--framework、-o|--output、-r|--runtime。

常用流程

$ dotnet new console -n HelloCli
$ cd HelloCli
$ dotnet restore
$ dotnet build
$ dotnet run
$ dotnet test
$ dotnet publish -c Release -o ./publish

多数命令会按需触发还原。CI 或离线场景中可显式使用 dotnet restore 并在后续命令中配合 --no-restore。

基础命令

命令	说明	示例
`new`	基于模板创建项目或文件	`dotnet new webapi -n Api`
`restore`	还原项目依赖	`dotnet restore`
`build`	构建项目、解决方案或文件应用	`dotnet build -c Release`
`run`	从源码构建并运行项目	`dotnet run --project src/App`
`test`	运行测试项目	`dotnet test --logger trx`
`publish`	生成可部署输出	`dotnet publish -c Release -o ./publish`
`pack`	创建 NuGet 包	`dotnet pack -c Release`
`clean`	清理构建输出	`dotnet clean`
`sln`	管理解决方案文件	`dotnet sln add src/App/App.csproj`
`format`	格式化代码	`dotnet format`
`watch`	监听文件变化并执行命令	`dotnet watch run`
`vstest`	运行已编译测试程序集	`dotnet vstest tests.dll`

dotnet run 适合开发迭代，不推荐作为生产运行方式。部署时应使用 dotnet publish 输出。

创建项目

$ dotnet new list
$ dotnet new console -n HelloCli
$ dotnet new webapi -n Api
$ dotnet new classlib -n Core
$ dotnet new gitignore

dotnet new 使用模板引擎创建项目或其他文件。可通过 dotnet new search <关键字> 查找模板。

构建

$ dotnet build
$ dotnet build MyApp.sln -c Release
$ dotnet build src/App/App.csproj -f net8.0
$ dotnet build --no-restore

dotnet build 使用 MSBuild 构建项目并支持 MSBuild 属性，例如 -p:Version=1.2.3。

发布

$ dotnet publish -c Release -o ./publish
$ dotnet publish -c Release -r win-x64 --self-contained true
$ dotnet publish -c Release -r linux-x64 --self-contained false

dotnet publish 会编译应用、读取依赖并生成可部署输出，是官方支持的部署准备方式。

$ dotnet publish -c Release -p:PublishSingleFile=true
$ dotnet publish -c Release -p:PublishTrimmed=true
$ dotnet publish -c Release -p:PublishReadyToRun=true

单文件、裁剪和 ReadyToRun 等选项会影响输出大小、启动速度和兼容性，发布前应在目标环境测试。

运行

$ dotnet run
$ dotnet run --project src/App
$ dotnet run --configuration Release -- arg1 arg2
$ dotnet run --no-build

应用参数放在 -- 后面，避免与 dotnet run 自身选项混淆。

测试

$ dotnet test
$ dotnet test -c Release
$ dotnet test --filter FullyQualifiedName~Unit
$ dotnet test --collect "XPlat Code Coverage"

dotnet test 会运行测试项目，并把参数传递给测试平台。

NuGet 包引用

命令	说明	示例
`dotnet add package`	.NET 9 及更早版本添加包	`dotnet add package Newtonsoft.Json`
`dotnet package add`	.NET 10 起添加或更新包	`dotnet package add Newtonsoft.Json`
`dotnet list package`	.NET 9 及更早版本列出包	`dotnet list package`
`dotnet package list`	.NET 10 起列出包	`dotnet package list`
`dotnet remove package`	移除包引用	`dotnet remove package Newtonsoft.Json`
`dotnet package search`	搜索 NuGet 包	`dotnet package search Newtonsoft.Json`

.NET 10 引入了更一致的“名词优先”命令顺序。维护旧项目时仍常见 dotnet add package 和 dotnet list package。

包版本与源

$ dotnet add package Serilog --version 4.0.0
$ dotnet package add Serilog --version 4.0.0
$ dotnet restore --source https://api.nuget.org/v3/index.json

添加包时 CLI 会检查包与项目目标框架的兼容性，并把 PackageReference 写入项目文件。

项目引用

$ dotnet add app/app.csproj reference lib/lib.csproj
$ dotnet reference add lib/lib.csproj --project app/app.csproj
$ dotnet list reference
$ dotnet reference list --project app/app.csproj
$ dotnet remove reference lib/lib.csproj

项目引用会在 .csproj 中生成 ProjectReference。CLI 不提供添加任意程序集引用的命令，需手动编辑项目文件。

NuGet 源

命令	说明	示例
`nuget list source`	列出源	`dotnet nuget list source`
`nuget add source`	添加源	`dotnet nuget add source <url> -n Private`
`nuget update source`	更新源	`dotnet nuget update source Private -s <url>`
`nuget enable source`	启用源	`dotnet nuget enable source Private`
`nuget disable source`	禁用源	`dotnet nuget disable source Private`
`nuget remove source`	移除源	`dotnet nuget remove source Private`
`nuget locals`	查看或清理缓存	`dotnet nuget locals all --clear`

包发布与签名

$ dotnet pack -c Release
$ dotnet nuget push bin/Release/MyLib.1.0.0.nupkg -k API_KEY -s https://api.nuget.org/v3/index.json
$ dotnet nuget delete MyLib 1.0.0 -s https://api.nuget.org/v3/index.json -k API_KEY
$ dotnet nuget verify MyLib.1.0.0.nupkg
$ dotnet nuget sign MyLib.1.0.0.nupkg --certificate-path cert.pfx

发布到 nuget.org 时建议使用 scoped API key，并避免把密钥写入仓库。

解决方案

$ dotnet new sln -n MySolution
$ dotnet sln add src/App/App.csproj
$ dotnet sln add tests/App.Tests/App.Tests.csproj
$ dotnet sln list
$ dotnet sln remove tests/App.Tests/App.Tests.csproj

解决方案文件用于组织多个项目，方便统一构建和测试。

.NET 工具

命令	说明	示例
`tool install -g`	安装全局工具	`dotnet tool install -g dotnet-ef`
`tool install --local`	安装本地工具	`dotnet tool install --local dotnet-ef`
`tool list`	列出工具	`dotnet tool list -g`
`tool update`	更新工具	`dotnet tool update -g dotnet-ef`
`tool restore`	还原本地工具	`dotnet tool restore`
`tool run`	运行本地工具	`dotnet tool run dotnet-ef`
`tool uninstall`	卸载工具	`dotnet tool uninstall -g dotnet-ef`
`tool search`	搜索工具	`dotnet tool search format`

本地工具依赖 .config/dotnet-tools.json manifest，适合团队项目固定工具版本。

工作负荷

$ dotnet workload list
$ dotnet workload search maui
$ dotnet workload install maui
$ dotnet workload update
$ dotnet workload restore
$ dotnet workload repair
$ dotnet workload uninstall maui

工作负荷用于安装 MAUI、Android、iOS、WebAssembly 等 SDK 扩展。

MSBuild

$ dotnet msbuild
$ dotnet msbuild /t:Clean,Build /p:Configuration=Release
$ dotnet build -p:TreatWarningsAsErrors=true

dotnet build 内部使用 MSBuild；需要更细粒度控制时可直接使用 dotnet msbuild。

构建服务器

$ dotnet build-server list
$ dotnet build-server shutdown

构建服务器缓存可能影响诊断结果。遇到奇怪的构建缓存问题时，可以先关闭构建服务器后重试。

安装脚本

$ curl -sSL https://dot.net/v1/dotnet-install.sh | bash
$ powershell -ExecutionPolicy Bypass -File dotnet-install.ps1 -Channel 8.0

安装脚本适合 CI 或用户级安装。生产机器更推荐使用系统包管理器或官方安装程序。

CI 构建

$ dotnet restore
$ dotnet build --no-restore -c Release
$ dotnet test --no-build -c Release
$ dotnet publish --no-build -c Release -o ./publish

把还原、构建、测试和发布拆开，能减少重复工作并让失败位置更清晰。

.NET CLI 备忘清单

入门

介绍

命令结构

常用流程

项目命令

基础命令

创建项目

构建

发布

运行

测试

包与引用

NuGet 包引用

包版本与源

项目引用

NuGet 源

包发布与签名

解决方案与工具

解决方案

.NET 工具

工作负荷

诊断与高级

SDK 与运行时

MSBuild

构建服务器

安装脚本

开发证书

常见场景

CI 构建

多目标框架

指定运行时

另见