共用方式為

.NET 發佈封裝 (部分機器翻譯)

  • 發行項

隨著 .NET 5 (與 .NET Core) 和更新版本在愈來愈多平台上推出，了解如何封裝、命名和設定應用程式及其程式庫的版本會很有幫助。 如此一來，套件維護人員可以協助確保一致的體驗，無論使用者選擇在何處執行 .NET。 本文適用於符合下列項目的使用者：

  • 嘗試從來源建置 .NET。
  • 想要變更 .NET CLI，而可能影響產生的配置或套件。

磁碟配置

安裝後，.NET 包含幾個元件，這些元件在檔案系統中的配置如下所示：

{dotnet_root}                    (0)              (*)
├── dotnet                       (1)
├── LICENSE.txt                  (8)
├── ThirdPartyNotices.txt        (8)
├── host                                          (*)
│   └── fxr                                       (*)
│       └── <fxr version>        (2)
├── sdk                                           (*)
│   └── <sdk version>            (3)
├── sdk-manifests                (4)              (*)
│   └── <sdk feature band version>
├── library-packs                (4)              (*)
├── metadata                     (4)              (*)
│   └── workloads
│       └── <sdk feature band version>
├── template-packs               (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)
│   ├── Microsoft.NETCore.App.Runtime.<rid>       (*)
│   │   └── <runtime version>            (18)
│   └── Microsoft.AspNetCore.App.Runtime.<rid>    (*)
│       └── <aspnetcore version>         (18)
├── 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)

  • (0) {dotnet_root} 是所有 .NET 主要和次要版本的共用根路徑。 如果安裝多個執行階段，則會共用 {dotnet_root} 資料夾，例如 {dotnet_root}/shared/Microsoft.NETCore.App/6.0.11 和 {dotnet_root}/shared/Microsoft.NETCore.App/7.0.0。 資料夾的名稱 {dotnet_root} 應不受版本影響，也就是只有 dotnet。

  • (1) dotnet 主機 (也稱為"muxer") 有兩個不同的角色：啟用執行階段以啟動應用程式，以及啟用 SDK 將命令分派給它。 主機是原生可執行檔 (dotnet.exe)。

雖然是單一主機，但大部分其他元件都會位於已建立版本的目錄中 (2、3、5、6)。 這表示多個版本可能會存在於系統上，因為為並排安裝。

  • (2) host/fxr/<fxr 版本> 包含主機使用的架構解析邏輯。 主機會使用已安裝的最新 hostfxr。 hostfxr 負責在執行 .NET 應用程式時選取適當的執行階段。 例如，針對 .NET 7.0.0 建置的應用程式會在可用時使用 7.0.5 執行階段。 同樣地，hostfxr 會在開發期間選取適當的 SDK。

  • (3) sdk/<SDK 版本>：SDK (也稱為「工具」) 是一組受控工具，用於撰寫和建置 .NET 程式庫和應用程式。 SDK 包含 .NET CLI、受控語言編譯器、MSBuild 以及相關聯的建置工作和目標、NuGet、新專案範本等。

  • (4) sdk-manifests/<SDK 功能範圍版本>：選擇性工作負載安裝所需的資產名稱和版本，會保留於儲存在此資料夾中的工作負載資訊清單中。 資料夾名稱是 SDK 的功能範圍版本。 因此，假如 SDK 版本為 7.0.102，此資料夾仍會命名為 7.0.100。 安裝工作負載時，會視工作負載資產的需求建立下列資料夾：library-packs、metadata 和 template-packs。 如果工作負載應該安裝在使用者路徑下，而不是 dotnet 資料夾中，散發版本可以建立空的 /metadata/workloads/<SDK 功能範圍>/userlocal 檔案。 如需詳細資訊，請參閱 GitHub 問題 dotnet/installer#12104。

共用資料夾包含架構。 共用架構在集中位置提供一組程式庫，以供不同的應用程式使用。

  • (5) shared/Microsoft.NETCore.App/<執行階段版本> 此架構包含 .NET 執行階段和支援的受控程式庫。

  • (6) shared/Microsoft.AspNetCore.{App,All}/<aspnetcore 版本> 包含 ASP.NET Core 程式庫。 Microsoft.AspNetCore.App 下的程式庫會在 .NET 專案中進行開發並受到支援。 在 Microsoft.AspNetCore.All 下的程式庫是超集，其中也包含第三方程式庫。

  • (7) shared/Microsoft.Desktop.App/<傳統型應用程式版本> 包含 Windows 傳統型程式庫。 非 Windows 平台未包含此項。

  • (8) LICENSE.txt、ThirdPartyNotices.txt 分別是 .NET 授權及 .NET 中使用的第三方程式庫授權。

  • (9、10) dotnet.1.gz，dotnetdotnet.1.gz 是 dotnet 手冊頁面。 dotnet 是 dotnet host(1) 的符號連結。 這些檔案會安裝在已知位置，以進行系統整合。

  • (11，12) Microsoft.NETCore.App.Ref、Microsoft.AspNetCore.App.Ref 分別描述 .NET and ASP.NET Core 的 x.y 版 API。 針對這些目標版本進行編譯時，會使用這些套件。

  • (13) Microsoft.NETCore.App.Host.<rid> 包含平台 rid 的原生二進位檔。 將 .NET 應用程式編譯為該平台的原生二進位檔時，此二進位檔可作為範本。

  • (14) Microsoft.WindowsDesktop.App.Ref 描述 Windows 傳統型應用程式的 x.y 版 API。 針對該目標進行編譯時，會使用這些檔案。 非 Windows 平台未提供此項。

  • (15) NETStandard.Library.Ref 描述 netstandard x.y API。 針對該目標進行編譯時，會使用這些檔案。

  • (16) /etc/dotnet/install_location 是包含 {dotnet_root} 完整路徑的檔案。 路徑結尾可能是新行字元。 根目錄為 /usr/share/dotnet 時，不需要新增此檔案。

  • (17) templates 包含 SDK 使用的範本。 例如，dotnet new 會在這裡尋找專案範本。

  • (18) Microsoft.NETCore.App.Runtime.<rid>/<執行階段版本>、Microsoft.AspNetCore.App.Runtime.<rid>/<aspnetcore 版本> 這些檔案可讓您建置獨立應用程式。 這些目錄包含 (2)、(5) 和 (6) 中檔案的符號連結。

標示 (*) 的資料夾供多個套件使用。 某些套件格式 (例如 rpm) 需要特殊處理這類資料夾。 套件維護者必須負責此部分。

.NET 版本設定以執行階段元件 [major].[minor] 版本號碼為基礎。 SDK 版本使用相同的 [major].[minor]，且具有獨立的 [patch]，其結合 SDK 的功能及修補程式語意。 例如：SDK 7.0.302 版是 SDK 第三個功能版本的第二個修補程式版本，支援 7.0 執行階段。 如需版本設定運作方式的詳細資訊，請參閱 .NET 版本設定概觀。

部分套件的名稱包含版本號碼部分。 這可讓您安裝特定版本。 其餘的版本不包含在版本名稱中。 這可讓 OS 套件管理員更新套件 (例如自動安裝安全性修正程式)。 支援的套件管理員特定於 Linux。

下方列出建議的套件：

  • dotnet-sdk-[major].[minor] - 安裝特定執行階段的最新 SDK

    • 版本：<SDK 版本>
    • 範例：dotnet-sdk-7.0
    • 包含： (3)、(4)、(18)
    • 相依性：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 Runtime

    • 版本：<ASP.NET Core Runtime 版本>
    • 範例：aspnetcore-runtime-7.0
    • 包含：(6)
    • 相依性dotnet-runtime-[major].[minor]：

  • dotnet-runtime-deps-[major].[minor] (選擇性) - 安裝執行獨立應用程式的相依性

    • 版本：<執行階段版本>
    • 範例：dotnet-runtime-deps-7.0
    • 相依性：散發版本專屬的相依性

  • dotnet-runtime-[major].[minor] - 安裝特定執行階段

    • 版本：<執行階段版本>
    • 範例：dotnet-runtime-deps-7.0
    • 包含：(5)
    • 相依性：dotnet-hostfxr-[major].[minor]、dotnet-runtime-deps-[major].[minor]

  • dotnet-hostfxr-[major].[minor] - 相依性

    • 版本：<執行階段版本>
    • 範例：dotnet-hostfxr-7.0
    • 包含：(2)
    • 相依性dotnet-host：

  • dotnet-host - 相依性

    • 版本：<執行階段版本>
    • 範例：dotnet-host
    • 包含：(1),(8),(9),(10),(16)

  • dotnet-apphost-pack-[major].[minor] - 相依性

    • 版本：<執行階段版本>
    • 包含：(13)

  • dotnet-targeting-pack-[major].[minor] - 允許以非最新執行階段為目標

    • 版本：<執行階段版本>
    • 包含：(12)

  • aspnetcore-targeting-pack-[major].[minor] - 允許以非最新執行階段為目標

    • 版本：<ASP.NET Core Runtime 版本>
    • 包含：(11)

  • netstandard-targeting-pack-[netstandard_major].[netstandard_minor] - 允許以 .NET Standard 版本為目標

    • 版本：<SDK 版本>
    • 包含： (15)

  • dotnet-templates-[major].[minor]

    • 版本：<SDK 版本>
    • 包含：(17)

下列兩個中繼套件是選擇性的。 這兩個套件可將最上層套件 (dotnet-sdk) 抽象化，以簡化完整 .NET 套件集的安裝，為終端使用者帶來價值。 這些中繼套件參考特定的 .NET SDK 版本。

  • dotnet[major] - 安裝指定的 SDK 版本

    • 版本：<SDK 版本>
    • 範例：dotnet7
    • 相依性dotnet-sdk-[major].[minor]：

  • dotnet - 安裝特定 SDK 版本，由散發版本決定為主要版本；通常是最新的可用版本

    • 版本：<SDK 版本>
    • 範例：dotnet
    • 相依性dotnet-sdk-[major].[minor]：

dotnet-runtime-deps-[major].[minor] 需要理解「散發版本專屬的相依性」。 因為散發版本組建系統可能會自動予以衍生，所以套件是選擇性的。在此情況下，這些相依性會直接新增至 dotnet-runtime-[major].[minor] 套件。

當套件內容位於已設定版本的資料夾下時，套件名稱 [major].[minor] 會與已設定版本的資料夾名稱相符。 除了 netstandard-targeting-pack-[netstandard_major].[netstandard_minor] 之外的所有套件，這也會與 .NET 版本相符。

套件之間的相依性應使用「等於或大於」版本需求。 例如，dotnet-sdk-7.0:7.0.401 需要 aspnetcore-runtime-7.0 >= 7.0.6。 這可讓使用者透過根套件 (例如 dnf update dotnet-sdk-7.0) 升級其安裝。

大部分的發佈都需要從來源建置的所有成品。 這會對套件造成某個影響：

  • shared/Microsoft.AspNetCore.All 下的第三方程式庫無法從來源輕鬆建置。 因此會從 aspnetcore-runtime 套件省略該資料夾。

  • 使用 nuget.org 中的二進位成品填入 NuGetFallbackFolder。 它應該維持空白。

多個 dotnet-sdk 套件可能會提供相同的 NuGetFallbackFolder 檔案。 為了避免套件管理員問題，這些檔案都應該相同 (總和檢查碼、修改日期等)。

偵錯套件

偵錯內容應該封裝在偵錯命名的套件中，此套件遵循本文先前所述的 .NET 套件分割方式。 例如，dotnet-sdk-[major].[minor] 套件的偵錯內容應包含在名為 dotnet-sdk-dbg-[major].[minor] 的套件中。 您應該將偵錯內容安裝到與二進位檔相同的位置。

以下是一些二進位檔範例：

在 {dotnet_root}/sdk/<sdk version> 目錄中，預期會有下列兩個檔案：

  • dotnet.dll - 隨 dotnet-sdk-[major].[minor] 套件一起安裝
  • dotnet.pdb - 隨 dotnet-sdk-dbg-[major].[minor] 套件一起安裝

在 {dotnet_root}/shared/Microsoft.NETCore.App/<runtime version> 目錄中，預期會有下列兩個檔案：

  • System.Text.Json.dll - 隨 dotnet-runtime-[major].[minor] 套件一起安裝
  • System.Text.Json.pdb - 隨 dotnet-runtime-dbg-[major].[minor] 套件一起安裝

在 {dotnet_root/shared/Microsoft.AspNetCore.App/<aspnetcore version> 目錄中，預期會有下列兩個檔案：

  • Microsoft.AspNetCore.Routing.dll - 隨 aspnetcore-runtime-[major].[minor] 套件一起安裝
  • Microsoft.AspNetCore.Routing.pdb - 隨 aspnetcore-runtime-dbg-[major].[minor] 套件一起安裝

從 .NET 8.0 開始，來源組建產生的所有 .NET 偵錯內容 (PDB 檔案) 都可以在名為 dotnet-symbols-sdk-<version>-<rid>.tar.gz 的 tarball 中使用。 此封存包含子目錄中符合 .NET SDK tarball 目錄結構的 PDB - dotnet-sdk-<version>-<rid>.tar.gz。

雖然所有偵錯內容都可在偵錯 tarball 中取得，但並非所有偵錯內容都同樣重要。 終端使用者對 shared/Microsoft.AspNetCore.App/<aspnetcore version> 和 shared/Microsoft.NETCore.App/<runtime version> 目錄的內容最感興趣。

sdk/<sdk version> 下的 SDK 內容對於偵錯 .NET SDK 工具組很有用。

下列套件是建議的偵錯套件：

  • aspnetcore-runtime-dbg-[major].[minor] - 安裝特定 ASP.NET Core 執行階段的偵錯內容

    • 版本：<ASP.NET Core Runtime 版本>
    • 範例： aspnetcore-runtime-dbg-8.0
    • 包含：(6) 的偵錯內容
    • 相依性aspnetcore-runtime-[major].[minor]：

  • dotnet-runtime-dbg-[major].[minor] - 安裝特定執行階段的偵錯內容

    • 版本：<執行階段版本>
    • 範例： dotnet-runtime-dbg-8.0
    • 包含：(5) 的偵錯內容
    • 相依性dotnet-runtime-[major].[minor]：

以下是選用的偵錯套件：

  • dotnet-sdk-dbg-[major].[minor] - 安裝特定 SDK 版本的偵錯內容
    • 版本：<SDK 版本>
    • 範例： dotnet-sdk-dbg-8.0
    • 包含：(3)、(4)、(18) 的偵錯內容
    • 相依性dotnet-sdk-[major].[minor]：

偵錯 tarball 也包含 packs 底下的一些偵錯內容，代表 shared 下的內容複本。 在 .NET 配置中，packs 目錄用於建置 .NET 應用程式。 沒有偵錯案例，因此您不應該將 packs 下的偵錯內容封裝在偵錯 tarball 中。

建置套件

dotnet/source-build 存放庫提供如何建置 .NET SDK 及其所有元件之來源 tarball 的指示。 source-build 存放庫的輸出會比對本文第一節中所述的配置。