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

问题描述

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

这是一系列问题和答案记录了我对现代NuGet软件包创作这一主题的发现，尤其着重于NuGet 3引入的更改。您可能也对一些相关问题感兴趣：

• 如何打包面向通用Windows平台的.NET库？




• 如何打包面向.NE的.NET库T Framework和Universal Windows Platform并包括特定于平台的功能？


• 如何打包针对通用Windows平台的多体系结构.NET库？


• 如何打包面向通用Windows平台并依赖Visual Studio扩展SDK的.NET库？

解决方案

您将要创建并发布包含以下内容的NuGet包：

• 包含代码（.dll）的程序集。


• 调试符号文件（.pdb）。


• XML文档文件（。 xml），前提是您已在项目设置中启用了它。





虽然发布代码的原因很明显，但另外两个值得扩展：






• 调试符号文件使运行时可以用代码的行号填充堆栈跟踪，并且还可以向附加的调试器提供其他信息。在NuGet程序包中包含此文件是增强与库关联的故障排除体验的非常简单的方法。


• XML文档文件来显示工具提示，这些提示为您的库用户提供有关方法及其参数的文档。这样可以避免引用外部文档，从而提高了库的可用性。






NuGet软件包本质上是一个zip。文件以及您的内容以及一些元数据。要发布此.NET库，您将需要创建一个具有以下结构的包（省略元数据）：

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

简而言之，将软件包安装到.NET Framework 4.6项目中时，lib exactlynet46中的所有内容都将使用。这三个文件都将来自项目的版本输出目录（在Release版本配置下）。





创建这样的NuGet包的最简单方法是使用NuGet命令行可执行文件。在解决方案中创建一个目录（例如MyLibrary\NuGet），然后将 nuget.exe 复制到该目录中。要定义库的NuGet包的结构，请使用以下模板作为模板，在同一目录（例如MyLibrary.nuspec）中创建一个.nuspec文件：

 <？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>名字姓氏< / authors> 
< description>是简单的.NET Framework 4.6库的示例。 
< dependencies> 
< dependency id = Newtonsoft.Json version = 8.0.1 /> 
< / dependencies> 
< / metadata> 
< files> 
< file src = .. \bin\Release\MyLibrary。* target = lib\net46 /> 
< / files> 
< / package> 
  

请确保将nuget.exe和.nuspec文件的生成操作设置为None，以避免





如果您的项目是根据标准Visual Studio项目模板配置的，则项目的所有三个相关输出（MyLibrary.dll， MyLibrary.xml和MyLibrary.pdb）将出现在bin\Release目录中，示例中的通配符模式会将它们全部复制到NuGet包中的相应位置。





依赖项列表应镜像项目目录中的packages.config文件。如果您的库不依赖于其他NuGet软件包，则可以简单地忽略< dependencies> 元素。








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





我发现使用a PowerShell脚本启动NuGet软件包的生成，尤其是在您需要对内容进行预处理的情况下（尤其是在更复杂的项目中）。这是一个PowerShell脚本示例，该脚本将在同一目录中使用nuget.exe为同一目录中的所有.nuspec文件创建软件包：

 ＃删除任何现有输出。 
 Remove-Item * .nupkg 
 
＃为该目录中存在的任何nuspec文件创建新软件包。 
 Foreach（$（获取（* .nuspec）中的$ nuspec））
 {
 .\NuGet.exe包 $ nuspec 
} 
  

如果将其包含在项目中，请确保将PowerShell脚本的build操作设置为None，以避免不必要的操作





示例库和相关打包文件是可在GitHub上使用。与此答案对应的解决方案是SimpleNetFrameworkLibrary。




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.

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:

• How to package a .NET library targeting the Universal Windows Platform?
• How to package a portable .NET library targeting .NET Core?
• How to package a .NET library targeting .NET Framework and Universal Windows Platform and include platform-specific functionality?
• How to package a multi-architecture .NET library that targets the Universal Windows Platform?
• How to package a .NET library that targets the Universal Windows Platform and depends on Visual Studio extension SDKs?

解决方案

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

• The assembly containing your code (.dll).
• The debug symbol file (.pdb).
• The XML documentation file (.xml), assuming you have enabled it in project settings.

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

• 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.

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

Simply put, everything in lib\net46 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.

The easiest way to create such a NuGet package is using the NuGet command line executable. Create a directory in your solution (e.g. MyLibrary\NuGet) 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="..\bin\Release\MyLibrary.*" target="lib\net46" />
    </files>
</package>

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.

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 bin\Release directory and the wildcard pattern in the example will copy all of them to the appropriate locations in the NuGet package.

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.

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.

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"
}

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.

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

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