Pakowanie dystrybucji platformy .NET

  • Artykuł

Ponieważ platforma .NET 5 (i .NET Core) i nowsze wersje stają się dostępne na coraz więcej platform, warto dowiedzieć się, jak pakować, nazywać i wersjonować aplikacje i biblioteki, które go używają. Dzięki temu osoby odpowiedzialne za pakiety mogą pomóc zapewnić spójne środowisko niezależnie od tego, gdzie użytkownicy zdecydują się uruchamiać platformę .NET. Ten artykuł jest przydatny dla użytkowników, którzy:

  • Próba skompilowania platformy .NET ze źródła.
  • Chcesz wprowadzić zmiany w interfejsie wiersza polecenia platformy .NET, które mogą mieć wpływ na wynikowy układ lub utworzone pakiety.

Układ dysku

Po zainstalowaniu platforma .NET składa się z kilku składników, które są określone w następujący sposób w systemie plików:

{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} to współużytkowany katalog główny dla wszystkich wersji głównych i pomocniczych platformy .NET. Jeśli zainstalowano wiele środowisk uruchomieniowych, współużytkują folder {dotnet_root} , na przykład {dotnet_root}/shared/Microsoft.NETCore.App/6.0.11 i {dotnet_root}/shared/Microsoft.NETCore.App/7.0.0. Nazwa {dotnet_root} folderu powinna być niezależna od wersji, czyli po prostu dotnet.

  • (1) dotnet Host (znany również jako "muxer") ma dwie odrębne role: aktywowanie środowiska uruchomieniowego w celu uruchomienia aplikacji i aktywowanie zestawu SDK w celu wysyłania do niego poleceń. Host jest natywnym plikiem wykonywalnym (dotnet.exe).

Chociaż istnieje jeden host, większość innych składników jest w katalogach w wersji (2,3,5,6). Oznacza to, że w systemie może znajdować się wiele wersji, ponieważ są instalowane obok siebie.

  • (2) host/fxr/<fxr wersja> zawiera logikę rozpoznawania struktury używaną przez hosta. Host używa najnowszego zainstalowanego narzędzia hostfxr. Hostfxr jest odpowiedzialny za wybranie odpowiedniego środowiska uruchomieniowego podczas wykonywania aplikacji platformy .NET. Na przykład aplikacja utworzona dla platformy .NET 7.0.0 używa środowiska uruchomieniowego 7.0.5, gdy jest dostępna. Podobnie narzędzie hostfxr wybiera odpowiedni zestaw SDK podczas programowania.

  • (3) sdk/<sdk wersja> zestawu SDK (nazywana również "narzędziami") to zestaw narzędzi zarządzanych używanych do pisania i kompilowania bibliotek i aplikacji platformy .NET. Zestaw SDK zawiera interfejs wiersza polecenia platformy .NET, kompilatory języków zarządzanych, program MSBuild oraz skojarzone zadania kompilacji i obiekty docelowe, NuGet, nowe szablony projektów itd.

  • (4) sdk-manifests/<sdk feature band version> Nazwy i wersje zasobów, których wymagana jest opcjonalna instalacja obciążenia, są przechowywane w manifestach obciążeń przechowywanych w tym folderze. Nazwa folderu to wersja zestawu SDK dla przedziału funkcji. W przypadku wersji zestawu SDK, takiej jak 7.0.102, ten folder nadal będzie miał nazwę 7.0.100. Po zainstalowaniu obciążenia następujące foldery są tworzone zgodnie z potrzebami dla zasobów obciążenia: pakiety bibliotek, metadane i pakiety szablonów. Dystrybucja może utworzyć pusty plik /metadata/workloads/<sdkfeatureband>/userlocal , jeśli obciążenia powinny być zainstalowane w ścieżce użytkownika, a nie w folderze dotnet . Aby uzyskać więcej informacji, zobacz problem z usługą GitHub dotnet/installer#12104.

Folder udostępniony zawiera struktury. Platforma udostępniona udostępnia zestaw bibliotek w centralnej lokalizacji, dzięki czemu mogą być używane przez różne aplikacje.

  • (5) shared/Microsoft.NETCore.App/<runtime wersja> ta zawiera środowisko uruchomieniowe platformy .NET i pomocnicze biblioteki zarządzane.

  • (6) shared/Microsoft.AspNetCore.{ Aplikacja,Wszystkie}/<wersja aspnetcore> zawiera biblioteki ASP.NET Core. Biblioteki w ramach programu Microsoft.AspNetCore.App są opracowywane i obsługiwane w ramach projektu platformy .NET. Biblioteki w obszarze Microsoft.AspNetCore.All są nadzbiorem, który zawiera również biblioteki innych firm.

  • (7) udostępniona/Microsoft.Desktop.App/<wersja> aplikacji klasycznej zawiera biblioteki klasyczne systemu Windows. Nie jest to uwzględnione na platformach innych niż Windows.

  • (8) LICENSE.txt,ThirdPartyNotices.txt są licencjami platformy .NET i licencjami bibliotek innych firm używanych odpowiednio na platformie .NET.

  • (910) dotnet.1.gz, dotnet to strona ręczna dotnetdotnet.1.gz . dotnet to symlink do hosta dotnet(1). Te pliki są instalowane w dobrze znanych lokalizacjach integracji systemu.

  • (11,12) Microsoft.NETCore.App.Ref,Microsoft.AspNetCore.App.Ref opisują interfejs API x.y odpowiednio wersji platformy .NET i ASP.NET Core. Te pakiety są używane podczas kompilowania dla tych wersji docelowych.

  • (13) Microsoft.NETCore.App.Host.<rid> zawiera natywny plik binarny dla platformy rid. Ten plik binarny jest szablonem podczas kompilowania aplikacji .NET do natywnego pliku binarnego dla tej platformy.

  • (14) Microsoft.WindowsDesktop.App.Ref opisuje interfejs API x.y wersji aplikacji klasycznych systemu Windows. Te pliki są używane podczas kompilowania dla tego obiektu docelowego. Nie jest to udostępniane na platformach innych niż Windows.

  • (15) NETStandard.Library.Ref opisuje interfejs API netstandard x.y . Te pliki są używane podczas kompilowania dla tego obiektu docelowego.

  • (16) /etc/dotnet/install_location jest plikiem zawierającym pełną ścieżkę dla .{dotnet_root} Ścieżka może kończyć się nowym wierszem. Nie trzeba dodawać tego pliku, gdy katalog główny ma wartość /usr/share/dotnet.

  • (17) Szablony zawierają szablony używane przez zestaw SDK. Na przykład dotnet new znajdziesz tutaj szablony projektów.

  • (18) Microsoft.NETCore.App.Runtime.<rid>/<runtime version,Microsoft.AspNetCore.App.Runtime>.<rid>/<aspnetcore version> Te pliki umożliwiają tworzenie aplikacji samodzielnie zawartych. Te katalogi zawierają łącza symboliczne do plików w (2), (5) i (6).

Foldery oznaczone za pomocą (*) są używane przez wiele pakietów. Niektóre formaty pakietów (na przykład rpm) wymagają specjalnej obsługi takich folderów. Osoba odpowiedzialne za pakiet musi się tym zająć.

Przechowywanie wersji platformy .NET jest oparte na numerach wersji składnika [major].[minor] środowiska uruchomieniowego. Wersja zestawu SDK używa tego samego [major].[minor] elementu i ma niezależną funkcję [patch] , która łączy semantyka funkcji i poprawek dla zestawu SDK. Na przykład: zestaw SDK w wersji 7.0.302 jest drugą wersją poprawki trzeciego wydania funkcji zestawu SDK obsługującego środowisko uruchomieniowe 7.0. Aby uzyskać więcej informacji na temat sposobu działania przechowywania wersji, zobacz Omówienie obsługi wersji platformy .NET.

Niektóre pakiety zawierają część numeru wersji w nazwie. Dzięki temu można zainstalować określoną wersję. Pozostała część wersji nie jest uwzględniona w nazwie wersji. Dzięki temu menedżer pakietów systemu operacyjnego może aktualizować pakiety (na przykład automatycznie instalować poprawki zabezpieczeń). Obsługiwane menedżery pakietów są specyficzne dla systemu Linux.

Poniżej wymieniono zalecane pakiety:

  • dotnet-sdk-[major].[minor] — Instaluje najnowszy zestaw SDK dla określonego środowiska uruchomieniowego

    • Wersja:<wersja zestawu SDK>
    • Przykład: dotnet-sdk-7.0
    • Zawiera: (3),(4),(18)
    • Zależności: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] — Instaluje określone środowisko uruchomieniowe ASP.NET Core

    • Version:<aspnetcore runtime version (Wersja środowiska uruchomieniowego aspnetcore)>
    • Przykład: aspnetcore-runtime-7.0
    • Zawiera: (6)
    • Zależnościdotnet-runtime-[major].[minor]:

  • dotnet-runtime-deps-[major].[minor](Opcjonalnie) — Instaluje zależności na potrzeby uruchamiania samodzielnych aplikacji

    • Wersja:<wersja środowiska uruchomieniowego>
    • Przykład: dotnet-runtime-deps-7.0
    • Zależności: zależności specyficzne dla dystrybucji

  • dotnet-runtime-[major].[minor] — Instaluje określone środowisko uruchomieniowe

    • Wersja:<wersja środowiska uruchomieniowego>
    • Przykład: dotnet-runtime-7.0
    • Zawiera: (5)
    • Zależności:dotnet-hostfxr-[major].[minor], dotnet-runtime-deps-[major].[minor]

  • dotnet-hostfxr-[major].[minor] -Zależności

    • Wersja:<wersja środowiska uruchomieniowego>
    • Przykład: dotnet-hostfxr-7.0
    • Zawiera: (2)
    • Zależnościdotnet-host:

  • dotnet-host -Zależności

    • Wersja:<wersja środowiska uruchomieniowego>
    • Przykład: dotnet-host
    • Zawiera: (1),(8),(9),(10),(16)

  • dotnet-apphost-pack-[major].[minor] -Zależności

    • Wersja:<wersja środowiska uruchomieniowego>
    • Zawiera: (13)

  • dotnet-targeting-pack-[major].[minor] — Zezwala na kierowanie do nie najnowszego środowiska uruchomieniowego

    • Wersja:<wersja środowiska uruchomieniowego>
    • Zawiera: (12)

  • aspnetcore-targeting-pack-[major].[minor] — Zezwala na kierowanie do nie najnowszego środowiska uruchomieniowego

    • Version:<aspnetcore runtime version (Wersja środowiska uruchomieniowego aspnetcore)>
    • Zawiera: (11)

  • netstandard-targeting-pack-[netstandard_major].[netstandard_minor] — Zezwala na określanie wartości docelowej wersji netstandard

    • Wersja:<wersja zestawu SDK>
    • Zawiera: (15)

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

    • Wersja:<wersja zestawu SDK>
    • Zawiera: (17)

Następujące dwa meta pakiety są opcjonalne. Przynoszą one wartość dla użytkowników końcowych, że abstrakują pakiet najwyższego poziomu (dotnet-sdk), co upraszcza instalację pełnego zestawu pakietów .NET. Te pakiety meta odwołują się do określonej wersji zestawu .NET SDK.

  • dotnet[major] — Instaluje określoną wersję zestawu SDK

    • Wersja:<wersja zestawu SDK>
    • Przykład: dotnet7
    • Zależnościdotnet-sdk-[major].[minor]:

  • dotnet — Instaluje określoną wersję zestawu SDK określaną przez dystrybucje jako wersję podstawową — zazwyczaj najnowszą dostępną

    • Wersja:<wersja zestawu SDK>
    • Przykład: dotnet
    • Zależnościdotnet-sdk-[major].[minor]:

Wymaga dotnet-runtime-deps-[major].[minor] zrozumienia zależności specyficznych dla dystrybucji. Ponieważ system kompilacji dystrybucji może być w stanie uzyskać ten proces automatycznie, pakiet jest opcjonalny, w takim przypadku te zależności są dodawane bezpośrednio do dotnet-runtime-[major].[minor] pakietu.

Gdy zawartość pakietu znajduje się w folderze w wersji, nazwa [major].[minor] pakietu jest zgodna z nazwą folderu wersji. Dla wszystkich pakietów, z wyjątkiem netstandard-targeting-pack-[netstandard_major].[netstandard_minor], jest to również zgodne z wersją platformy .NET.

Zależności między pakietami powinny używać wymagania dotyczącego wersji równej lub większej . Na przykład dotnet-sdk-7.0:7.0.401 wymaga .aspnetcore-runtime-7.0 >= 7.0.6 Dzięki temu użytkownik może uaktualnić instalację za pośrednictwem pakietu głównego (na przykład dnf update dotnet-sdk-7.0).

Większość dystrybucji wymaga skompilowania wszystkich artefaktów ze źródła. Ma to pewien wpływ na pakiety:

  • Biblioteki innych firm w obszarze shared/Microsoft.AspNetCore.All nie mogą być łatwo kompilowane ze źródła. W związku z tym folder zostanie pominięty z aspnetcore-runtime pakietu.

  • Element NuGetFallbackFolder jest wypełniany przy użyciu artefaktów binarnych z klasy nuget.org. Powinna pozostać pusta.

Wiele dotnet-sdk pakietów może zawierać te same pliki dla elementu NuGetFallbackFolder. Aby uniknąć problemów z menedżerem pakietów, te pliki powinny być identyczne (suma kontrolna, data modyfikacji itd.).

Debugowanie pakietów

Zawartość debugowania powinna być spakowana w pakietach o nazwie debugowania, które są zgodne z podziałem pakietu platformy .NET opisanym wcześniej w tym artykule. Na przykład zawartość debugowania pakietu dotnet-sdk-[major].[minor] powinna być uwzględniona w pakiecie o nazwie dotnet-sdk-dbg-[major].[minor]. Należy zainstalować zawartość debugowania w tej samej lokalizacji co pliki binarne.

Oto kilka przykładów binarnych:

{dotnet_root}/sdk/<sdk version> W katalogu oczekiwane są następujące dwa pliki:

  • dotnet.dll— zainstalowane z pakietem dotnet-sdk-[major].[minor]
  • dotnet.pdb— zainstalowane z pakietem dotnet-sdk-dbg-[major].[minor]

{dotnet_root}/shared/Microsoft.NETCore.App/<runtime version> W katalogu oczekiwane są następujące dwa pliki:

  • System.Text.Json.dll— zainstalowane z pakietem dotnet-runtime-[major].[minor]
  • System.Text.Json.pdb— zainstalowane z pakietem dotnet-runtime-dbg-[major].[minor]

{dotnet_root/shared/Microsoft.AspNetCore.App/<aspnetcore version> W katalogu oczekiwane są następujące dwa pliki:

  • Microsoft.AspNetCore.Routing.dll— zainstalowane z pakietami aspnetcore-runtime-[major].[minor]
  • Microsoft.AspNetCore.Routing.pdb— zainstalowane z pakietami aspnetcore-runtime-dbg-[major].[minor]

Począwszy od platformy .NET 8.0, cała zawartość debugowania platformy .NET (pliki PDB), utworzona przez kompilację źródłową, jest dostępna w tarball o nazwie dotnet-symbols-sdk-<version>-<rid>.tar.gz. To archiwum zawiera pliki PDB w podkatalogach, które pasują do struktury katalogów tarball zestawu .NET SDK — dotnet-sdk-<version>-<rid>.tar.gz.

Chociaż cała zawartość debugowania jest dostępna w narzędziu tarball debugowania, nie wszystkie treści debugowania są równie ważne. Użytkownicy końcowi są głównie zainteresowani zawartością shared/Microsoft.AspNetCore.App/<aspnetcore version> katalogów i shared/Microsoft.NETCore.App/<runtime version> .

Zawartość zestawu SDK w obszarze sdk/<sdk version> jest przydatna do debugowania zestawów narzędzi zestawu SDK platformy .NET.

Poniżej przedstawiono zalecane pakiety debugowania:

  • aspnetcore-runtime-dbg-[major].[minor] — Instaluje zawartość debugowania dla określonego środowiska uruchomieniowego ASP.NET Core

    • Version:<aspnetcore runtime version (Wersja środowiska uruchomieniowego aspnetcore)>
    • Przykład: aspnetcore-runtime-dbg-8.0
    • Zawiera: zawartość debugowania dla (6)
    • Zależnościaspnetcore-runtime-[major].[minor]:

  • dotnet-runtime-dbg-[major].[minor] — Instaluje zawartość debugowania dla określonego środowiska uruchomieniowego

    • Wersja:<wersja środowiska uruchomieniowego>
    • Przykład: dotnet-runtime-dbg-8.0
    • Zawiera: debugowanie zawartości dla (5)
    • Zależnościdotnet-runtime-[major].[minor]:

Następujący pakiet debugowania jest opcjonalny:

  • dotnet-sdk-dbg-[major].[minor] — Instaluje zawartość debugowania dla określonej wersji zestawu SDK
    • Wersja:<wersja zestawu SDK>
    • Przykład: dotnet-sdk-dbg-8.0
    • Zawiera: zawartość debugowania dla (3),(4),(18)
    • Zależnościdotnet-sdk-[major].[minor]:

Debugowanie tarball zawiera również część zawartości debugowania w obszarze packs, która reprezentuje kopie zawartości w obszarze shared. W układzie platformy packs .NET katalog jest używany do tworzenia aplikacji platformy .NET. Nie ma scenariuszy debugowania, więc nie należy pakować zawartości debugowania w obszarze packs w narzędziu tarball debugowania.

Kompilowanie pakietów

Repozytorium dotnet/source-build zawiera instrukcje dotyczące tworzenia źródłowego tarballa zestawu .NET SDK i wszystkich jego składników. Dane wyjściowe repozytorium source-build są zgodne z układem opisanym w pierwszej sekcji tego artykułu.