.NET Core 分发打包.NET Core distribution packaging

由于 .NET Core 现已可用于更多平台,因此了解如何为其打包、命名并进行版本控制将很有用。As .NET Core becomes available on more and more platforms, it's useful to learn how to package, name, and version it. 这样,无论用户选择在哪里运行 .NET,包维护人员均可以帮助确保获得一致的体验。This way, package maintainers can help ensure a consistent experience no matter where users choose to run .NET. 本文对以下用户非常有用:This article is useful for users that are:

  • 尝试从源生成 .NET Core。Attempting to build .NET Core from source.
  • 想要更改 .NET Core CLI,但更改可能会影响生成的布局或包。Wanting to make changes to the .NET Core CLI that could impact the resulting layout or packages produced.

磁盘布局Disk layout

安装时,.NET Core 包含一些组件,这些组件在文件系统中排列如下:When installed, .NET Core consists of several components that are laid out as follows in the filesystem:

.
├── dotnet                       (1)
├── LICENSE.txt                  (8)
├── ThirdPartyNotices.txt        (8)
├── host
│   └── fxr
│       └── <fxr version>        (2)
├── sdk
│   ├── <sdk version>            (3)
│   └── NuGetFallbackFolder      (4)
└── shared
    ├── Microsoft.NETCore.App
    │   └── <runtime version>    (5)
    └── Microsoft.AspNetCore.App
        └── <aspnetcore version> (6)
    └── Microsoft.AspNetCore.All
        └── <aspnetcore version> (7)
/
├─usr/share/man/man1
│       └── dotnet.1.gz          (9)
└─usr/bin
        └── dotnet               (10)
  • (1) dotnet 主机(也称为“muxer”)有两个不同角色:激活运行时以启动应用程序,及激活 SDK 以向其分派命令。(1) dotnet The host (also known as the "muxer") has two distinct roles: activate a runtime to launch an application, and activate an SDK to dispatch commands to it. 主机是本机可执行文件 (dotnet.exe)。The host is a native executable (dotnet.exe).

主机只有一个,不过大部分的其他组件都在带有版本的目录中(2、3、5 和 6)。While there's a single host, most of the other components are in versioned directories (2,3,5,6). 这意味着系统上可存在多个版本,因为它们是并排安装的。This means multiple versions can be present on the system since they're installed side by side.

  • (2) host/fxr/<fxr version> 包含了主机所使用的框架解析逻辑。(2) host/fxr/<fxr version> contains the framework resolution logic used by the host. 主机采用已安装的最新 hostfxr。The host uses the latest hostfxr that is installed. 在执行 .NET Core 应用程序时,hostfxr 负责选择合适的运行时。The hostfxr is responsible for selecting the appropriate runtime when executing a .NET Core application. 例如,为 .NET Core 2.0.0 生成的应用程序会使用 2.0.5 运行时(如果可用)。For example, an application built for .NET Core 2.0.0 uses the 2.0.5 runtime when it's available. 同样,hostfxr 在开发期间也会选择适当的 SDK。Similarly, hostfxr selects the appropriate SDK during development.

  • (3) sdk/<sdk version> SDK(也称为“工具”)是一组托管工具,可用于编写和生成 .NET Core 库和应用程序。(3) sdk/<sdk version> The SDK (also known as "the tooling") is a set of managed tools that are used to write and build .NET Core libraries and applications. SDK 包括 .NET Core 命令行接口 (CLI)、托管的语言编译器、MSBuild 及相关生成任务和目标、NuGet、新项目模板等。The SDK includes the .NET Core Command-line interface (CLI), the managed languages compilers, MSBuild, and associated build tasks and targets, NuGet, new project templates, and so on.

  • (4) sdk/NuGetFallbackFolder 包含 SDK 在还原操作期间使用的 NuGet 包的缓存,例如在运行 dotnet restoredotnet build /t:Restore 时。(4) sdk/NuGetFallbackFolder contains a cache of NuGet packages used by an SDK during the restore operation, such as when running dotnet restore or dotnet build /t:Restore.

“共享”文件夹包含框架。The shared folder contains frameworks. 共享框架提供一组位于中心位置的库,从而让不同的应用程序使用。A shared framework provides a set of libraries at a central location so they can be used by different applications.

  • (5) shared/Microsoft.NETCore.App/<runtime version> 此框架包含.NET Core 运行时和支持托管库。(5) shared/Microsoft.NETCore.App/<runtime version> This framework contains the .NET Core runtime and supporting managed libraries.

  • (6,7) shared/Microsoft.AspNetCore.{App,All}/<aspnetcore version> 包含 ASP.NET Core 库。(6,7) shared/Microsoft.AspNetCore.{App,All}/<aspnetcore version> contains the ASP.NET Core libraries. 已开发且支持 Microsoft.AspNetCore.App 下的库(作为 .NET Core 项目的一部分)。The libraries under Microsoft.AspNetCore.App are developed and supported as part of the .NET Core project. Microsoft.AspNetCore.All 下的库是一个超集,其中还包含第三方库。The libraries under Microsoft.AspNetCore.All are a superset that also contains third-party libraries.

  • (8) LICENSE.txt,ThirdPartyNotices.txt 分别是 .NET Core 许可证和 .NET Core 中使用的第三方库的许可证。(8) LICENSE.txt,ThirdPartyNotices.txt are the .NET Core license and licenses of third-party libraries used in .NET Core, respectively.

  • (9,10) dotnet.1.gz, dotnet dotnet.1.gz 是 dotnet 手册页。(9,10) dotnet.1.gz, dotnet dotnet.1.gz is the dotnet manual page. dotnet 是指向 dotnet 主机 (1) 的符号链接。dotnet is a symlink to the dotnet host(1). 这些文件安装在已知位置用于系统集成。These files are installed at well known locations for system integration.

.NET Core 版本控制基于运行时组件 [major].[minor] 版本号。.NET Core versioning is based on the runtime component [major].[minor] version numbers. SDK 版本采用相同的 [major].[minor],并有一个独立的 [patch],它为 SDK 合并了功能和修补语义。The SDK version uses the same [major].[minor] and has an independent [patch] that combines feature and patch semantics for the SDK. 例如:SDK 版本 2.2.302 是支持 2.2 运行时的 SDK 的第 3 个功能版本的第 2 个补丁版本。For example: SDK version 2.2.302 is the second patch release of the third feature release of the SDK that supports the 2.2 runtime. 有关版本控制的工作原理的详细信息,请参阅 .NET Core 版本控制概述For more information about how versioning works, see .NET Core versioning overview.

一些包在自己的名称中就包含一部分版本号。Some of the packages include part of the version number in their name. 这允许你安装特定版本。This allows you to install a specific version. 版本名称中不包含版本的剩余部分。The rest of the version isn't included in the version name. 这允许 OS 包管理器更新这些包(例如,自动安装安全修补程序)。This allows the OS package manager to update the packages (for example, automatically installing security fixes). 支持的包管理器特定于 Linux。Supported package managers are Linux specific.

下表显示了推荐的包:The following table shows the recommended packages:

nameName 示例Example 用例:安装 ...Use case: Install ... 包含Contains 依赖项Dependencies 版本Version
dotnet-sdk-[major]dotnet-sdk-[major] dotnet-sdk-2dotnet-sdk-2 运行时主版本的最新 SDKLatest sdk for runtime major dotnet-sdk-[major].[latestminor]dotnet-sdk-[major].[latestminor] <sdk version><sdk version>
dotnet-sdk-[major].[minor]dotnet-sdk-[major].[minor] dotnet-sdk-2.1dotnet-sdk-2.1 特定运行时的最新 SDKLatest sdk for specific runtime dotnet-sdk-[major].[minor].[latest sdk feat]xxdotnet-sdk-[major].[minor].[latest sdk feat]xx <sdk version><sdk version>
dotnet-sdk-[major].[minor].[sdk feat]xxdotnet-sdk-[major].[minor].[sdk feat]xx dotnet-sdk-2.1.3xxdotnet-sdk-2.1.3xx 特定 SDK 的功能版本Specific sdk feature release (3),(4)(3),(4) aspnetcore-runtime-[major].[minor]aspnetcore-runtime-[major].[minor] <sdk version><sdk version>
aspnetcore-runtime-[major].[minor]aspnetcore-runtime-[major].[minor] aspnetcore-runtime-2.1aspnetcore-runtime-2.1 特定 ASP.NET Core 运行时Specific ASP.NET Core runtime (6),[(7)](6),[(7)] dotnet-runtime-[major].[minor]dotnet-runtime-[major].[minor] <runtime version><runtime version>
dotnet-runtime-[major].[minor]dotnet-runtime-[major].[minor] dotnet-runtime-2.1dotnet-runtime-2.1 特定运行时Specific runtime (5)(5) host-fxr:<runtime version>+host-fxr:<runtime version>+ <runtime version><runtime version>
dotnet-host-fxrdotnet-host-fxr dotnet-host-fxrdotnet-host-fxr dependencydependency (2)(2) host:<runtime version>+host:<runtime version>+ <runtime version><runtime version>
dotnet-hostdotnet-host dotnet-hostdotnet-host dependencydependency (1),(8),(9),(10)(1),(8),(9),(10) <runtime version><runtime version>

大多数分发都需要从源中构建所有项目。Most distributions require all artifacts to be built from source. 这对包有一些影响:This has some impact on the packages:

  • 不能简单地从源生成 shared/Microsoft.AspNetCore.All 下的第三方库。The third-party libraries under shared/Microsoft.AspNetCore.All can't be easily built from source. 因此 aspnetcore-runtime 包中省略了该文件夹。So that folder is omitted from the aspnetcore-runtime package.

  • 使用 nuget.org 中的二进制项目填充了 NuGetFallbackFolderThe NuGetFallbackFolder is populated using binary artifacts from nuget.org. 它应保留为空。It should remain empty.

多个 dotnet-sdk 包可能会为 NuGetFallbackFolder 提供同样的文件。Multiple dotnet-sdk packages may provide the same files for the NuGetFallbackFolder. 若要避免包管理器出现问题,这些文件应完全相同(包括校验和、修改日期等等)。To avoid issues with the package manager, these files should be identical (checksum, modification date, and so on).

预览版Preview versions

包维护人员可以决定提供共享框架和 SDK 的预览版。Package maintainers may decide to provide preview versions of the shared framework and SDK. 可以使用 dotnet-sdk-[major].[minor].[sdk feat]xxaspnetcore-runtime-[major].[minor]dotnet-runtime-[major].[minor] 包提供预览版。Preview releases may be provided using the dotnet-sdk-[major].[minor].[sdk feat]xx, aspnetcore-runtime-[major].[minor], or dotnet-runtime-[major].[minor] packages. 对于预览版,包的主版本号必须设为 0。For preview releases, the package version major must be set to zero. 这样最终版本将被安装为此包的升级版。This way, the final release is installed as an upgrade of the package.

修补程序包Patch packages

由于包的补丁版本可能会带来重大更改,包维护人员可能要提供_补丁包_。Since a patch version of a package may cause a breaking change, a package maintainer may want to provide patch packages. 这些包允许安装非自动升级的特定补丁版本。These packages allow you to install a specific patch version that isn't automatically upgraded. 因为这些补丁包不会随(安全)修补程序升级,所以只应在极少数情况下使用。Only use patch packages in rare circumstances as they aren't upgraded with (security) fixes.

下表显示了推荐的包和补丁包The following table shows the recommended packages and patch packages:

nameName 示例Example 包含Contains 依赖项Dependencies
dotnet-sdk-[major]dotnet-sdk-[major] dotnet-sdk-2dotnet-sdk-2 dotnet-sdk-[major].[latest sdk minor]dotnet-sdk-[major].[latest sdk minor]
dotnet-sdk-[major].[minor]dotnet-sdk-[major].[minor] dotnet-sdk-2.1dotnet-sdk-2.1 dotnet-sdk-[major].[minor].[latest sdk feat]xxdotnet-sdk-[major].[minor].[latest sdk feat]xx
dotnet-sdk-[major].[minor].[sdk feat]xxdotnet-sdk-[major].[minor].[sdk feat]xx dotnet-sdk-2.1.3xxdotnet-sdk-2.1.3xx dotnet-sdk-[major].[minor].[latest sdk patch]dotnet-sdk-[major].[minor].[latest sdk patch]
dotnet-sdk-[major].[minor].[patch]dotnet-sdk-[major].[minor].[patch] dotnet-sdk-2.1.300dotnet-sdk-2.1.300 (3),(4)(3),(4) aspnetcore-runtime-[major].[minor].[sdk runtime patch]aspnetcore-runtime-[major].[minor].[sdk runtime patch]
aspnetcore-runtime-[major].[minor]aspnetcore-runtime-[major].[minor] aspnetcore-runtime-2.1aspnetcore-runtime-2.1 aspnetcore-runtime-[major].[minor].[latest runtime patch]aspnetcore-runtime-[major].[minor].[latest runtime patch]
aspnetcore-runtime-[major].[minor].[patch]aspnetcore-runtime-[major].[minor].[patch] aspnetcore-runtime-2.1.0aspnetcore-runtime-2.1.0 (6),[(7)](6),[(7)] dotnet-runtime-[major].[minor].[patch]dotnet-runtime-[major].[minor].[patch]
dotnet-runtime-[major].[minor]dotnet-runtime-[major].[minor] dotnet-runtime-2.1dotnet-runtime-2.1 dotnet-runtime-[major].[minor].[latest runtime patch]dotnet-runtime-[major].[minor].[latest runtime patch]
dotnet-runtime-[major].[minor].[patch]dotnet-runtime-[major].[minor].[patch] dotnet-runtime-2.1.0dotnet-runtime-2.1.0 (5)(5) host-fxr:<runtime version>+host-fxr:<runtime version>+
dotnet-host-fxrdotnet-host-fxr dotnet-host-fxrdotnet-host-fxr (2)(2) host:<runtime version>+host:<runtime version>+
dotnet-hostdotnet-host dotnet-hostdotnet-host (1),(8),(9),(10)(1),(8),(9),(10)

除了使用修补程序包,还可以使用包管理器将包固定为特定版本。An alternative to using patch packages is pinning the packages to a specific version using the package manager. 要避免影响其他应用程序/用户,例如可能会在容器中生成并部署的应用程序。To avoid affecting other applications/users, such applications can be built and deployed in a container.

生成包Building packages

dotnet/source-build 存储库中说明了如何生成 .NET Core SDK 的源 tarball 及其所有组件。The dotnet/source-build repository provides instructions on how to build a source tarball of the .NET Core SDK and all its components. 源版本存储库中的输出内容符合本文第一部分中所描述的布局。The output of the source-build repository matches the layout described in the first section of this article.