共用方式為


.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                (20)             (*)
├── 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)
│   └── runtime.<rid>.Microsoft.DotNet.ILCompiler (*)
│       └── <runtime version>            (19)
├── 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。 安裝工作負載時,會視需要為工作負載的資產建立下列資料夾: 元數據範本套件。 如果工作負載應該安裝在使用者路徑下,而不是 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,dotnet dotnet.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) 中檔案的符號連結。

  • (19) 運行時間。<rid>。Microsoft.DotNet.ILCompiler/<runtime 版本> :這些檔案可建置目標平臺的 NativeAOT 應用程式。

  • (20) 連結庫套件 包含 NuGet 套件檔案。 SDK 已設定為使用此資料夾作為 NuGet 來源。 .NET 組建所提供的 NuGet 套件清單如下所述。

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

新增至 library-packs (20) 的套件檔案可以是Microsoft未針對目標平臺散發的套件。 這些檔案也可以是Microsoft散發的套件,並提供 library-packs 從來源建置的套件,以符合平臺套件發佈指導方針。 .NET 組建包含下列套件:

封裝名稱 由 Microsoft 發佈 需要
Microsoft.DotNet.ILCompiler.<version>.nupkg
Microsoft.NET.ILLink.Tasks.<version>.nupkg
NativeAOT

.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),(20)
    • 相依性: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]
  • dotnet-sdk-aot-[major].[minor] - 安裝平臺 NativeAOT 的 SDK 元件

    • 版本:<SDK 版本>
    • 範例: dotnet-sdk-aot-9.0
    • 包含: (19)
    • 相依性:dotnet-sdk-[major].[minor]編譯程式工具鏈和 .NET 運行時間相依連結庫的開發人員套件
  • 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 存放庫的輸出會比對本文第一節中所述的配置。