.NET Core CLI工具文档dotnet-pack

《.NET Core CLI工具文档dotnet-pack：从基础到进阶的包管理指南》

在.NET Core生态中，`dotnet-pack`是开发者将项目代码转换为NuGet包的标准化工具。作为.NET CLI命令集的核心组件，它通过简洁的命令行操作实现项目元数据配置、依赖管理、版本控制及多目标框架支持，是构建可复用组件库的关键环节。本文将系统解析`dotnet-pack`的工作原理、使用场景及高级技巧，帮助开发者高效完成包发布流程。

一、dotnet-pack基础概念

`dotnet-pack`是.NET SDK自带的跨平台命令行工具，用于将项目文件（.csproj/.fsproj）打包为符合NuGet规范的.nupkg文件。其核心功能包括：

• 自动解析项目中的``依赖项
• 生成包含.dll、.pdb及内容文件的标准化包结构
• 支持符号包（.snupkg）生成
• 多目标框架（TFM）的包构建

与手动创建.nuspec文件相比，`dotnet-pack`直接读取项目文件中的元数据（如``、``等），减少了配置文件的维护成本。其工作流程可简化为：

项目文件解析 → 依赖项收集 → 包结构生成 → 元数据注入 → 输出.nupkg

二、基础使用场景

1. 单项目打包

最简单的打包命令格式为：

dotnet pack MyLibrary.csproj

该命令会：

• 在当前目录查找MyLibrary.csproj文件
• 读取项目中的``配置
• 在bin/Debug（默认配置）下生成包

典型项目文件配置示例：

  
    net6.0
    MyCompany.Utilities
    1.0.0
    Developer Team
    Utility library for common tasks
  

2. 指定输出目录

通过`-o`参数控制包输出位置：

dotnet pack -o ./artifacts/packages

该参数常用于CI/CD流程中的制品管理，确保包文件集中存储。

3. 配置构建选项

结合`--configuration`参数指定构建配置：

dotnet pack --configuration Release

此时会读取项目中的``配置节点，通常包含优化后的编译选项。

三、高级功能解析

1. 多目标框架支持

在项目文件中定义多个目标框架：

net6.0;net7.0;netstandard2.0

执行`dotnet pack`时，工具会自动为每个框架生成独立的包文件（如MyLibrary.1.0.0.net6.0.nupkg）。

2. 符号包生成

添加`--include-symbols`参数生成包含调试信息的符号包：

dotnet pack --include-symbols

生成的.snupkg文件可用于NuGet的符号服务器，帮助调试依赖包中的代码。

3. 版本控制策略

通过``和``实现语义化版本管理：

  1.0
  beta-$([System.DateTime]::Now.ToString("yyyyMMdd"))

最终版本号将组合为`1.0-beta-20231015`，适合预发布版本管理。

4. 包含额外文件

使用``的``节点添加非代码文件：

这些文件会被复制到包内的指定路径，支持自定义安装行为。

四、CI/CD集成实践

1. GitHub Actions示例

典型工作流配置：

name: Pack and Publish
on:
  push:
    tags:
      - 'v*'
jobs:
  pack:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-dotnet@v2
        with:
          dotnet-version: '6.0.x'
      - run: dotnet pack --configuration Release -o ./packages
      - uses: actions/upload-artifact@v3
        with:
          name: nuget-packages
          path: ./packages

2. Azure DevOps流水线

YAML流水线片段：

steps:
- task: DotNetCoreCLI@2
  displayName: 'Pack NuGet'
  inputs:
    command: pack
    packagesToPack: '**/*.csproj'
    configuration: Release
    packDirectory: '$(Build.ArtifactStagingDirectory)/packages'
- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)/packages'
    ArtifactName: 'NuGetPackages'

五、常见问题解决方案

1. 依赖项未打包问题

当项目依赖本地文件时，需在.csproj中添加：

2. 版本冲突处理

使用`dotnet list package --include-transitive`检查依赖树，通过``的`VersionOverride`属性解决冲突。

3. 跨平台路径问题

在PowerShell中执行时，路径需使用双引号：

dotnet pack ".\src\MyProject.csproj" -o ".\output"

六、性能优化技巧

1. 并行构建：通过`/p:ParallelBuild=true`启用多核编译

2. 增量打包：结合`dotnet msbuild /t:Pack /p:RestorePackages=false`跳过依赖还原

3. 缓存策略：在CI中缓存`%USERPROFILE%\.nuget\packages`目录

关键词：.NET Core CLI、dotnet-pack、NuGet包、多目标框架、符号包、CI/CD集成、语义化版本、依赖管理、跨平台开发、项目元数据

简介：本文全面解析.NET Core CLI中的dotnet-pack工具，涵盖基础打包流程、多目标框架支持、符号包生成、CI/CD集成等核心功能，提供项目配置示例、常见问题解决方案及性能优化技巧，助力开发者高效构建和管理NuGet包。