Tutoriel : Installer et utiliser un outil local .NET à l’aide de l’interface CLI .NET

Article
05/10/2023

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

Ce tutoriel vous explique comment installer et utiliser un outil local. Vous utilisez un outil que vous créez dans le premier tutoriel de cette série.

Prérequis

Suivez le premier tutoriel de cette série.
Installez le runtime .NET Core 2.1.

Pour ce tutoriel, vous installez et utilisez un outil qui cible .NET Core 2.1. Vous devez donc installer ce runtime sur votre ordinateur. Pour installer le runtime 2.1, accédez à la page de téléchargement .NET Core 2.1 et recherchez le lien d’installation du runtime dans la colonne Applications d’exécution - Runtime.

Créer un fichier manifeste

Pour installer un outil pour l’accès local uniquement (pour le répertoire actif et les sous-répertoires), il doit être ajouté à un fichier manifeste.

À partir du dossier microsoft.botsay, naviguez jusqu’au dossier du référentiel :

cd ..

Créez un fichier manifeste en exécutant la commande dotnet new :

dotnet new tool-manifest

La sortie indique la création réussie du fichier.

The template "Dotnet local tool manifest file" was created successfully.

Le fichier .config/dotnet-tools.json n’a pas encore d’outils :

{
  "version": 1,
  "isRoot": true,
  "tools": {}
}

Les outils répertoriés dans un fichier manifeste sont disponibles pour le répertoire actif et les sous-répertoires. Le répertoire actif est celui qui contient le répertoire .config avec le fichier manifeste.

Lorsque vous utilisez une commande CLI qui fait référence à un outil local, le Kit de développement logiciel (SDK) recherche un fichier manifeste dans le répertoire actif et les répertoires parents. S’il trouve un fichier manifeste, mais que le fichier n’inclut pas l’outil référencé, il poursuit la recherche dans les répertoires parents. La recherche se termine lorsqu’elle trouve l’outil référencé ou qu’elle trouve un fichier manifeste avec isRoot défini sur true.

Installer botsay en tant qu’outil local

Installez l’outil à partir du package que vous avez créé dans le premier tutoriel :

dotnet tool install --add-source ./microsoft.botsay/nupkg microsoft.botsay

Cette commande ajoute l’outil au fichier manifeste que vous avez créé à l’étape précédente. La sortie de commande indique le fichier manifeste dans lequel se trouve l’outil nouvellement installé :

You can invoke the tool from this directory using the following command:
'dotnet tool run botsay' or 'dotnet botsay'
Tool 'microsoft.botsay' (version '1.0.0') was successfully installed.
Entry is added to the manifest file /home/name/repository/.config/dotnet-tools.json

Le fichier .config/dotnet-tools.json dispose désormais d’un outil :

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    }
  }
}

Utiliser l’outil

Appelez l’outil en exécutant la commande dotnet tool run à partir du dossier référentiel :

dotnet tool run botsay hello from the bot

Restaurer un outil local installé par d’autres utilisateurs

Vous installez généralement un outil local dans le répertoire racine du référentiel. Après avoir vérifié le fichier manifeste dans le référentiel, d’autres développeurs peuvent obtenir le dernier fichier manifeste. Pour installer tous les outils répertoriés dans le fichier manifeste, ils peuvent exécuter une commande dotnet tool restore.

Ouvrez le fichier .config/dotnet-tools.json et remplacez le contenu par le code JSON suivant :

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

Enregistrez vos modifications.

Cette modification est identique à l’obtention de la dernière version à partir du référentiel une fois que quelqu’un d’autre a installé le package dotnetsay pour le répertoire du projet.

Exécutez la commande dotnet tool restore.

dotnet tool restore

La commande produit une sortie comme l’exemple suivant :

Tool 'microsoft.botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

Vérifiez que les outils sont disponibles :

dotnet tool list

La sortie est une liste de packages et de commandes, comme dans l’exemple suivant :

Package Id      Version      Commands       Manifest
--------------------------------------------------------------------------------------------
microsoft.botsay 1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay        2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Testez les outils :

dotnet tool run dotnetsay hello from dotnetsay
dotnet tool run botsay hello from botsay

Mettre à jour un outil local

La version installée de l’outil local dotnetsay est 2.1.3. Utilisez la commande dotnet tool update pour mettre à jour l’outil vers la dernière version.

dotnet tool update dotnetsay

La sortie indique le nouveau numéro de version :

Tool 'dotnetsay' was successfully updated from version '2.1.3' to version '2.1.7'
(manifest file /home/name/repository/.config/dotnet-tools.json).

La commande de mise à jour recherche le premier fichier manifeste qui contient l’identifiant de package et le met à jour. S’il n’existe aucun identifiant de package de ce type dans un fichier manifeste qui se trouve dans l’étendue de la recherche, le Kit de développement logiciel (SDK) ajoute une nouvelle entrée au fichier manifeste le plus proche. L’étendue de recherche se trouve via les répertoires parents jusqu’à ce qu’un fichier manifeste avec isRoot = true soit trouvé.

Supprimer les outils locaux

Supprimez les outils installés en exécutant la commande dotnet tool uninstall :

dotnet tool uninstall microsoft.botsay

dotnet tool uninstall dotnetsay

Dépanner

Si vous recevez un message d’erreur en suivant le tutoriel, consultez Résoudre les problèmes d’utilisation des outils .NET.

Voir aussi

Pour plus d’informations, consultez Outils .NET