掌握.NET 命令行界面: 开发, 测试与部署的综合指南

要精通 dotnet CLI, 首先必须理解其命令的解剖结构. dotnet 可执行文件本身扮演着"驱动程序"的角色, 其核心职责有两个: 一是运行一个依赖框架的应用(例如 dotnet myapp.dll), 二是执行一个特定的命令(例如 dotnet build). dotnet 命令的完整结构由以下四个部分组成:

• 驱动程序 (Driver): 即 dotnet.exe. 当执行一个命令时, 它首先会确定要使用的 SDK 版本, 然后启动相应的命令进程.
• 命令 (Command): 表示要执行的具体操作, 如 build(构建代码), publish(发布应用)等.
• 参数 (Arguments): 是命令操作的目标, 通常是文件或路径, 例如在 dotnet publish my_app.csproj 中, my_app.csproj 就是 publish 命令的参数.
• 选项 (Options): 用于修改命令的行为, 通常以 -- 或 - 开头, 例如 --output /build_output 选项会指定发布的输出目录.

这种清晰, 分层的结构是理解和有效使用整个 dotnet 工具链的基础.

在复杂的软件生命周期中, 确保开发, 测试和生产环境的一致性至关重要. global.json 文件是实现这一目标的关键机制, 它允许开发者精确控制 dotnet CLI 使用的.NET SDK 版本, 从而保证构建的可复现性.

CLI 会在当前工作目录及其所有父目录中查找 global.json 文件. 这种发现机制使得可以在代码仓库的根目录放置一个 global.json 文件, 从而为整个项目锁定一个统一的 SDK 版本基线.

该文件不仅仅是指定一个固定版本, 它更像一份构建环境的"合同". 在团队协作和持续集成(CI/CD)场景中, 开发者本地使用的.NET 8.0.300 SDK 与构建服务器上的 8.0.200 SDK 可能存在细微差异, 这些差异可能导致"在我机器上能正常工作"的典型问题. global.json 通过声明"此仓库必须使用版本 X 或其兼容版本进行构建"来解决此问题.

global.json 的核心 schema 包含以下关键属性:

• sdk.version: 一个字符串, 用于指定一个确切的 SDK 版本号, 不支持通配符
• sdk.allowPrerelease: 一个布尔值, 用于控制是否允许 SDK 解析器考虑预览版. 其默认行为取决于执行环境(例如, 在 Visual Studio 的预览版中默认为 true)
• sdk.rollForward: 这是 global.json 中最具战略意义的属性, 它定义了当 version 字段中指定的 SDK 未找到时的回滚策略. 这为构建合同提供了必要的灵活性, 允许构建服务器使用更新的补丁版本(通常只包含安全和错误修复), 同时防止意外切换到可能引入重大变更的新功能带(feature band)或主版本. 其策略包括:
  • patch: 仅允许回滚到最新的补丁版本. 这是历史默认行为.
  • feature: 在同一主版本和次版本内, 允许回滚到更高的功能带.
  • minor: 在同一主版本内, 允许回滚到更高的次版本.
  • major: 允许回滚到任何更高的版本.
  • latestPatch, latestFeature, latestMinor, latestMajor: 强制使用已安装的, 大于等于指定版本的最新版本.
  • disable: 禁止任何回滚, 要求精确匹配.

随着.NET 的演进, global.json 也获得了新功能, 如.NET 10 预览版中引入的 paths 和 errorMessage, 它们分别提供了对 SDK 解析路径的更多控制和更友好的开发者错误提示.

dotnet new 命令是项目生命周期的起点, 用于从预定义的模板创建新项目和文件. 它的功能远不止于此, 它还是一个完整的模板管理系统, 支持从 NuGet 源安装和卸载自定义模板.

开发者可以为任何类型的项目(如应用, 服务, 工具或类库)创建自定义模板. 创建自定义模板的核心是构建一个包含源代码和 ./.template.config/template.json 配置文件的目录结构, 然后使用 dotnet pack 将其打包成一个 NuGet 包(.nupkg 文件)以便分发和复用.

对于包含多个项目的复杂应用程序, 解决方案文件(.sln)是组织和管理的核心. dotnet sln 命令提供了一套便捷的工具, 用于在解决方案文件中添加, 列出和移除项目.

这表明 CLI 不仅能管理单个项目, 还能在更高层次上掌控整个应用的结构. 开发者可以使用 dotnet new sln 创建一个新的解决方案文件, 然后通过 dotnet sln add <PROJECT_PATH> 将现有项目逐一添加到解决方案中.

在.NET 开发中, 依赖关系主要分为两种, 理解它们的区别对于构建健壮和可维护的系统至关重要.

• 项目到项目 (P2P) 引用: 通过 dotnet add reference <PROJECT_PATH> 添加. 这种引用在同一解决方案内的项目之间创建了直接的构建依赖. 当被引用的项目发生变化时, 构建系统会自动重新编译依赖于它的项目. 这种方式非常适合于紧密耦合, 共同开发的组件, 因为它提供了即时编译和跨项目调试的快速反馈循环
• NuGet 包引用: 通过 dotnet add package <PACKAGE_NAME> 添加. 这种引用指向一个来自 NuGet 源(如官方的 nuget.org 或私有源)的不可变的, 版本化的包. 这是消费外部库或已发布内部组件的标准方式.

选择使用项目引用还是本地 NuGet 包, 这并非一个纯粹的技术决策, 而是一个战略选择.

项目引用适合于 单体式开发模型, 其中所有代码都在一个解决方案中, 追求的是紧密的开发反馈循环. 而本地 NuGet 包则模拟了 分布式或基于微服务的开发模型.

即使所有代码都在同一个代码仓库中, 使用本地包也强制实行了基于版本和契约的依赖关系, 模仿了消费第三方库的流程. 这种方式虽然开发流程稍慢, 但能强制实现更清晰的关注点分离和更强的模块边界. 下表总结了这两种本地开发策略的权衡.

表 3: 本地开发策略对比: 项目引用 vs. 本地 NuGet 源

dotnet nuget… 系列命令的实现机制并非直接内置于 dotnet.exe 的主解析器中. 实际上, 当执行这类命令时, dotnet 驱动程序会启动一个名为 NuGet.CommandLine.XPlat.dll 的独立进程, 并将所有相关参数转发给它.

这种"进程派生"模型解释了一些行为上的不一致性. 由于主 dotnet/sdk 仓库需要为制表符补全(tab-completion)等功能维护一套重复的命令定义,

当 NuGet 团队在其工具中添加新功能时, dotnet CLI 对其的完全支持(特别是自动补全)可能会有延迟.

这是一个架构上的权衡: 它允许 NuGet 团队独立地迭代其工具, 但也创造了一个开发者偶尔会感受到的"接缝". 理解这一"为什么"能让开发者更深刻地认识到工具的行为及其演进过程.

dotnet CLI 提供了一套完整的命令来管理项目的 NuGet 依赖:

• dotnet package add: 此命令向项目的 .csproj 文件中添加一个 <PackageReference> 元素. 关键选项包括 -v 或 –version 用于指定特定版本, -s 或 –source 用于指定包源, 以及 –prerelease 用于允许安装预发布版本
• dotnet package list: 这是一个强大的依赖审查工具. 它不仅能列出项目引用的顶级包, 还能通过 –include-transitive 选项显示传递性依赖. 近年来, 它已演变为一个项目健康检查工具, 通过 –outdated, –deprecated 和 –vulnerable 等选项, 可以快速识别过时, 已弃用或存在已知安全漏洞的包
• dotnet package remove: 与 add 对应, 此命令用于从 .csproj 文件中移除 <PackageReference>
• dotnet restore: 此命令会读取项目文件中列出的所有包引用, 并将它们从配置的 NuGet 源下载并解压到本地的全局包缓存中, 以供后续的构建和运行使用.

现代 dotnet CLI 的一个关键生产力特性是"隐式还原". 诸如 build, run, publish 和 pack 等常用命令, 在执行前会自动检查依赖是否需要还原, 如果需要则会隐式地运行 restore 操作 这种设计的初衷是为了方便开发者, 简化工作流程.

然而, 在某些特定场景下, 显式控制还原过程更为有利. 例如, 在 CI/CD 流水线中, 通过使用 –no-restore 选项禁用隐式还原, 并将 dotnet restore 作为一个独立的步骤, 可以更好地利用构建缓存.

依赖还原步骤的结果可以被缓存起来, 只要项目依赖没有变化, 后续的构建就可以跳过网络密集型的下载过程, 从而显著加快构建速度.

nuget.config 文件是 NuGet 配置的基石, 它以 XML 格式定义了 NuGet 客户端的行为.

• 分层加载: NuGet 的配置是分层聚合的. 它会从机器级别, 用户级别(在 Windows 上是 %APPDATA%\NuGet\NuGet.Config, 在 Linux/macOS 上是 ~/.config/NuGet/NuGet.Config)以及从项目根目录逐级向上查找到的 nuget.config 文件中加载并合并设置. 这种机制允许进行全局, 用户和仓库级别的精细化配置.
• 核心配置节:
  • <packageSources>: 定义了所有可用的包源列表. 每个源都有一个唯一的键(名称)和值(URL 或本地路径). 官方的 nuget.org 源地址是 https://api.nuget.org/v3/index.json
  • <globalPackagesFolder>: 指定全局包缓存的位置, 默认在用户配置文件的 .nuget/packages 目录下
  • <packageSourceCredentials>: 用于存储私有源的凭据.
  • <packageSourceMapping>: 一个现代且强大的安全功能, 允许将包 ID 的模式(如 Contoso.*)映射到特定的源. 这有助于防止"依赖混淆"攻击, 确保内部包只能从受信任的私有源下载.

尽管 nuget.config 文件可以手动编辑, 但 CLI 提供了一套命令用于编程式地管理包源, 这在自动化脚本中尤其有用:

• dotnet nuget add source: 添加一个新源
• dotnet nuget list source: 列出当前所有已配置的源
• dotnet nuget remove source: 移除一个指定的源
• dotnet nuget update source: 修改一个现有源的属性, 如 URL 或名称
• dotnet nuget enable/disable source: 启用或禁用一个源, 而无需将其从配置文件中删除.

在专业的开发环境中, 使用私有或认证的 NuGet 源是常态. dotnet nuget add source 命令支持通过 –username 和 –password 选项提供凭据. 然而, 将密码以明文形式存储在配置文件中(即使使用了 –store-password-in-clear-text)存在安全风险.

更安全, 现代的方法是使用凭据提供程序. 当 dotnet CLI 命令(如 restore 或 add package)需要访问认证源时, 如果配置了凭据提供程序, 它可以通过 –interactive 标志以交互方式提示用户登录, 或在非交互式环境中(如 CI/CD)自动获取访问令牌, 从而避免了在配置文件中硬编码任何敏感信息.

针对用户提出的"如何指定本地资源"的问题, 最直接和灵活的方法是建立一个基于本地文件夹的 NuGet 源. 这对于在多个项目间共享正在开发的库, 或者在没有网络连接的环境中工作非常有用

建立本地源的步骤非常简单:

1. 创建文件夹: 在本地文件系统上创建一个文件夹, 例如 D:\LocalNuGetFeed.

2. 添加为源: 使用 CLI 将此文件夹添加为一个 NuGet 源.

   dotnet nuget add source "D:\LocalNuGetFeed"--name "LocalFeed"
   

   这条命令会在用户的 nuget.config 文件中添加一个新条目

3. 打包库: 在一个类库项目中, 运行 dotnet pack 命令来生成一个 .nupkg 文件. 此文件通常位于项目的 bin\Debug 或 bin\Release 目录下.

4. 发布到本地源: 将生成的 .nupkg 文件复制到 D:\LocalNuGetFeed 文件夹中. 更优雅的方式是使用 dotnet nuget push 命令:

   dotnet nuget push "bin\Release\MyLibrary.1.0.0.nupkg"--source "LocalFeed"
   

   –source 选项的值是之前添加源时指定的名称 "LocalFeed"19.

为了进一步提升使用本地源的开发效率, 可以利用 MSBuild 的强大功能来自动化打包和推送流程. 通过在库项目的 .csproj 文件中添加一个自定义的 Target, 可以实现每次调试构建后自动更新本地包

以下是一个高级 MSBuild 目标的示例, 改编自社区分享的实践 12:

XML

<Target Name="PushToLocalFeed"AfterTargets="Build"Condition="'$(Configuration)' == 'Debug'">
  <PropertyGroup>
    <LocalFeedPath>$(SolutionDir)nuget</LocalFeedPath>
    <PackageVersion>$(::Now.ToString("yyyy.MM.dd.HHmmss"))-local</PackageVersion>
  </PropertyGroup>

  <Message Text="Pushing package with version $(PackageVersion) to $(LocalFeedPath)"Importance="high"/>

  <RemoveDir Directories="$(LocalFeedPath)"/>
  <MakeDir Directories="$(LocalFeedPath)"/>

  <Exec Command="dotnet pack --no-build --configuration $(Configuration) -p:PackageVersion=$(PackageVersion) --output "$(LocalFeedPath)""/>

  <Exec Command="dotnet nuget push "$(LocalFeedPath)\*.nupkg"--source Local --skip-duplicate"/>
</Target>

这个 MSBuild 目标实现了以下自动化流程:

1. 仅在 Debug 配置下, Build 完成后触发.
2. 使用当前的时间戳生成一个唯一的预发布版本号, 避免版本冲突.
3. 运行 dotnet pack, 使用新版本号打包项目, 并输出到解决方案下的 nuget 目录.
4. 运行 dotnet nuget push, 将新生成的包推送到名为 Local 的 NuGet 源.

这是个高阶技巧, 它将本地源的开发模式从手动操作转变为全自动流程, 极大地提高了迭代效率.

dotnet watch 是提升开发效率的关键工具, 它能监控文件变化并自动重新构建和运行应用, 从而为开发者提供一个极速的反馈循环 dotnet watch 的工作机制比表面看起来更复杂.

对于代码文件(如 .cs, .razor), 它利用 Roslyn 工作空间来分析代码变更. 如果变更是"轻微的"(即支持热重载), 它会生成一个差异补丁并应用到正在运行的应用中, 无需重启.

对于 Web 应用, 它还会启动一个 WebSocket 服务器, 在静态文件(如 CSS)变更时通知浏览器刷新, 实现无缝的前端开发体验 当代码变更过于"粗鲁"(Rude Edit), 即无法通过热重载应用时(例如修改了方法签名), dotnet watch 会提示用户是否重启应用.

开发者可以通过在项目文件中添加 <Watch> 项组来自定义需要监控的文件类型, 并通过 DOTNET_WATCH* 系列环境变量来精细控制其行为 24.

在开发过程中处理敏感数据(如 API 密钥, 数据库连接字符串)是一个常见的安全挑战. dotnet user-secrets 命令是.NET 为此提供的标准解决方案.

其核心机制是: 运行 dotnet user-secrets init 会在项目文件 .csproj 中添加一个唯一的 <UserSecretsId>. 这个 ID 对应于开发者本地用户配置文件目录下的一个特定文件夹, 其中存储着一个 secrets.json 文件. 这样, 所有敏感信息都保存在项目源码树之外, 从根本上防止了它们被意外提交到版本控制系统(如 Git)中.

必须强调的是, 用户机密是一个 仅限开发时使用的工具. 它存储的 secrets.json 文件是 未加密的 纯文本文件. 它的设计目标是防止敏感信息泄露到源代码仓库, 而不是保护信息免受本地机器被攻破的风险. 在生产环境中, 应使用更安全的方案, 如 Azure Key Vault, AWS Secrets Manager 或环境变量.

dotnet CLI 的一个强大之处在于其可扩展性. 开发者可以通过 dotnet tool install 命令安装由社区或第三方提供的工具来增强其功能 2. .NET 工具分为三种类型:

• 全局工具 (Global tools): 为每个用户安装一次, 如果其安装路径被添加到系统 PATH 环境变量中, 则可以在任何目录下调用.
• 工具路径工具 (Tool-path tools): 安装到指定的目录, 非常适合于 CI/CD 环境或需要隔离工具的场景.
• 本地工具 (Local tools): 作用域限定于特定的代码仓库, 其定义记录在仓库根目录下的 .config/dotnet-tools.json 清单文件中. 这是管理项目特定开发依赖(如代码格式化工具, linter)的推荐方式.

dotnet test 命令是.NET 测试工作流的核心. 它会自动构建解决方案, 并为每个测试项目启动一个测试执行器来运行测试.

它通过测试适配器(Test Adapters)与各种流行的测试框架(如 xUnit, NUnit, MSTest)无缝集成 在.NET 的测试领域, 一个重要的架构演进正在发生.

多年来, dotnet test 实际上是 vstest.console.exe 的一个前端包装. 然而, 从.NET 10 开始, 微软正在引入一个更轻量, 更高性能的"微软测试平台"(Microsoft Testing Platform, MTP).

这一前瞻性的变化预示着未来.NET 测试将变得更快, 更直接. 开发者可以通过在仓库根目录添加一个 dotnet.config 文件来启用 MTP 模式, 并调整其命令行参数以适应新的执行器. 了解这一演进方向, 有助于开发者编写更现代化, 面向未来的测试.

在大型项目中, 运行所有测试既耗时又低效. dotnet test 提供了强大的 –filter 选项, 允许开发者根据测试的 Name, ClassName, TestCategory 或其他属性来精确地运行一个子集. 例如, 在 CI 流程中, 可以配置一个作业只运行标记为 Category=Smoke 的烟雾测试, 而另一个作业运行完整的回归测试套件.

代码覆盖率是衡量测试完备性的重要指标. dotnet CLI 生态系统提供了成熟的工具链来生成覆盖率报告.

• Coverlet 生态系统: Coverlet 是目前最流行的跨平台代码覆盖率工具. 通过在运行 dotnet test 时添加 –collect "XPlat Code Coverage"选项, Coverlet 会在测试执行期间收集覆盖率数据, 并生成一个 coverage.cobertura.xml 文件
• 生成报告: 这个 XML 文件本身不易阅读, 但可以作为其他工具的输入. reportgenerator 是一个广泛使用的工具, 它可以将 Cobertura 格式的 XML 文件转换为美观, 易于导航的 HTML 报告
• 第一方工具: 微软也推出了官方的 dotnet-coverage 工具, 它提供了类似的功能, 表明了对代码覆盖率这一功能日益增长的第一方支持.

当开发一个旨在被其他项目复用的类库时, dotnet pack 命令是最终的打包工具. 它会读取 .csproj 文件中的元数据(如 PackageId, Version, Authors, Description, PackageTags), 并将项目编译的 DLL 和其他资产打包成一个 .nupkg 文件.

将所有元数据定义在 .csproj 文件中, 使其成为唯一的真实来源, 是一种最佳实践. 此外, –include-symbols 和 –include-source 选项可以创建符号包, 这对于库的消费者进行调试至关重要.

创建了 .nupkg 文件后, 下一步就是将其发布到 NuGet 源. dotnet nuget push 命令用于此目的, 它需要 –source(目标源的 URL 或名称)和 –api-key(用于认证的密钥)作为关键参数.

此命令可用于发布到公共的 nuget.org, 也可用于发布到私有的 Azure Artifacts 或 GitHub Packages 等源.

与用于库的 dotnet pack 不同, dotnet publish 命令专为部署*应用程序*而设计. 它会编译应用, 并将其所有依赖项(包括项目引用和 NuGet 包)复制到一个指定的输出目录, 使其成为一个可直接部署的单元 dotnet publish 支持两种主要的部署模式, 它们在部署产物, 依赖管理和运行环境方面有根本性的区别.

除了基本的部署模式外, dotnet CLI 还提供了一系列高级优化功能, 用于在部署大小, 启动性能和兼容性之间进行权衡. 这可以被看作是一个"优化三难困境": 开发者需要根据应用的具体目标来决定优先考虑哪个方面.

• 使用 ReadyToRun (R2R) 编译提升启动性能: R2R 是一种预先(Ahead-Of-Time, AOT)编译技术.

  它在发布时将部分 IL 代码编译为本地机器码, 从而减少了应用启动时 JIT(Just-In-Time)编译器的工作量, 显著加快了冷启动速度. 代价是部署包的体积会增大.

  通过在项目文件中设置 <PublishReadyToRun>true</PublishReadyToRun> 来启用 对于追求极致启动性能的场景, 还可以启用 <PublishReadyToRunComposite>true</PublishReadyToRunComposite>, 它能优化更多的代码, 但会进一步增加包体积和编译时间.

• 使用程序集裁剪减小应用体积: 程序集裁剪(Trimming)功能通过在发布时进行静态代码分析, 移除应用程序中未被引用的程序集, 类型和成员, 从而大幅减小独立部署应用(SCD)的体积. 通过设置 <PublishTrimmed>true</PublishTrimmed> 来启用.

  然而, 裁剪并非没有风险. 对于大量使用反射或动态加载程序集的应用, 静态分析可能无法准确判断哪些代码是"未使用"的, 从而导致运行时错误. 因此, 启用裁剪需要进行详尽的测试.

下表总结了这些高级优化技术的特点和权衡.

这个模型帮助开发者根据具体目标做出明智决策. 例如, 如果要部署到一个微小的物联网设备, 部署体积(Trimming)是首要考虑; 如果部署一个无服务器函数, 冷启动时间(R2R)则至关重要.