.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. 本文適用於符合下列項目的使用者: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 版本> 包含主機所使用的架構解析邏輯。(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 uses the 2.0.5 runtime when it's available. 同樣地,hostfxr 會在開發期間選取適當的 SDK。Similarly, hostfxr selects the appropriate SDK during development.

  • (3) sdk/< 版本> 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/<執行階段版本> 此架構包含 .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 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 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],且具有獨立的 [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 版是 SDK 第三個功能版本的第二個修補程式版本,其支援 2.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:

名稱Name 範例Example 使用案例:安裝...Use case: Install ... ContainsContains 相依性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 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. 針對 Preview 版本,套件版本主要必須設為零。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:

名稱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.