.NET Core 發佈封裝.NET Core distribution packaging

隨著 .NET Core 可在越來越多的平台上使用,了解如何封裝、命名和建立 .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.

磁碟配置Disk layout

安裝時,.NET Core 包含在檔案系統中進行如下配置的數個元件:When installed, .NET Core consists of several components that are layed 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)
│       └── dotnet.1.gz          (9)
        └── 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 is 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 are installed side-by-side.

  • (2) host/fxr/<fxr 版本> 包含主機所使用的架構解析邏輯。(2) host/fxr/<fxr version> contains the framework resolution logic used by the host. 主機會使用已安裝的最新 hostfxr。The host uses the latest hostfxr that is installed. hostfxr 負責在執行 .NET Core 應用程式時選取適當的執行階段。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 will use the 2.0.5 runtime when it is available. 同樣地,hostfxr 會在開發期間選取適當的 SDK。Similarly, hostfxr selects the appropriate SDK during development.

  • (3) sdk/<SDK 版本> SDK (也稱為「工具」) 是一組受控工具,可用來撰寫與建置 .NET Core 程式庫和應用程式。(3) sdk/<sdk version> The SDK (also known as "the tooling") is a set of managed tools that can be used to write and build .NET Core libraries and applications. SDK 包含 CLI、Roslyn 編譯器、MSBuild,以及相關聯的建置工作與目標、NuGet 及新的專案範本等。The SDK includes the CLI, the Roslyn compiler, MSBuild, and associated build tasks and targets, NuGet, new project templates, etc.

  • (4) sdk/NuGetFallbackFolder 包含 SDK 在 dotnet restore 步驟期間所使用的 NuGet 套件快取。(4) sdk/NuGetFallbackFolder contains a cache of NuGet packages used by an SDK during the dotnet restore step.

共用資料夾包含架構。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/<執行階段版本> 此架構包含 .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 版本> 包含 ASP.NET Core 程式庫。(6,7) shared/Microsoft.AspNetCore.{App,All}/<aspnetcore version> contains the ASP.NET Core libraries. 在 .NET Core 專案期間,開發並支援 Microsoft.AspNetCore.App 下的程式庫。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 which also contains 3rd 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.

  • (9,10) dotnet.1.gz, dotnet dotnet.1.gz 是 dotnet 手冊頁。(9,10) dotnet.1.gz, dotnet dotnet.1.gz is the dotnet man page. dotnet 是 dotnet host(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],並且具有合併 SDK 功能及修補程式語意的獨立 [patch]The SDK version uses the same [major].[minor] and has an independent [patch] which 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 a the 2nd patch release of the 3rd feature release of the SDK that supports the 2.2 runtime.

部分套件的名稱包含版本號碼部分。Some of the packages include part of the version number in their name. 這可讓使用者安裝特定版本。This allows the end-user to install a specific version. 版本的其餘部分不會納入版本名稱中。The remainder of the version is not included in the version name. 這可讓 OS 套件管理員更新套件 (例如自動安裝安全性修正)。This allows the OS package manager to update the packages (e.g. automatically installing security fixes).

下列各表顯示建議的套件。The following tables shows the recommended packages.

名稱Name 範例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 版本><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 版本><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 版本><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>
dotnet-runtime-[major].[minor]dotnet-runtime-[major].[minor] dotnet-runtime-2.1dotnet-runtime-2.1 特定執行階段Specific runtime (5)(5) host-fxr:<執行階段版本>+host-fxr:<runtime version>+ <執行階段版本><runtime version>
dotnet-host-fxrdotnet-host-fxr dotnet-host-fxrdotnet-host-fxr dependencydependency (2)(2) host:<執行階段版本>+host:<runtime version>+ <執行階段版本><runtime version>
dotnet-hostdotnet-host dotnet-hostdotnet-host dependencydependency (1),(8),(9),(10)(1),(8),(9),(10) <執行階段版本><runtime version>

大部分的發佈都需要從來源建置的所有成品。Most distributions require all artifacts to be built from source. 這會對套件造成某個影響:This has some impact on the packages:

  • 無法從來源輕鬆地建置 shared/Microsoft.AspNetCore.All 下的協力廠商程式庫。The 3rd party libraries under shared/Microsoft.AspNetCore.All cannot 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, ...).

預覽版本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 版本。Preview releases may be provided using the dotnet-sdk-[major].[minor].[sdk feat]xx, aspnetcore-runtime-[major].[minor], dotnet-runtime-[major].[minor] packages. 針對 Preview 版本,套件版本主要必須設為零。For preview releases, the package version major must be set to zero. 因此,最終版本將會安裝為套件的升級。This way, the final release will be installed as an upgrade of the package.

修補程式套件Patch packages

因為套件的修補程式版本可能會導致重大變更,所以套件維護人員可能想要提供「修補程式套件」。Since a patch version of a packages may cause a breaking change, a package maintainer may want to provide patch packages. 這些套件允許安裝不會自動升級的特定修補程式版本。These packages allows to install a specific patch version which is not automatically upgraded. 只有在極少數的情況下才應該使用修補程式套件,因為它們不會與 (安全性) 修正程式一起自動升級。Patch packages should only be used in rare circumstances as they will not be upgraded with (security) fixes.

下表顯示建議的套件和修補程式套件The following table shows the recommended packages and patch packages.

名稱Name 範例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:<執行階段版本>+host-fxr:<runtime version>+
dotnet-host-fxrdotnet-host-fxr dotnet-host-fxrdotnet-host-fxr (2)(2) host:<執行階段版本>+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. source-build 存放庫的輸出會比對本文第一節中所述的配置。The output of the source-build repository matches the layout described in the first section of this article.