.NET 散發封裝.NET distribution packaging

由於 .NET 5 (和 .NET Core) 和更新版本會在更多平臺上提供使用,因此瞭解如何封裝、命名和使用它的應用程式和程式庫,是很有用的。As .NET 5 (and .NET Core) and later versions become available on more and more platforms, it's useful to learn how to package, name, and version apps and libraries that use 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。Attempting to build .NET from source.
  • 想要變更可能會影響所產生之配置或封裝的 .NET CLI。Wanting to make changes to the .NET CLI that could impact the resulting layout or packages produced.

磁碟配置Disk layout

安裝時,.NET 會包含幾個配置檔案系統中的元件,如下所示:When installed, .NET consists of several components that are laid out as follows in the file system:

{dotnet_root}                                     (*)
├── dotnet                       (1)
├── LICENSE.txt                  (8)
├── ThirdPartyNotices.txt        (8)
├── host                                          (*)
│   └── fxr                                       (*)
│       └── <fxr version>        (2)
├── sdk                                           (*)
│   ├── <sdk version>            (3)
│   └── NuGetFallbackFolder      (4)              (*)
├── packs                                         (*)
│   ├── Microsoft.AspNetCore.App.Ref              (*)
│   │   └── <aspnetcore ref version>     (11)
│   ├── Microsoft.NETCore.App.Ref                 (*)
│   │   └── <netcore ref version>        (12)
│   ├── Microsoft.NETCore.App.Host.<rid>          (*)
│   │   └── <apphost version>            (13)
│   ├── Microsoft.WindowsDesktop.App.Ref          (*)
│   │   └── <desktop ref version>        (14)
│   └── NETStandard.Library.Ref                   (*)
│       └── <netstandard version>        (15)
├── shared                                        (*)
│   ├── Microsoft.NETCore.App                     (*)
│   │   └── <runtime version>     (5)
│   ├── Microsoft.AspNetCore.App                  (*)
│   │   └── <aspnetcore version>  (6)
│   ├── Microsoft.AspNetCore.All                  (*)
│   │   └── <aspnetcore version>  (6)
│   └── Microsoft.WindowsDesktop.App              (*)
│       └── <desktop app version> (7)
└── templates                                     (*)
│   └── <templates version>      (17)
/
├── etc/dotnet
│       └── install_location     (16)
├── 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. Hostfxr 會負責在執行 .NET 應用程式時選取適當的執行時間。The hostfxr is responsible for selecting the appropriate runtime when executing a .NET 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 程式庫和應用程式。(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 libraries and applications. SDK 包含 .NET CLI、managed 語言編譯器、MSBuild,以及相關聯的組建工作與目標、NuGet、新專案範本等等。The SDK includes the .NET 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 時。(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. 此資料夾只會在 .NET Core 3.0 之前使用。This folder is only used prior to .NET Core 3.0. 它無法從來源建立,因為它包含預建的二進位資產 nuget.orgIt can't be built from source, because it contains prebuilt binary assets from nuget.org.

共用 資料夾包含架構。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/NETCore. App/ <runtime version> 此架構包含 .net 執行時間和支援的 managed 程式庫。(5) shared/Microsoft.NETCore.App/<runtime version> This framework contains the .NET runtime and supporting managed libraries.

  • (6) shared/AspNetCore. {App、All}/ <aspnetcore version> 包含 ASP.NET Core 程式庫。(6) shared/Microsoft.AspNetCore.{App,All}/<aspnetcore version> contains the ASP.NET Core libraries. 下的程式庫 Microsoft.AspNetCore.App 是在 .net 專案中開發和支援的。The libraries under Microsoft.AspNetCore.App are developed and supported as part of the .NET project. Microsoft.AspNetCore.All 下的程式庫是超集,其中也包含第三方程式庫。The libraries under Microsoft.AspNetCore.All are a superset that also contains third-party libraries.

  • (7) 共用/Microsoft. App/ <desktop app version> 包含 Windows 桌面程式庫。(7) shared/Microsoft.Desktop.App/<desktop app version> contains the Windows desktop libraries. 這不包含在非 Windows 平臺上。This isn't included on non-Windows platforms.

  • (8) LICENSE.txt,ThirdPartyNotices.txt 分別是 .net 中使用的 .net 授權和協力廠商程式庫的授權。(8) LICENSE.txt,ThirdPartyNotices.txt are the .NET license and licenses of third-party libraries used in .NET, 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.

  • (11,12) NETCore。 ref 分別描述 .net 版本的 API 和 ASP.NET Core 的應用程式開發介面 x.y(11,12) Microsoft.NETCore.App.Ref,Microsoft.AspNetCore.App.Ref describe the API of an x.y version of .NET and ASP.NET Core respectively. 針對這些目標版本進行編譯時,會使用這些套件。These packs are used when compiling for those target versions.

  • (13) NETCore <rid>(13) Microsoft.NETCore.App.Host.<rid> 包含平臺的原生二進位檔 ridcontains a native binary for platform rid. 將 .NET 應用程式編譯為該平臺的原生二進位檔時,此二進位檔是範本。This binary is a template when compiling a .NET application into a native binary for that platform.

  • (14) WindowsDesktop 描述 x.y Windows 傳統型應用程式版本的 API。(14) Microsoft.WindowsDesktop.App.Ref describes the API of x.y version of Windows Desktop applications. 針對該目標編譯時,會使用這些檔案。These files are used when compiling for that target. 非 Windows 平臺上不會提供此資訊。This isn't provided on non-Windows platforms.

  • (15) NETStandard 描述 NETStandard x.y API。(15) NETStandard.Library.Ref describes the netstandard x.y API. 針對該目標編譯時,會使用這些檔案。These files are used when compiling for that target.

  • (16) /etc/dotnet/install_location 是包含完整路徑的檔案 {dotnet_root}(16) /etc/dotnet/install_location is a file that contains the full path for {dotnet_root}. 路徑結尾可以是分行符號。The path may end with a newline. 當根目錄為時,並不需要加入這個檔案 /usr/share/dotnetIt's not necessary to add this file when the root is /usr/share/dotnet.

  • (17) 範本 包含 SDK 所使用的範本。(17) templates contains the templates used by the SDK. 例如, dotnet new 在這裡尋找專案範本。For example, dotnet new finds project templates here.

標記為的資料夾 (*) 會由多個套件使用。The folders marked with (*) are used by multiple packages. 某些封裝格式 (例如, rpm) 需要這類資料夾的特殊處理。Some package formats (for example, rpm) require special handling of such folders. 封裝維護程式必須負責處理。The package maintainer must take care of this.

.NET 版本控制是以執行時間元件的 [major].[minor] 版本號碼為基礎。.NET 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 第三項功能版本的第二個修補程式版本。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 版本控制總覽For more information about how versioning works, see .NET 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 lists the recommended packages:

  • dotnet-sdk-[major].[minor] -安裝適用于特定執行時間的最新 sdkdotnet-sdk-[major].[minor] - Installs the latest sdk for specific runtime

    • 版本:<sdk version>Version: <sdk version>
    • 範例: dotnet-sdk-2。1Example: dotnet-sdk-2.1
    • 包含: (3) 、 (4) Contains: (3),(4)
    • 相依性 dotnet-runtime-[major].[minor]aspnetcore-runtime-[major].[minor]dotnet-targeting-pack-[major].[minor]aspnetcore-targeting-pack-[major].[minor] 、、 netstandard-targeting-pack-[netstandard_major].[netstandard_minor] dotnet-apphost-pack-[major].[minor]dotnet-templates-[major].[minor]Dependencies: dotnet-runtime-[major].[minor], aspnetcore-runtime-[major].[minor], dotnet-targeting-pack-[major].[minor], aspnetcore-targeting-pack-[major].[minor], netstandard-targeting-pack-[netstandard_major].[netstandard_minor], dotnet-apphost-pack-[major].[minor], dotnet-templates-[major].[minor]
  • aspnetcore-runtime-[major].[minor] -安裝特定的 ASP.NET Core 執行時間aspnetcore-runtime-[major].[minor] - Installs a specific ASP.NET Core runtime

    • 版本:<aspnetcore runtime version>Version: <aspnetcore runtime version>
    • 範例: aspnetcore-runtime-2。1Example: aspnetcore-runtime-2.1
    • 包含: (6) Contains: (6)
    • 相依性 dotnet-runtime-[major].[minor]Dependencies: dotnet-runtime-[major].[minor]
  • dotnet-runtime-deps-[major].[minor](選擇性) -安裝執行獨立應用程式的相依性dotnet-runtime-deps-[major].[minor] (Optional) - Installs the dependencies for running self-contained applications

    • 版本:<runtime version>Version: <runtime version>
    • 範例: dotnet-runtime-d-2。1Example: dotnet-runtime-deps-2.1
    • 相依性 散發特定 相依性Dependencies: distribution-specific dependencies
  • dotnet-runtime-[major].[minor] -安裝特定執行時間dotnet-runtime-[major].[minor] - Installs a specific runtime

    • 版本:<runtime version>Version: <runtime version>
    • 範例: dotnet-runtime-2。1Example: dotnet-runtime-2.1
    • 包含: (5) Contains: (5)
    • 相依性 dotnet-hostfxr-[major].[minor]dotnet-runtime-deps-[major].[minor]Dependencies: dotnet-hostfxr-[major].[minor], dotnet-runtime-deps-[major].[minor]
  • dotnet-hostfxr-[major].[minor] -相依性dotnet-hostfxr-[major].[minor] - dependency

    • 版本:<runtime version>Version: <runtime version>
    • 範例: dotnet-hostfxr-3。0Example: dotnet-hostfxr-3.0
    • 包含: (2) Contains: (2)
    • 相依性 dotnet-hostDependencies: dotnet-host
  • dotnet-host -相依性dotnet-host - dependency

    • 版本:<runtime version>Version: <runtime version>
    • 範例: dotnet-主機Example: dotnet-host
    • 包含: (1) 、 (8) 、 (9) 、 (10) 、 (16) Contains: (1),(8),(9),(10),(16)
  • dotnet-apphost-pack-[major].[minor] -相依性dotnet-apphost-pack-[major].[minor] - dependency

    • 版本:<runtime version>Version: <runtime version>
    • 包含: (13) Contains: (13)
  • dotnet-targeting-pack-[major].[minor] -允許以非最新執行時間為目標dotnet-targeting-pack-[major].[minor] - Allows targeting a non-latest runtime

    • 版本:<runtime version>Version: <runtime version>
    • 包含: (12) Contains: (12)
  • aspnetcore-targeting-pack-[major].[minor] -允許以非最新執行時間為目標aspnetcore-targeting-pack-[major].[minor] - Allows targeting a non-latest runtime

    • 版本:<aspnetcore runtime version>Version: <aspnetcore runtime version>
    • 包含: (11) Contains: (11)
  • netstandard-targeting-pack-[netstandard_major].[netstandard_minor] -允許以 netstandard 版本為目標netstandard-targeting-pack-[netstandard_major].[netstandard_minor] - Allows targeting a netstandard version

    • 版本:<sdk version>Version: <sdk version>
    • 包含: (15) Contains: (15)
  • dotnet-templates-[major].[minor]

    • 版本:<sdk version>Version: <sdk version>
    • 包含: (15) Contains: (15)

dotnet-runtime-deps-[major].[minor]需要瞭解 發行版本特有 的相依性。The dotnet-runtime-deps-[major].[minor] requires understanding the distro-specific dependencies. 因為發行版本組建系統可能會自動衍生此封裝,所以封裝是選擇性的,在這種情況下,這些相依性會直接加入 dotnet-runtime-[major].[minor] 封裝中。Because the distro build system may be able to derive this automatically, the package is optional, in which case these dependencies are added directly to the dotnet-runtime-[major].[minor] package.

當套件內容位於已建立版本的資料夾之下時,套件名稱會與已建立 [major].[minor] 版本的資料夾名稱相符。When package content is under a versioned folder, the package name [major].[minor] match the versioned folder name. 除了以外的所有封裝之外 netstandard-targeting-pack-[netstandard_major].[netstandard_minor] ,這也會與 .net 版本相符。For all packages, except the netstandard-targeting-pack-[netstandard_major].[netstandard_minor], this also matches with the .NET version.

套件之間的相依性應使用 等於或大於 版本需求。Dependencies between packages should use an equal or greater than version requirement. 例如, dotnet-sdk-2.2:2.2.401 需要 aspnetcore-runtime-2.2 >= 2.2.6For example, dotnet-sdk-2.2:2.2.401 requires aspnetcore-runtime-2.2 >= 2.2.6. 如此一來,使用者就可以透過根封裝升級其安裝 (例如 dnf update dotnet-sdk-2.2) 。This makes it possible for the user to upgrade their installation via a root package (for example, dnf update dotnet-sdk-2.2).

大部分的發佈都需要從來源建置的所有成品。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).

建置套件Building packages

Dotnet/來源組建存放庫提供如何建立 .net SDK 的來源 tarball 及其所有元件的指示。The dotnet/source-build repository provides instructions on how to build a source tarball of the .NET 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.