如何打包面向 .NET Core 的可移植 .NET 库? [英] How to package a portable .NET library targeting .NET Core?

问题描述

如何以现代通用方式打包可移植的 .NET 库?假设我有一个 AnyCPU 程序集，我希望将其提供给支持 .NET Core API 表面的任何 .NET 平台，例如 .NET Framework 4.6 和通用 Windows 平台.

How do I package a portable .NET library in a modern general-purpose way? Let's assume I have a single AnyCPU assembly that I wish to make available to any .NET platform that supports the .NET Core API surface, for example .NET Framework 4.6 and the Universal Windows 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 Framework 库?莉>
• 如何打包 .NET 库以通用 Windows 平台为目标?
• 如何打包面向 .NET Framework 和通用 Windows 平台并包含特定于平台的功能的 .NET 库?
• 如何打包面向通用 Windows 平台的多架构 .NET 库?
• 如何打包面向通用 Windows 平台并依赖于 Visual Studio 扩展 SDK 的 .NET 库?

推荐答案

这个答案建立在 用于打包面向 .NET Framework 的库的原则.首先阅读链接的答案以更好地理解以下内容.

This answer builds upon the principles used to package libraries targeting the .NET Framework. Read the linked answer first to better understand the following.

要发布可移植的 .NET 库，您需要创建一个具有以下结构的 NuGet 包:

To publish the portable .NET library, you will need to create a NuGet package with the following structure:

---lib
    ---dotnet
            MyPortableLibrary.dll
            MyPortableLibrary.pdb
            MyPortableLibrary.XML

所有三个文件都将来自发布构建配置下项目的构建输出目录.

All three files will come from your project's build output directory under the Release build configuration.

上面结构中的 dotnet 目录具有特殊含义 - 它向 NuGet 表明该目录中的文件将在所有包的依赖项都兼容的任何平台上使用.因此，您的包可自动在支持所有依赖项(例如 .NET Core)的任何 .NET 平台上使用.

The dotnet directory in the structure above has a special meaning - it indicates to NuGet that the files in the directory are to be used on any platform that all your package's dependencies are compatible with. Therefore, your package is automatically usable on any .NET platform that supports all your dependencies (e.g. .NET Core).

关键的下一步是确定依赖项列表.由于一个包管理问题，不可能简单地声明对 .NET Core 本身的依赖(.NET Core是所有 .NET 平台共享的 API 表面).相反，您必须手动确定每个 .NET Core 组件依赖项并将其添加到 nuspec 文件中.

The crucial next step is to determine the list of dependencies. Due to a package management issue it is not possible to simply declare a dependency on .NET Core itself (.NET Core is the API surface shared by all the .NET platforms). Instead, you must manually determine each .NET Core component dependency and add it to the nuspec file.

.NET Core 包的依赖检测过程包括两个步骤:

The dependency detection process for .NET Core packages consists of two steps:

1. 确定您的库引用的 .NET Core 程序集.
2. 确定包含这些程序集的 NuGet 包.

Visual Studio 不提供您需要的信息.相反，您需要构建库并检查生成的 DLL 文件.以下 PowerShell 脚本将显示 .NET 程序集的引用:

Visual Studio does not provide the information you need. Instead, you need to build your library and inspect the resulting DLL file. The following PowerShell script will display the references of a .NET assembly:

Get-ChildItem MyPortableLibrary.dll | % { [Reflection.Assembly]::LoadFile($_.FullName).GetReferencedAssemblies() | % { $_.Name + ".dll" } }

此命令的输出将是程序集名称列表，例如:

The output of this command will be a list of assembly names, for example:

System.Runtime.dll
System.Resources.ResourceManager.dll
System.Numerics.Vectors.dll

获得列表后，打开项目目录中的 project.lock.json 文件.此文件包含有关项目使用的所有 NuGet 包的信息.在其他数据中，您会发现各种 JSON 块，例如:

Once you have obtained the list, open the project.lock.json file in your project directory. This file contains information about all NuGet packages used by your project. You will find, among other data, various blocks of JSON such as the following:

"System.Numerics.Vectors/4.1.0": {
    "dependencies": {
        "System.Globalization": "[4.0.10, )",
        "System.Resources.ResourceManager": "[4.0.0, )",
        "System.Runtime": "[4.0.20, )",
        "System.Runtime.Extensions": "[4.0.10, )"
    },
    "frameworkAssemblies": [
        "mscorlib",
        "System.Numerics"
    ],
    "compile": {
        "ref/net46/System.Numerics.Vectors.dll": {}
    },
    "runtime": {
        "lib/net46/System.Numerics.Vectors.dll": {}
    }
},

此 JSON 块表示编译"下列出的程序集文件由顶级值(System.Numerics.Vectors 版本 4.1.0)中列出的包提供.使用此信息将每个引用的程序集映射到 NuGet 包.请注意，虽然包和程序集名称通常相同，但情况并非总是如此！

This block of JSON indicates that the assembly files listed under "compile" are provided by the package listed in the top level value (System.Numerics.Vectors version 4.1.0). Use this information to map every referenced assembly to a NuGet package. Note that while the package and assembly names are often the same, this is not always the case!

对于任何不属于 .NET Core 的 NuGet 包，您可以跳过上述过程，因为您已经知道您依赖的确切包.此处描述的依赖项检测逻辑仅是必需的，因为由于上面链接的问题，您无法直接在 .NET Core(Microsoft.NETCore 包)上声明依赖项.

For any NuGet packages that are not part of .NET Core, you can skip the above process as you already know the exact package you have a dependency on. The dependency detection logic described here is only required because you cannot declare a dependency directly on .NET Core (the Microsoft.NETCore package) due to the issue linked above.

现在根据以下示例简单地列出 nuspec 文件中的所有依赖项:

Now simply list all the dependencies in your nuspec file, based on the following example:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata minClientVersion="3.2">
        <id>Example.MyPortableLibrary</id>
        <version>1.0.0</version>
        <authors>Firstname Lastname</authors>
        <description>Example of a portable library with NuGet package dependencies.</description>
        <dependencies>
            <dependency id="System.Numerics.Vectors" version="4.1.0" />
            <dependency id="System.Resources.ResourceManager" version="4.0.0" />
            <dependency id="System.Runtime" version="4.0.20" />
        </dependencies>
    </metadata>
    <files>
        <file src="..inReleaseMyPortableLibrary.*" target="libdotnet" />
    </files>
</package>

就是这样！生成的包可在任何兼容的 .NET 平台上使用，例如 .NET Framework 4.6 或通用 Windows 平台.请记住在创建 NuGet 包之前使用 Release 配置构建您的解决方案.

That's it! The resulting package is usable on any compatible .NET platform, such as .NET Framework 4.6 or Universal Windows Platform. Remember to build your solution using the Release configuration before creating the NuGet package.

一个示例库和相关的打包文件在 GitHub 上提供.这个答案对应的解决方案是 PortableLibrary.

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

参考Lucian Wischik 的博客，深入了解在此类 NuGet 包上运行的逻辑.

Refer to Lucian Wischik's blog for a deeper dive into the logic that operates on such NuGet packages.

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