如何打包 .NET Framework 库? [英] How to package a .NET Framework library?

问题描述

如何以现代通用方式打包 .NET 库以通过 NuGet 发布?假设我希望在 .NET Framework 4.6 平台上提供一个 AnyCPU 程序集.

How do I package a .NET library in a modern general-purpose way for publishing via NuGet? Let's assume I have a single AnyCPU assembly that I wish to make available on the .NET Framework 4.6 platform.

这是一系列问题和答案，记录了我对现代 NuGet 包创作主题的发现，特别关注 NuGet 3 引入的更改.您可能还对一些相关问题感兴趣:

This is a series of questions and answers that document my findings on the topic of modern NuGet package authoring, focusing especially on the changes introduced with NuGet 3. You may also be interested in some related questions:

• 如何打包 .NET 库面向通用 Windows 平台?
• 如何打包可移植的 .NET 库定位.NET 核心?
• 如何打包面向 .NET Framework 和通用 Windows 平台并包含特定于平台的功能的 .NET 库?
• 如何打包面向通用 Windows 平台的多架构 .NET 库?
• 如何打包一个面向通用 Windows 平台并依赖于 Visual Studio 扩展 SDK 的 .NET 库?

推荐答案

您需要创建并发布一个包含以下内容的 NuGet 包:

You will want to create and publish a NuGet package with the following contents:

• 包含您的代码 (.dll) 的程序集.
• 调试符号文件 (.pdb).
• XML 文档文件 (.xml)，假设您已在项目设置中启用它.

虽然发布代码的原因很明显，但其他两个值得扩展:

While the reason for publishing your code is obvious, the other two are worth expanding on:

• 调试符号文件使运行时能够使用代码的行号填充堆栈跟踪，并且还可以为附加的调试器提供其他信息.在 NuGet 包中包含此文件是增强与库相关的故障排除体验的一种非常简单的方法.
• Visual Studio 使用 XML 文档文件来显示提供有关方法的文档的工具提示以及他们对图书馆用户的争论.这避免了引用外部文档，从而提高了库的可用性.

• The debug symbol file enables the runtime to populate stack traces with the line numbers of your code and may also provide additional information to an attached debugger. Including this file in the NuGet package is a very simple way to enhance the troubleshooting experience associated with your library.
• The XML documentation file is used by Visual Studio to display tooltips that provide documentation about methods and their arguments to users of your library. This avoids having to reference an external piece of documentation, increasing usability of your library.

NuGet 包本质上是一个包含您的内容和一些元数据的 zip 文件.要发布此 .NET 库，您需要创建一个具有以下结构的包(元数据省略):

A NuGet package is, in essence, a zip file with your content plus some metadata. To publish this .NET Library, you will need to create a package with the following structure (metadata omitted):

---lib
    ---net46
            MyLibrary.dll
            MyLibrary.pdb
            MyLibrary.XML

简单地说，当软件包安装到 .NET Framework 4.6 项目中时，将使用 lib et46 中的所有内容，而这正是您所需要的.所有三个文件都将来自您的项目在 Release 构建配置下的构建输出目录.

Simply put, everything in lib et46 will be used when the package is installed into a .NET Framework 4.6 project and that's exactly what you need. All three files will come from your project's build output directory under the Release build configuration.

创建此类 NuGet 包的最简单方法是使用 NuGet 命令行可执行文件.在您的解决方案中创建一个目录(例如 MyLibraryNuGet)并将 nuget.exe 复制到此目录中.要定义库的 NuGet 包的结构，请在同一目录中创建一个 .nuspec 文件(例如 MyLibrary.nuspec)，使用以下内容作为模板:

The easiest way to create such a NuGet package is using the NuGet command line executable. Create a directory in your solution (e.g. MyLibraryNuGet) and copy nuget.exe into this directory. To define the structure of your library's NuGet package, create a .nuspec file in the same directory (e.g. MyLibrary.nuspec), using the following as a template:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata minClientVersion="3.2">
        <id>Example.MyLibrary</id>
        <version>1.0.0</version>
        <authors>Firstname Lastname</authors>
        <description>Example of a simple .NET Framework 4.6 library.</description>
        <dependencies>
            <dependency id="Newtonsoft.Json" version="8.0.1" />
        </dependencies>
    </metadata>
    <files>
        <file src="..inReleaseMyLibrary.*" target="lib
et46" />
    </files>
</package>

确保将 nuget.exe 和 .nuspec 文件的构建操作设置为 None，以避免它们被构建过程不必要地触及.

Make sure to set the build action of nuget.exe and the .nuspec file to None, to avoid them being needlessly touched by the build process.

如果您的项目是根据标准 Visual Studio 项目模板配置的，则项目的所有三个相关输出(MyLibrary.dll、MyLibrary.xml 和 MyLibrary.pdb)都将出现在 binRelease 目录和通配符模式中在示例中会将它们全部复制到 NuGet 包中的适当位置.

If your project is configured according to the standard Visual Studio project templates, all three relevant outputs of your project (MyLibrary.dll, MyLibrary.xml and MyLibrary.pdb) will be present in the binRelease directory and the wildcard pattern in the example will copy all of them to the appropriate locations in the NuGet package.

依赖项列表应反映项目目录中的 packages.config 文件.如果你的库不依赖于其他 NuGet 包，你可以简单地省略 <dependencies> 元素.

The list of dependencies should mirror the packages.config file in your project directory. If your library has no dependencies on other NuGet packages, you can simply omit the <dependencies> element.

在继续之前使用发布配置构建您的解决方案.

Build your solution using the Release configuration before proceeding.

您可以使用命令 nuget.exe pack MyLibrary.nuspec 创建包.这将生成一个以 .nuspec 文件中指定的 ID 命名的包，例如Example.MyLibrary.1.0.0.nupkg.您可以将此文件上传到您选择的 NuGet 包存储库，然后像使用任何其他 NuGet 包一样直接继续使用它.

You can create the package using the command nuget.exe pack MyLibrary.nuspec. This will generate a package named with the ID specified in the .nuspec file, e.g. Example.MyLibrary.1.0.0.nupkg. You can upload this file to your NuGet package repository of choice and proceed directly to using it as you would any other NuGet package.

我发现使用 PowerShell 脚本启动 NuGet 包生成是有益的，尤其是当您需要对内容执行预处理时，更复杂的项目通常会出现这种情况.下面是一个 PowerShell 脚本示例，它将使用同一目录中的 nuget.exe 为同一目录中的所有 .nuspec 文件创建包:

I find that it is beneficial to use a PowerShell script to kick off NuGet package generation, especially if you need to perform pre-processing of the contents, as is often the case with more complex projects. Here is an example of a PowerShell script that will use nuget.exe in the same directory to create packages for all .nuspec files in the same directory:

# Delete any existing output.
Remove-Item *.nupkg

# Create new packages for any nuspec files that exist in this directory.
Foreach ($nuspec in $(Get-Item *.nuspec))
{
    .NuGet.exe pack "$nuspec"
}

如果您将它包含在您的项目中，请确保将 PowerShell 脚本的构建操作设置为无"，以避免它被构建过程不必要地触及.

If you include it in your project, make sure to set the build action of the PowerShell script to None, to avoid it being needlessly touched by the build process.

示例库和相关打包文件可在 GitHub 上获得.这个答案对应的解决方案是 SimpleNetFrameworkLibrary.

A sample library and the relevant packaging files are available on GitHub. The solution corresponding to this answer is SimpleNetFrameworkLibrary.

这篇关于如何打包 .NET Framework 库?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！