用命令行工具创建 NuGet 程序包

NuGet.exe 下载地址

本文翻译自：

• https://docs.nuget.org/Create/Creating-and-Publishing-a-Package
• https://docs.nuget.org/Create/Enforced-Package-Conventions

基本步骤

1. 使用 nuget spec 命令生成 nuspec 文件
2. 编辑 nuspec 文件，使用 nuget pack 命令打包

从程序集创建程序包

执行以下命令：生成  nuspec 文件：

nuget spec MyAssembly.dll

按需编辑 nuspec 文件后执行打包命令：

nuget pack MyAssembly.nuspec

从项目文件创建程序包

在项目文件夹执行：

nuget spec

工具会读取 csproj 或 vbproj 文件生成 nuspec 文件。这种方式生成的 nuspec 文件包含一些可替换标记，打包时会用项目的元数据替换标记。可用标记包括：

• $id$   用程序集名称替换
• $version$    用 AssemblyVersionAttribute 或 AssemblyInformationalVersionAttribute 替换
• $author$    用 AssemblyCompanyAttribute 替换
• $description$    用 AssemblyDescriptionAttribute 替换

若不需要自动替换，可手工移除这些标记。

注意，使用项目文件执行打包命令才会替换这些标记，使用 nuspec 文件执行打包命令不会替换。

使用 files 节点显式指定程序包中包含哪些文件，例如：

<files>
    <file src="..\..\SomeRoot\**\*.*" target="" />
</files>

程序包将仅包含这个节点中指定的文件，若 files 节点为空，则程序包将仅包含 lib 文件夹。另外 pack 命令会排除已句点开头的目录，例如 .git。

编辑好 nuspec 文件后，执行打包命令：

nuget pack MyProject.csproj

如果项目引用其他项目，可使用 -IncludeReferencedProjects 选项包含被引用项目的文件。假设有下图所示的引用结构：

执行命令

nuget pack A.csproj -IncludeReferencedProjects

生成的程序包会包含项目 A,B,C,D,E,F,G中的文件。

如果被引用的项目有 nuspec 文件，则它将作为依赖项，例如 C.csproj 所在目录中有一个 C.nuspec 文件，执行以上命令后生成的程序包将包含项目 A,B,D,E 中的文件，并且有一个对 C 的依赖项。

默认情况下，NuGet 使用默认生成配置(通常是Debug)，要打包 Release 配置的文件，可执行：

nuget pack MyProject.csproj -Prop Configuration=Release

visual studio 未提供修改默认生成配置的界面，要修改默认生成配置，需要手工编辑项目文件。

在生成时创建程序包

通过添加 AfterBuild 目标，可以在生成成功时自动创建程序包。手工编辑项目文件，加入以下内容：

<Target Name="AfterBuild" Condition=" ‘$(Configuration)‘ == ‘Release‘">
    <Exec Command="nuget pack $(ProjectFileName) -Prop Configuration=Release"></Exec>
</Target>

将在生成配置为 Release 时自动调用 nuget.exe 创建程序包。

从基于约定的目录创建程序包

除了程序集，程序包中还可包含源代码，PowerShell 脚本，可执行文件，配置文件等内容。NuGet 有一个对工作目录结构的约定：

• tools。用于存放 powershell 脚本，以及可在程序包管理器控制台访问的程序。这个目录复制到目标项目后，将添加到 `$env:Path (PATH) 环境变量。
• lib。安装程序包时，此文件夹下的程序集作为引用添加到目标项目。
• content。安装程序包时，这个文件夹下的文件将复制到目标项目的根目录。
• build。安装程序包时，自动插入到 .csproj 文件。

可以把 content 目录想象成目标项目的根目录。如果要在目标项目的 /images 目录添加一个图片文件，那么应把这个图片放在程序包的 content/images 文件夹中。

创建清单

请执行以下命令从头创建一个 spec 文件

nuget spec

将生成一个 XML 格式的 .nuspec 文件。

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>MyPackageId</id>
    <version>1.0</version>
    <authors>philha</authors>
    <owners>philha</owners>
    <licenseUrl>http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE</licenseUrl>
    <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
    <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Package description</description>
    <tags>Tag1 Tag2</tags>
    <dependencies>
      <dependency id="SampleDependency" version="1.0" />
    </dependencies>
  </metadata>
</package>

将文件中的占位符改成实际的值，然后创建需要的目录并复制内容

mkdir lib
mkdir tools
mkdir content
mkdir content\controllers

copy ..\src\SomeController.cs content
copy ..\src\MyLibrary lib
copy ..\src\SomePowershellScript.ps1 tools

准备好工作目录后，执行：

nuget pack YourPackage.nuspec

来打包文件。采用这种方式创建程序包不支持标记替换功能。

创建解决方案级程序包

解决方案级程序包用于向程序包管理器控制台按照工具或额外命令，但不添加引用，内容，也不修改生成过程。例如，psake 程序包安装 powershell 脚本帮助自动化生成过程。

如果程序包在 lib, content, build 目录中都没有文件，它就是解决方案级的，被它依赖项同样不能在 lib, content, build 目录中包含文件。

已安装的解决方案级程序包在 .nuget 目录的 package.config 文件中跟踪，而不是在特定项目的的 packages.config 文件中跟踪。

NuGet 3.0.0-3.2.0 不支持解决方案级程序包，变通的方式是安装到公共项目中。

程序包约定

框架版本文件夹结构

安装程序包时，NuGet 检查项目的目标框架，然后从 lib 文件夹中选择合适的子文件夹。使用以下命名约定指示程序集安装到哪个框架：

lib\{framework name}{version}

例如，下面的文件夹结构支持四个版本

\lib
    \net11
        \MyAssembly.dll
    \net20
        \MyAssembly.dll
    \net40
        \MyAssembly.dll
    \sl40
        \MyAssembly.dll

从 NuGet 2.0 开始，内容文件和 powershell 脚本也可按照目标框架分组，规则同 lib 文件夹。

\content
    \net11
        \MyContent.txt
    \net20
        \MyContent20.txt
    \net40
    \sl40
        \MySilverlightContent.html

\tools
    init.ps1
    \net40
        install.ps1
        uninstall.ps1
    \sl40
        install.ps1
        uninstall.ps1

init.ps1 在解决方案级运行，与项目和目标框架无关，应直接放在 tools 文件夹中。

框架名称

NuGet 将文件夹名解析为 FrameworkName 对象，名称是区分大小写的，名称和版本号都可以使用缩写形式。

如果省略框架名称，则假定是 .Net Framework。例如，以下文件夹结构与上面的同义：

\lib
    \11
        \MyAssembly.dll
    \20
        \MyAssembly.dll
    \40
        \MyAssembly.dll
    \sl4
        \MyAssembly.dll

下表是有效的框架名称和缩写

框架版本无关的程序集

与框架版本无关的程序集直接放在 lib 文件夹中。

程序集版本和项目的目标框架的匹配

向项目安装具有多个程序集的程序包时，NuGet 会将程序集的框架名称同项目的目标框架进行匹配。若未找到匹配，NuGet 会排除大于项目框架版本的程序集，然后从剩余的程序集中选择最高版本。假设要把上例中的程序包安装到以 .net 3.5 为目标的项目中，实际安装的是 net20 文件夹中的程序集。

按照框架版本对程序集进行分组

NuGet 仅从一个库目录中复制文件，假设有以下目录

\lib
    \Net20
        \MyAssembly.dll (v1.0)
        \MyAssembly.Core.dll (v1.0)
    \Net40
        \MyAssembly.dll (v2.0)

安装到以 .net4 为目标的项目时，仅安装 MyAssembly.dll (v2.0)，不安装 MyAssembly.Core.dll (v1.0) 。若要安装 MyAssembly.Core.dll，要在 net40 中再包含一次。

仅从一个目录复制的规则也适用于根 lib 文件夹。有以下文件夹结构

\lib
    \MyAssembly.dll (v1.0)
    \MyAssembly.Core.dll (v1.0)
    \Net40
        \MyAssembly.dll (v2.0)

对于以 .net2.0 或 3.5 为目标的项目，NuGet 复制 MyAssembly.dll 和 MyAssembly.Core.dll。对于以 .net4.0为目标的项目，则仅复制 net40 中的 MyAssembly.dll。

在安装和卸载时自动运行 PowerShell 脚本

NuGet 按照命名约定自动运行 PowerShell 脚本：

• Init.ps1 当程序包首次安装到解决方案后运行。
  • 程序包到解决方案的其他项目时不会运行。
  • 每次打开解决方案都会运行（程序包管理器控制台窗口必须打开）。
• Install.ps1 当程序包安装到项目后运行。
  • 如果程序包安装到解决方案中的多个项目时，将为每个项目运行一次。
  • 程序包的 content 或 lib 目录存在文件时才会运行。仅在 tools 文件夹中存在文件不会运行。
  • 若 init.ps1 存在，install.ps2 在 init.ps1 之后运行。
  • [NuGet 3.x] 在使用 project.json 管理的项目中不运行。
• Uninstall.ps1 在程序包卸载后运行。
  • [NuGet 3.x] 在使用 project.json 管理的项目中不运行。
• 脚本文件应放在程序包的 tools 目录中。
• 在文件顶部加上这样一行：param($installPath, $toolsPath, $package, $project)
  • $installPath 是安装目录。
  • $toolsPath 是安装目录下的 tools 目录。
  • $package 是程序包对象的引用。
  • $project 是 EnvDTE 项目对象的引用，它表示程序包安装到的项目。init.ps1 在解决方案级运行，因此 init.ps1 中为 null。
• 编写脚本时，若要在控制台测试 $project，可设置为 $project = Get-Project。

可通过 NuGetPSVariables 程序包了解实际的输出，这个工具将信息写到日志中：

Install-Package NuGetPSVariables

NuGetPSVariables 程序包在显示日志文件后自动卸载。