Créer des outils .NET qui sont spécifiques au RID, autonomes et AOT

Cet article s’applique à : ✔️ .NET SDK 10 et versions ultérieures

Packager des outils .NET pour des plateformes et des architectures spécifiques afin de distribuer des applications natives, rapides et réduites. Cette fonctionnalité facilite la distribution d’applications optimisées pour les outils en ligne de commande tels que les serveurs MCP ou d’autres utilitaires spécifiques à la plateforme.

Aperçu

À compter du Kit de développement logiciel (SDK) .NET 10, vous pouvez créer des outils .NET qui ciblent des environnements de système d’exploitation spécifiques (représentés par des identificateurs d’exécution (RID)). Ces outils peuvent être les suivants :

Spécifique au RID : compilé pour des systèmes d’exploitation et des architectures particuliers.
Autonome : inclut le runtime .NET et ne nécessite pas d’installation distincte de .NET.
AOT natif : Utilisez la compilation anticipée pour accélérer le démarrage et réduire l’encombrement mémoire.

Les utilisateurs ne remarquent pas de différence lorsqu’ils installent l’outil. L’interface CLI .NET sélectionne et installe automatiquement le meilleur package pour sa plateforme.

Opter pour un emballage spécifique au RID

Pour créer un outil spécifique au RID, configurez votre projet avec l’une des propriétés MSBuild suivantes :

RuntimeIdentifiers, propriété

Permet RuntimeIdentifiers de spécifier les plateformes prises en charge par votre outil :

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <ToolCommandName>mytool</ToolCommandName>
    <RuntimeIdentifiers>win-x64;linux-x64;osx-arm64</RuntimeIdentifiers>
  </PropertyGroup>
</Project>

propriété ToolPackageRuntimeIdentifiers

Vous pouvez également utiliser cette option ToolPackageRuntimeIdentifiers pour la configuration RID spécifique à l’outil :

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <PublishAot>true</PublishAot>
    <ToolCommandName>mytool</ToolCommandName>
    <ToolPackageRuntimeIdentifiers>win-x64;linux-x64;osx-arm64</ToolPackageRuntimeIdentifiers>
  </PropertyGroup>
</Project>

Utilisez une liste délimitée par des points-virgules de valeurs RID. Pour obtenir la liste des identificateurs d’exécution, consultez le catalogue RID.

À quel moment utiliser `RuntimeIdentifiers` par rapport à `ToolPackageRuntimeIdentifiers`

À la fois RuntimeIdentifiers et ToolPackageRuntimeIdentifiers intègrent votre outil dans un emballage spécifique au RID, mais ont des finalités légèrement différentes :

Utilisez RuntimeIdentifiers quand :

Vous souhaitez que le projet crée et publie des applications spécifiques au RID en général (pas seulement en tant qu’outil).
Vous ciblez principalement CoreCLR (non-AOT) ou vous souhaitez le comportement du KIT de développement logiciel (SDK) standard où un seul dotnet pack produit plusieurs packages spécifiques au RID.
Vous pouvez conditionner PublishAot pour un sous-ensemble de RID, mais vous souhaitez toujours un package CoreCLR pour chaque RID dans RuntimeIdentifiers.

Utilisez ToolPackageRuntimeIdentifiers quand :

Vous souhaitez définir un comportement spécifique au RID uniquement pour l’empaquetage d’outils, sans modifier la façon dont le projet s’appuie sur d’autres scénarios de déploiement.
Vous utilisez Native AOT et envisagez de générer manuellement des fichiers binaires AOT par RID avec dotnet pack -r <RID>.
Vous souhaitez un modèle hybride où certains RID obtiennent AOT natif et d'autres se replient sur une implémentation CoreCLR portable.

Notes:

Le package de pointeur de niveau supérieur spécifie les packages spécifiques au RID disponibles. Si vous spécifiez ToolPackageRuntimeIdentifiers, il détermine les RID de l’outil ; sinon, RuntimeIdentifiers est utilisé.
ToolPackageRuntimeIdentifiers doit être égal à ou à un sous-ensemble des RID dans RuntimeIdentifiers
Quand PublishAot=true, les packages spécifiques au RID sont générés uniquement lorsque vous packez pour un RID spécifique (par exemple, dotnet pack -r linux-x64).
Les builds AOT natives (PublishAot=true) sont prises en charge uniquement lorsque le système d’exploitation de build et le système d’exploitation cible sont identiques.

Empaqueter votre outil

Le processus d’empaquetage diffère selon que vous utilisez la compilation AOT. Pour générer un package NuGet ou un fichier .nupkg à partir du projet, exécutez la commande dotnet pack .

Outils propres à RID et autonomes

Exécutez dotnet pack une seule fois :

dotnet pack

Cette commande crée plusieurs packages NuGet :

Un package pour chaque RID : <packageName>.<RID>.<packageVersion>.nupkg
- Exemple : mytool.win-x64.1.0.0.nupkg
- Exemple : mytool.linux-x64.1.0.0.nupkg
- Exemple : mytool.osx-arm64.1.0.0.nupkg
Un paquet de pointeur indépendant de RID : <packageName>.<packageVersion>.nupkg
- Exemple : mytool.1.0.0.nupkg

Outils AOT

Pour les outils avec la compilation AOT (<PublishAot>true</PublishAot>), vous devez effectuer un pack distinct pour chaque plateforme.

Configuration requise pour la plateforme native AOT

La compilation AOT native nécessite que le système d’exploitation (OS) du SDK RID corresponde au système d’exploitation du RID cible. Le Kit de développement logiciel (SDK) peut compiler plusieurs architectures (par exemple, x64 à ARM64), mais pas entre les systèmes d’exploitation (par exemple, Windows vers Linux).

Cela signifie que vous avez plusieurs options pour créer des packages AOT natifs :

Compiler uniquement pour votre machine de développement : prise en charge du Native AOT uniquement pour le système d'exploitation sur lequel vous développez.
Utilisez des conteneurs pour les builds Linux : si vous êtes sur macOS ou Windows, utilisez des conteneurs pour compiler plusieurs fois pour Linux. Par exemple, utilisez des mcr.microsoft.com/dotnet/sdk:10.0-noble-aot images conteneur.
Fédérer votre build sur des machines : utilisez des systèmes CI/CD tels que GitHub Actions ou Azure DevOps Pipelines pour créer sur différents systèmes d’exploitation.

Vous n’avez pas besoin de générer tous les packages spécifiques au RID sur le même ordinateur ou en même temps. Vous devez simplement les générer et les publier avant de publier le package de niveau supérieur.

Empaquetage des outils AOT natifs

Empaquetez le package de niveau supérieur une seule fois (sur n’importe quelle plateforme) :

dotnet pack

Pack pour chaque RID spécifique sur la plateforme correspondante, par exemple :

dotnet pack -r linux-x64

Vous devez exécuter chaque commande de pack spécifique à RID sur une plateforme où le système d’exploitation correspond au système d’exploitation rid cible. Pour plus d’informations sur les prérequis pour la compilation AOT native, consultez déploiement AOT natif.

Lorsque vous définissez PublishAot sur true, le comportement d’empaquetage change :

dotnet pack produit le package de pointeur de niveau supérieur (type de DotnetToolpackage).
Les packages AOT spécifiques au RID sont produits uniquement lorsque vous passez explicitement -r <RID>, par exemple, dotnet pack -r linux-x64 ou dotnet pack -r osx-arm64.

Modèle d’empaquetage AOT + CoreCLR hybride (exemple)

Certains outils veulent le meilleur des deux mondes :

AOT natif pour un sous-ensemble de plateformes à priorité élevée (en fonction de l’outil).
Une solution de repli CoreCLR portable qui fonctionne sur les plateformes non ciblées par les builds AOT natives.

Vous pouvez obtenir ce modèle « hybride » avec le modèle suivant :

Configurez l’outil pour les AOT natifs et les RID spécifiques à l’outil.

Dans votre fichier projet, utilisez ToolPackageRuntimeIdentifiers et activez PublishAot.

Par exemple:
```
<ToolPackageRuntimeIdentifiers>osx-arm64;linux-arm64;linux-x64;any</ToolPackageRuntimeIdentifiers>
<PublishAot>true</PublishAot>
```
Créez le package de pointeur.

Exécutez dotnet pack une seule fois (sur n’importe quelle plateforme) pour générer le package de niveau supérieur qui pointe vers les packages spécifiques au RID :
```
dotnet pack
```
Générez des packages AOT natifs pour les RID sélectionnés.

La compilation AOT native nécessite la compilation sur la plateforme cible. Générez chaque package RID compatible AOT sur la plateforme correspondante à l'aide de dotnet pack -r <RID>.

Par exemple:

dotnet pack -r linux-x64

Générez un package de secours CoreCLR.

Pour fournir un recours universel, emballez le any RID sans AOT :
```
dotnet pack -r any -p:PublishAot=false
```
Cela produit un package CoreCLR portable (par exemple) yourtool.any.<version>.nupkgqui peut s’exécuter sur des plateformes qui n’ont pas de build AOT dédiée.

Note

Vous pouvez également utiliser les .NET SDK 10.0-noble-aot images conteneur pour générer et empaqueter des outils AOT natifs Linux à partir de n’importe quel hôte prenant en charge les conteneurs Linux. Par exemple:

mcr.microsoft.com/dotnet/sdk:10.0-noble-aot

Cela est utile lorsque votre ordinateur de développement n’exécute pas Linux en mode natif.

Dans cette configuration hybride :

Le package de pointeur (yourtool.<version>.nupkg) fait référence aux deux :
- Packages AOT natifs spécifiques au RID (par exemple, yourtool.osx-arm64, yourtool.linux-x64).
- Le package any CoreCLR comme secours.
L’interface CLI .NET sélectionne automatiquement le package le plus approprié pour la plateforme de l’utilisateur lorsqu’il s’exécute dotnet tool install ou dnx.

Exemple : `dotnet10-hybrid-tool`

Le dotnet10-hybrid-tool référentiel illustre ce modèle d’empaquetage hybride avec des packages AOT natifs pour osx-arm64, linux-arm64et linux-x64, ainsi qu’un package de secours CoreCLR pour le any RID (utilisé, par exemple, sur Windows quand aucune build AOT n’est disponible).

Vous pouvez installer et essayer l’outil vous-même :

dotnet tool install -g dotnet10-hybrid-tool
dotnet10-hybrid-tool

L’outil signale sa description de l’infrastructure d’exécution, son identificateur d’exécution (RID) et le mode de compilation (AOT natif ou CoreCLR).

Exemple de sortie sur une plateforme avec AOT natif :

Hi, I'm a 'DotNetCliTool v2' tool!
Yes, I'm quite fancy.

Version: .NET 10.0.2
RID: osx-arm64
Mode: Native AOT

Exemple de sortie sur une plateforme à l’aide du fallback CoreCLR :

Hi, I'm a 'DotNetCliTool v2' tool!
Yes, I'm quite fancy.

Version: .NET 10.0.2
RID: win-x64
Mode: CoreCLR

Cela permet d’expérimenter des outils compilés AOT spécifiques à un RID et le comportement de repli de CoreCLR.

Publier votre outil

Lors de la publication de packages d’outils spécifiques au RID, l’interface CLI .NET utilise le numéro de version du package de niveau supérieur pour sélectionner les packages spécifiques au RID correspondants. En d’autres termes :

Tous les packages spécifiques au RID doivent avoir exactement la même version que le package de niveau supérieur.
Tous les packages doivent être publiés dans votre flux avant que le package de niveau supérieur ne soit disponible.

Pour garantir un processus de publication fluide :

Publiez tout d’abord tous les packages spécifiques au RID :

dotnet nuget push yourtool.win-x64.1.0.0.nupkg
dotnet nuget push yourtool.linux-x64.1.0.0.nupkg
dotnet nuget push yourtool.osx-arm64.1.0.0.nupkg
dotnet nuget push yourtool.any.1.0.0.nupkg

Publiez le package de niveau supérieur en dernier :
```
dotnet nuget push yourtool.1.0.0.nupkg
```

La publication du package de niveau supérieur garantit que tous les packages spécifiques au RID référencés sont disponibles lorsque les utilisateurs installent votre outil. Si un utilisateur installe votre outil avant la publication de tous les packages RID, l’installation échoue.

Installer et exécuter des outils

Si un outil utilise un empaquetage spécifique au RID est un détail d’implémentation transparent pour les utilisateurs. Vous installez et exécutez les outils de la même façon, que le développeur de l’outil ait choisi un empaquetage spécifique au RID.

Pour installer un outil globalement :

dotnet tool install -g mytool

Une fois installé, vous pouvez l’appeler directement :

mytool

Vous pouvez également utiliser l’assistance dnx , qui se comporte de la même façon npx que dans l’écosystème Node.js : il télécharge et lance un outil dans un seul mouvement s’il n’est pas déjà présent :

dnx mytool

Lorsqu’un outil utilise un empaquetage spécifique au RID, l’interface CLI .NET sélectionne automatiquement le package approprié pour votre plateforme. Vous n’avez pas besoin de spécifier un RID : l’interface CLI l’déduit à partir de votre système et télécharge le package propre au RID approprié.

Voir aussi

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-01-24