Empaquetage de distribution .NET

  • Article

À mesure que .NET 5 (et .NET Core) et les versions ultérieures deviennent disponibles sur de plus en plus de plateformes, il est utile d’apprendre à empaqueter, nommer et version les applications et les bibliothèques qui l’utilisent. De cette manière, les chargés de maintenance des packages pourront garantir une expérience cohérente quelle que soit la plateforme choisie par les utilisateurs pour exécuter .NET. Cet article est utile pour les utilisateurs qui :

  • Essaient de générer .NET à partir de la source.
  • Souhaitent apporter des modifications à l’interface CLI .NET susceptibles d’impacter la disposition résultante ou les packages générés.

Disposition du disque

Une fois installé, .NET est constitué de plusieurs composants qui sont disposés comme suit dans le système de fichiers :

{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} est une racine partagée pour toutes les versions principales et mineures de .NET. Si plusieurs runtimes sont installés, ils partagent le dossier {dotnet_root}, par exemple, {dotnet_root}/shared/Microsoft.NETCore.App/6.0.11 et {dotnet_root}/shared/Microsoft.NETCore.App/7.0.0. Le nom du {dotnet_root} dossier doit être indépendant de la version, c’est-à-dire simplement dotnet.

  • (1) dotnet L’hôte (également appelé « muxer ») a deux rôles distincts : activer un runtime pour lancer une application, et un SDK pour lui distribuer des commandes. L’hôte est un fichier exécutable natif (dotnet.exe).

Alors qu’il n’y a qu’un seul hôte, la plupart des autres composants sont dans des répertoires avec version (2,3,5,6). Cela signifie que plusieurs versions peuvent être présentes sur le système, car elles sont installées côte à côte.

  • (2) host/fxr/<version fxr> contient la logique de résolution du framework utilisé par l’hôte. L’hôte utilise la dernière version de hostfxr qui est installée. hostfxr est chargé de sélectionner le runtime approprié lors de l’exécution d’une application .NET. Par exemple, une application générée pour .NET 7.0.0 utilise le runtime 7.0.5 quand il est disponible. De même, hostfxr sélectionne le SDK approprié au cours du développement.

  • (3) sdk/<version sdk> Le SDK (également appelé « outils ») est un ensemble d’outils gérés servant à écrire et à générer des bibliothèques et des applications .NET. Le SDK inclut, entre autres, la CLI .NET, les compilateurs de langages managés, MSBuild, les cibles et les tâches de génération associées, NuGet et de nouveaux modèles de projet.

  • (4) sdk-manifests/<sdk feature band version> Les noms et versions des ressources requises par une installation facultative de charge de travail sont conservés dans les manifestes de charge de travail stockés dans ce dossier. Le nom du dossier est la version de la bande de fonctionnalités du SDK. Ainsi, pour une version du SDK telle que 7.0.102, ce dossier serait toujours nommé 7.0.100. Lorsqu’une charge de travail est installée, les dossiers suivants sont créés en fonction des besoins pour les ressources de la charge de travail : packs de bibliothèques, métadonnées et packs de modèles. Une distribution peut créer un fichier /metadata/workloads/<sdkfeatureband>/userlocal vide si les charges de travail doivent être installées sous un chemin d’accès utilisateur plutôt que dans le dossier dotnet. Pour plus d’informations, consultez le problème GitHub dotnet/installer#12104.

Le dossier shared contient des frameworks. Un framework partagé fournit un ensemble de bibliothèques à un emplacement central, ce qui permet à différentes applications de les utiliser.

  • (5) shared/Microsoft.NETCore.App/<version runtime> Ce framework contient le runtime .NET et des bibliothèques managées qui le prennent en charge.

  • (6) shared/Microsoft.AspNetCore.{App,All}/<version aspnetcore> Contient les bibliothèques ASP.NET Core. Les bibliothèques sous Microsoft.AspNetCore.App sont développées et prises en charge dans le cadre du projet .NET. Les bibliothèques sous Microsoft.AspNetCore.All sont un sur-ensemble qui contient également des bibliothèques de tiers.

  • (7) La version de l’application <>shared/Microsoft.Desktop.App/ contient les bibliothèques de bureau Windows. Cela n’est pas inclus sur les plateformes autres que Windows.

  • (8) LICENSE.txt,ThirdPartyNotices.txt sont la licence .NET et les licences des bibliothèques de tiers utilisées dans .NET, respectivement.

  • (9, 10) dotnet.1.gz, dotnet dotnet.1.gz est la page du manuel de dotnet. dotnet est un lien symbolique vers l’hôte dotnet (1). Ces fichiers sont installés aux emplacements habituels pour l’intégration du système.

  • (11,12) Microsoft.NETCore.App.Ref,Microsoft.AspNetCore.App.Ref décrivent respectivement l’API d’une x.y version de .NET et ASP.NET Core. Ces packs sont utilisés lors de la compilation pour ces versions cibles.

  • (13) Microsoft.NETCore.App.Host.<rid> contient un binaire natif pour la plateforme rid. Ce binaire est un modèle lors de la compilation d’une application .NET dans un binaire natif pour cette plateforme.

  • (14) Microsoft.WindowsDesktop.App.Ref décrit l’API de x.y la version des applications de bureau Windows. Ces fichiers sont utilisés lors de la compilation pour cette cible. Cela n’est pas fourni sur les plateformes autres que Windows.

  • (15) NETStandard.Library.Ref décrit l’API netstandard x.y. Ces fichiers sont utilisés lors de la compilation pour cette cible.

  • (16) /etc/dotnet/install_location est un fichier qui contient le chemin d’accès complet pour {dotnet_root}. Le chemin d’accès peut se terminer par une nouvelle ligne. Il n’est pas nécessaire d’ajouter ce fichier lorsque la racine est /usr/share/dotnet.

  • (17) templates contiennent les modèles utilisés par le SDK. Par exemple, dotnet new recherche des modèles de projet ici.

  • (18) Microsoft.NETCore.App.Runtime.<rid>/<runtime version>,Microsoft.AspNetCore.App.Runtime.<rid>/<aspnetcore version> Ces fichiers permettent de générer des applications autonomes. Ces répertoires contiennent des liens symboliques vers des fichiers dans (2), (5) et (6).

Les dossiers marqués avec (*) sont utilisés par plusieurs packages. Certains formats de package (par exemple, rpm) requièrent un traitement spécial de ces dossiers. Le chargé de maintenance du package doit s’en occuper.

Le contrôle de version de .NET est basé sur les numéros de version [major].[minor] du composant runtime. La version du SDK utilise les mêmes numéros [major].[minor] et a un [patch] indépendant qui combine la sémantique des fonctionnalités et des correctifs pour le SDK. Par exemple : SDK version 7.0.302 est la deuxième version du correctif de la troisième version des fonctionnalités du SDK qui prend en charge le runtime 7.0. Pour plus d’informations sur le fonctionnement de la gestion des versions, consultez Vue d’ensemble de la gestion des versions .NET.

Le nom de certains packages inclut une partie du numéro de version. Cela vous permet d’installer une version spécifique. Le reste de la version n’est pas inclus dans le nom de version. Ceci permet au Gestionnaire de package du système d’exploitation de mettre à jour les packages (par exemple d’installer automatiquement des correctifs de sécurité). Les gestionnaires de packages pris en charge sont spécifiques de Linux.

La liste suivante répertorie les packages recommandés :

  • dotnet-sdk-[major].[minor] - Installe le dernier SDK pour un runtime spécifique

    • Version :<version du Kit de développement logiciel (SDK)>
    • Exemple : dotnet-sdk-7.0
    • Contient : (3),(4),(18)
    • Dépendances : 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] - Installe un runtime ASP.NET Core spécifique

    • Version :< version du runtime aspnetcore>
    • Exemple : aspnetcore-runtime-7.0
    • Contient : (6)
    • Dépendances : dotnet-runtime-[major].[minor]

  • dotnet-runtime-deps-[major].[minor] (Facultatif) - Installe les dépendances pour l’exécution d’applications autonomes

    • Version :<version du runtime>
    • Exemple : dotnet-runtime-deps-7.0
    • Dépendances : dépendances spécifiques à la distribution

  • dotnet-runtime-[major].[minor] - Installe un runtime spécifique

    • Version :<version du runtime>
    • Exemple : dotnet-runtime-7.0
    • Contient : (5)
    • Dépendances : dotnet-hostfxr-[major].[minor], dotnet-runtime-deps-[major].[minor]

  • dotnet-hostfxr-[major].[minor] - dépendance

    • Version :<version du runtime>
    • Exemple : dotnet-hostfxr-7.0
    • Contient : (2)
    • Dépendances : dotnet-host

  • dotnet-host - dépendance

    • Version :<version du runtime>
    • Exemple : dotnet-host
    • Contient : (1),(8),(9),(10),(16)

  • dotnet-apphost-pack-[major].[minor] - dépendance

    • Version :<version du runtime>
    • Contient : (13)

  • dotnet-targeting-pack-[major].[minor] - Permet de cibler un runtime non récent

    • Version :<version du runtime>
    • Contient : (12)

  • aspnetcore-targeting-pack-[major].[minor] - Permet de cibler un runtime non récent

    • Version :< version du runtime aspnetcore>
    • Contient : (11)

  • netstandard-targeting-pack-[netstandard_major].[netstandard_minor] - Permet de cibler une version netstandard

    • Version :<version du Kit de développement logiciel (SDK)>
    • Contient : (15)

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

    • Version :<version du Kit de développement logiciel (SDK)>
    • Contient : (17)

Les deux meta packages suivants sont facultatifs. Ils apportent de la valeur pour les utilisateurs finaux en ce qu’ils extraitnt le package de niveau supérieur (dotnet-sdk), ce qui simplifie l’installation de l’ensemble complet de packages .NET. Ces meta packages référencent une version spécifique du Kit de développement logiciel (SDK) .NET.

  • dotnet[major] - Installe la version spécifiée du Kit de développement logiciel (SDK)

    • Version :<version du Kit de développement logiciel (SDK)>
    • Exemple : dotnet7
    • Dépendances : dotnet-sdk-[major].[minor]

  • dotnet - Installe une version spécifique du KIT de développement logiciel (SDK) déterminée par les distributions comme étant la version principale, généralement la dernière version disponible

    • Version :<version du Kit de développement logiciel (SDK)>
    • Exemple : dotnet
    • Dépendances : dotnet-sdk-[major].[minor]

Le dotnet-runtime-deps-[major].[minor] nécessite une compréhension des dépendances spécifiques à la distribution. Étant donné que le système de génération distribution peut être en mesure de le dériver automatiquement, le package est facultatif, auquel cas ces dépendances sont ajoutées directement au dotnet-runtime-[major].[minor] Package.

Lorsque le contenu du package se trouve dans un dossier avec version, le nom [major].[minor] du package correspond au nom du dossier avec version. Pour tous les packages, à l’exception netstandard-targeting-pack-[netstandard_major].[netstandard_minor] de, cela correspond également à la version .net.

Les dépendances entre les packages doivent utiliser une valeur égale ou supérieure à la version requise. Par exemple, dotnet-sdk-7.0:7.0.401 nécessite aspnetcore-runtime-7.0 >= 7.0.6. Cela permet à l’utilisateur de mettre à niveau son installation via un package racine (par exemple, dnf update dotnet-sdk-7.0).

La plupart des distributions nécessitent que tous les artefacts soient générés à partir de la source. Ceci a un certain impact sur les packages :

  • Les bibliothèques de tiers sous shared/Microsoft.AspNetCore.All ne peuvent pas être facilement générées à partir de la source. Ce dossier est donc omis du package aspnetcore-runtime.

  • NuGetFallbackFolder est rempli avec des artefacts binaires provenant de nuget.org. Il doit rester vide.

Plusieurs packages dotnet-sdk peuvent fournir les mêmes fichiers pour le NuGetFallbackFolder. Pour éviter des problèmes avec le Gestionnaire de package, ces fichiers doivent être identiques (somme de contrôle, date de modification, etc.).

Déboguer des packages

Le contenu de débogage doit être empaqueté dans des packages nommés « debug » qui suivent le fractionnement du package .NET décrit précédemment dans cet article. Par exemple, le contenu de débogage du package dotnet-sdk-[major].[minor] doit être inclus dans un package nommé dotnet-sdk-dbg-[major].[minor]. Vous devez installer le contenu de débogage dans le même emplacement que les fichiers binaires.

Voici quelques exemples binaires :

Dans le répertoire {dotnet_root}/sdk/<sdk version>, les deux fichiers suivants sont attendus :

  • dotnet.dll – installé avec un package dotnet-sdk-[major].[minor]
  • dotnet.pdb – installé avec un package dotnet-sdk-dbg-[major].[minor]

Dans le répertoire {dotnet_root}/shared/Microsoft.NETCore.App/<runtime version>, les deux fichiers suivants sont attendus :

  • System.Text.Json.dll – installé avec un package dotnet-runtime-[major].[minor]
  • System.Text.Json.pdb – installé avec un package dotnet-runtime-dbg-[major].[minor]

Dans le répertoire {dotnet_root/shared/Microsoft.AspNetCore.App/<aspnetcore version>, les deux fichiers suivants sont attendus :

  • Microsoft.AspNetCore.Routing.dll – installé avec des packages aspnetcore-runtime-[major].[minor]
  • Microsoft.AspNetCore.Routing.pdb – installé avec des packages aspnetcore-runtime-dbg-[major].[minor]

Depuis .NET 8.0, tout le contenu de débogage .NET (fichiers PDB) généré par la génération source est disponible dans un tarball nommé dotnet-symbols-sdk-<version>-<rid>.tar.gz. Cette archive contient des fichiers PDB dans des sous-répertoires correspondant à la structure de répertoires du kit de développement logiciel (SDK) .NET tarball – dotnet-sdk-<version>-<rid>.tar.gz.

Bien que tout le contenu de débogage soit disponible dans le tarball de débogage, tout le contenu de débogage n’est pas aussi important. Les utilisateurs finaux sont davantage intéressés par le contenu des répertoires shared/Microsoft.AspNetCore.App/<aspnetcore version> et shared/Microsoft.NETCore.App/<runtime version>.

Le contenu du kit de développement logiciel (SDK) sous sdk/<sdk version> est utile pour le débogage des boîtes à outils du kit de développement logiciel (SDK) .NET.

Les packages suivants sont les packages de débogage recommandés :

  • aspnetcore-runtime-dbg-[major].[minor] – Installe un contenu de débogage pour un runtime ASP.NET Core spécifique

    • Version :< version du runtime aspnetcore>
    • Exemple : aspnetcore-runtime-dbg-8.0
    • Contient : déboguer du contenu pour (6)
    • Dépendances : aspnetcore-runtime-[major].[minor]

  • dotnet-runtime-dbg-[major].[minor] – Installe le contenu de débogage pour un runtime spécifique

    • Version :<version du runtime>
    • Exemple : dotnet-runtime-dbg-8.0
    • Contient : déboguer du contenu pour (5)
    • Dépendances : dotnet-runtime-[major].[minor]

Le package de débogage suivant est facultatif :

  • dotnet-sdk-dbg-[major].[minor] – Installe un contenu du débogage pour une version spécifique du kit de développement logiciel (SDK)
    • Version :<version du Kit de développement logiciel (SDK)>
    • Exemple : dotnet-sdk-dbg-8.0
    • Contient : déboguer du contenu pour (3), (4), (18)
    • Dépendances : dotnet-sdk-[major].[minor]

Le tarball de débogage contient également du contenu de débogage sous packs. Ce qui représente des copies du contenu sous shared. Dans la disposition .NET, le répertoire packs est utilisé pour la génération d’applications .NET. Aucun scénario de débogage n’existe. Vous ne devez donc pas empaqueter le contenu de débogage sous packs dans le tarball de débogage.

Génération des packages

Le référentiel dotnet/source-build fournit des instructions qui expliquent comment créer un tarball source du Kit SDK .NET et de tous ses composants. La sortie du dépôt de builds sources correspond à la disposition décrite dans la première section de cet article.