Поделиться через

Упаковка дистрибутивов .NET

Поскольку .NET 5 (и .NET Core) и более поздние версии становятся доступными на все большем числе платформ, полезно изучить, как упаковывать приложения и библиотеки, присваивать им имена и управлять их версиями. Таким образом издатели пакетов смогут обеспечить согласованную работу независимо от платформы, выбранной пользователями для запуска .NET. Эта статья пригодится пользователям, которые:

  • Пытаются собрать .NET из исходного кода.
  • хотят внести в .NET CLI изменения, способные повлиять на итоговый макет или создаваемые пакеты.

Разметка диска

Установка .NET включает несколько компонентов, которые располагаются в файловой системе следующим образом:

{dotnet_root}                    (0)              (*)
├── dotnet                       (1)
├── dnx                          (22)
├── LICENSE.txt                  (8)
├── ThirdPartyNotices.txt        (8)
├── host                                          (*)
│   └── fxr                                       (*)
│       └── <fxr version>        (2)
├── sdk                                           (*)
│   └── <sdk version>            (3)
├── sdk-manifests                (4)              (*)
│   └── <sdk feature band version>
├── library-packs                (21)             (*)
├── 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)
│   └── Microsoft.NETCore.App.Runtime.NativeAOT.<rid> (*)
│       └── <runtime version>            (20)
├── 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)
        └── dnx                  (23)

  • (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: хост (также известный как "мультиплексор") выполняет две функции: используется для запуска среды выполнения приложения и активации SDK для отправки команд. Хост представляет собой исполняемый файл (dotnet.exe).

  • (22) dnx Скрипт dnx — это исполняемый скрипт оболочки, цель которого — переадресация пользовательских команд в dotnet dnx команду в пакете SDK. Эта функция в основном существует, чтобы сделать приобретение и запуск различных типов приложений .NET, таких как средства .NET, проще для конечных пользователей. Думайте об этом аналогично команде npx из Node. Она является независимой от версии, так как большинство фактических функциональных возможностей dnx процесса однократного выполнения обрабатывается в реализации CLI в dotnet каталоге пакета SDK с версиями.

Хотя хост единственный, большинство остальных компонентов находятся в версиях директории (2, 3, 5, 6). Это значит, что в системе могут быть представлены сразу несколько версий, поскольку разные версии компонентов устанавливаются параллельно.

  • (2) host/fxr/<fxr version> содержит логику разрешения фреймворка, используемую хостом. Хост использует последнюю установленную версию hostfxr. Hostfxr отвечает за выбор необходимой среды выполнения при запуске приложения .NET. Например, приложение, созданное для .NET 7.0.0,0, использует среду выполнения 7.0.5, когда она доступна. Аналогично hostfxr выбирает соответствующую версию SDK во время разработки.

  • ** (3) sdk/<версия sdk> SDK (также известный как "набор инструментов") — это набор управляемых средств, которые используются для написания и сборки библиотек и приложений .NET. Пакет SDK содержит .NET CLI, компиляторы языков с управляемым кодом, MSBuild, а также соответствующие задачи и целевые объекты сборки, NuGet, новые шаблоны проектов и т. д.

  • (4) sdk-manifests/<версия sdk feature band> Имена и версии ресурсов, необходимых для установки необязательной рабочей нагрузки, сохраняются в манифестах рабочей нагрузки, которые хранятся в этой папке. Имя папки — это версия SDK в рамках функциональной ветки. Поэтому для версии пакета SDK, например 7.0.102, эта папка по-прежнему будет называться 7.0.100. При установке рабочей нагрузки создаются следующие папки, необходимые для ресурсов рабочей нагрузки: метаданных и пакетов шаблонов. Распределение может создать пустой файл /metadata/workloads/<sdkfeatureband>/userlocal , если рабочие нагрузки должны быть установлены в пользовательском пути, а не в папке dotnet . Дополнительные сведения см. в статье GitHub issue dotnet/installer#12104.

Папка shared содержит платформы. Общая платформа предоставляет набор библиотек в центральном расположении таким образом, что они могут использоваться другими приложениями.

  • (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/<desktop app version> содержит библиотеки рабочего стола Windows. Не используется на платформах, отличных от Windows.

  • (8) LICENSE.txt,ThirdPartyNotices.txt — тексты лицензий .NET и лицензий библиотек сторонних производителей, используемых в .NET, соответственно.

  • (9,10, 23) dotnet.1.gz, dotnetdotnet.1.gz — это руководство для dotnet. dotnet представляет собой символьную ссылку на хост dotnet(1). dnx — это ссылка на скрипт оболочки dnx (22). Эти файлы устанавливаются в типичные расположения для системной интеграции.

  • (11,12) Microsoft.NETCore.App.Ref,Microsoft.AspNetCore.App.Ref описывают API соответствующей версии x.y .NET и ASP.NET Core соответственно. Эти пакеты используются при компиляции для этих целевых версий.

  • (13) Microsoft.NETCore.App.Host.<rid> содержит собственный двоичный файл для платформы rid. Этот двоичный файл представляет собой шаблон, используемый при компиляции приложения .NET в собственный двоичный файл для этой платформы.

  • (14) Microsoft.WindowsDesktop.App.Ref описывает API версии x.y для настольных приложений Windows. Эти файлы используются при компиляции для этого целевого объекта. Не используется на платформах, отличных от Windows.

  • (15) NETStandard.Library.Ref описывает API x.y netstandard. Эти файлы используются при компиляции для этого целевого объекта.

  • (16) /etc/dotnet/install_location — это файл, содержащий полный путь для {dotnet_root}. Путь может заканчиваться новой строкой. Если корневым элементом является /usr/share/dotnet, добавлять этот файл не нужно.

  • (17) templates содержат шаблоны, используемые пакетом SDK. Например, dotnet new находит шаблоны проектов.

  • (18) Microsoft.NETCore.App.Runtime.<версия rid>/<runtime,Microsoft.AspNetCore.App.Runtime>.<Версия rid>/<aspnetcore> Эти файлы позволяют создавать автономные приложения. Эти каталоги содержат символьные ссылки на файлы (2), (5) и (6).

  • (19) время выполнения.<rid>.Microsoft.DotNet.ILCompiler/<runtime version> Эти файлы позволяют создавать приложения NativeAOT на целевой платформе. В .NET 9 также позволяет создавать приложения NativeAOT для целевой платформы. Может присутствовать в .NET 9 и более поздней версии.

  • (20) Microsoft.NETCore.App.Runtime.NativeAOT.<rid>/<версия среды выполнения> Эти файлы позволяют создавать приложения NativeAOT для целевой платформы. Может присутствовать в .NET 10 и более поздней версии.

  • (21) пакеты библиотек содержат файлы пакетов NuGet. Пакет SDK настроен для использования этой папки в качестве источника NuGet. Ниже описан список пакетов NuGet, предоставляемых сборкой .NET.

Папки, помеченные (*), используются несколькими пакетами. Для некоторых форматов пакетов (например, rpm) требуется специальная обработка таких папок. Этим должен заниматься мантейнер пакетов.

Файлы пакетов, добавленные в library-packs (21), могут быть пакетами, которые корпорация Майкрософт не распространяет для целевой платформы. Файлы также могут быть пакетами, распространяемыми корпорацией Майкрософт, и для которых library-packs предоставляет пакет, созданный из исходного кода для удовлетворения рекомендаций по распространению пакетов платформы. Следующие пакеты включаются в сборку .NET:

Имя пакета Опубликовано Майкрософт Требуемые для
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.

Некоторые пакеты содержат часть номера версии в своем имени. Это позволяет устанавливать определенную версию. Остальные компоненты версии не являются частью имени версии. Это позволяет диспетчеру пакетов операционной системы обновлять пакеты (например, автоматически устанавливать исправления безопасности). Поддерживаемые диспетчеры пакетов рассчитаны на Linux.

Далее перечислены рекомендуемые пакеты.

  • dotnet-sdk-[major].[minor] — устанавливает последний пакет SDK для определенной среды выполнения

    • Версия:<sdk>
    • Пример: dotnet-sdk-7.0
    • Содержит: (3),(4),(18),(21)
    • Зависимости: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] — устанавливает компоненты ПАКЕТА SDK для платформы NativeAOT

    • Версия:<sdk>
    • Пример: dotnet-sdk-aot-9.0
    • Содержит: (19, 20)
    • Зависимости:dotnet-sdk-[major].[minor], цепочка инструментов компилятора и пакеты разработчика для библиотек, от которые зависит среда выполнения .NET

  • aspnetcore-runtime-[major].[minor] — устанавливает конкретную среду выполнения ASP.NET Core

    • Версия:<aspnetcore runtime version>
    • Пример: 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-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),(22),(23)

  • dotnet-apphost-pack-[major].[minor] — зависимость

    • Версия:<версия среды выполнения>
    • Содержит: (13)

  • dotnet-targeting-pack-[major].[minor] — нацеливание на непоследнюю среду выполнения

    • Версия:<версия среды выполнения>
    • Содержит: (12)

  • aspnetcore-targeting-pack-[major].[minor] — позволяет нацеливаться на не самую последнюю версию среды выполнения

    • Версия:<aspnetcore runtime version>
    • Содержит: (11)

  • netstandard-targeting-pack-[netstandard_major].[netstandard_minor] — Позволяет нацеливаться на версию netstandard

    • Версия:<sdk>
    • Содержит: (15)

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

    • Версия:<sdk>
    • Содержит: (17)

Следующие два метапакета являются необязательными. Они приносят значение конечным пользователям в том, что они абстрагируют пакет верхнего уровня (dotnet-sdk), что упрощает установку полного набора пакетов .NET. Эти метапакеты ссылались на определенную версию пакета SDK для .NET.

  • 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.

  • Папка NuGetFallbackFolder заполняется двоичными артефактами из nuget.org. Она должна оставаться пустой.

Несколько пакетов dotnet-sdk могут предоставлять одни и те же файлы для каталога NuGetFallbackFolder. Чтобы не возникали проблемы с диспетчером пакетов, эти файлы (контрольная сумма, дата изменения и т. д.) должны быть идентичны.

Отладка пакетов

Содержимое отладки следует упаковать в пакеты с именем debug, которые следуют разделению пакетов .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), созданные в исходной сборке, доступны в tarball с именем dotnet-symbols-sdk-<version>-<rid>.tar.gz. Этот архив содержит файлы PDB в подкаталогах, которые соответствуют структуре каталогов tarball dotnet-sdk-<version>-<rid>.tar.gz пакета SDK для .NET.

Хотя все содержимое отладки доступно в отладочном архиве tar, не все отладочное содержимое одинаково важно. Конечные пользователи в основном заинтересованы в содержимом shared/Microsoft.AspNetCore.App/<aspnetcore version> каталогов и shared/Microsoft.NETCore.App/<runtime version> каталогов.

Содержимое sdk/<sdk version> пакета SDK полезно для отладки наборов инструментов пакета SDK для .NET.

Ниже перечислены рекомендуемые пакеты отладки:

  • aspnetcore-runtime-dbg-[major].[minor] — устанавливает отладочное содержимое для определенной среды выполнения ASP.NET Core

    • Версия:<aspnetcore runtime version>
    • Пример: 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]

Отладочный архив также содержит некоторое отладочное содержимое в секции packs, представляющее копии содержимого в секции shared. В структуре packs .NET каталог используется для создания приложений .NET. Нет сценариев отладки, поэтому не следует упаковывать содержимое отладки под packs в отладочный tarball.

Построение пакетов

Репозиторий dotnet/source-build содержит инструкции по созданию архива TAR с исходным кодом пакета SDK для .NET и всех его компонентов. Выход репозитория, построенного из источника, соответствует виду, описанному в первом разделе этой статьи.

  • Last updated on