Tutoriel : Créer un outil .NET à l’aide de l’interface CLI .NET

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

Ce tutoriel vous explique comment créer et empaqueter un outil .NET. L’interface CLI .NET vous permet de créer une application console en tant qu’outil que d’autres peuvent installer et exécuter. Les outils .NET sont des packages NuGet installés à partir de l’interface CLI .NET. Pour plus d’informations sur les outils, consultez la vue d’ensemble des outils .NET.

L’outil que vous allez créer est une application console qui prend un message comme entrée et l’affiche avec des lignes de texte qui créent l’image d’un robot.

Il s’agit du premier d’une série de trois tutoriels. Dans ce tutoriel, vous allez créer et empaqueter un outil. Dans les deux tutoriels suivants, vous utiliserez l’outil comme outil global et utiliserez l’outil comme outil local. Les procédures de création d’un outil sont identiques si vous l’utilisez en tant qu’outil global ou en tant qu’outil local.

Prérequis

  • SDK .NET 6.0.100 ou version ultérieure.

    Ce tutoriel utilise le Kit de développement logiciel (SDK) .NET 6.0, mais les outils globaux sont disponibles à partir du SDK .NET Core 2.1. Les outils locaux sont disponibles à partir du SDK .NET Core 3.0.

  • Un éditeur de texte ou un éditeur de code de votre choix.

Création d’un projet

  1. Ouvrez une invite de commandes et créez un dossier nommé référentiel.

  2. Accédez au dossier référentiel, puis entrez la ligne de commande suivante :

    dotnet new console -n microsoft.botsay -f net6.0
    

    La commande crée un nouveau dossier nommé microsoft.botsay sous le dossier référentiel .

    Notes

    Pour ce tutoriel, vous créez un outil qui cible .NET 6.0. Pour cibler une autre infrastructure, modifiez l’option -f|--framework . Pour cibler plusieurs infrastructures, remplacez l’élément TargetFramework par un élément TargetFrameworks dans le fichier projet, comme illustré dans l’exemple suivant :

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFrameworks>net8.0;net6.0</TargetFrameworks>
      </PropertyGroup>
    </Project>
    
  3. Accédez au dossier microsoft.botsay.

    cd microsoft.botsay
    

Ajouter le code

  1. Ouvrez le fichier Program.cs avec votre éditeur de code.

  2. Remplacez le code dans Program.cs par le code suivant :

    using System.Reflection;
    
    namespace microsoft.botsay;
    
    internal class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
        }
    }
    

    La directive using System.Reflection; est nécessaire pour le code qui sera ajouté à l’étape suivante.

  3. Remplacez la méthode Main par le code suivant afin de traiter les arguments de ligne de commande pour votre application.

    static void Main(string[] args)
    {
        if (args.Length == 0)
        {
            var versionString = Assembly.GetEntryAssembly()?
                                    .GetCustomAttribute<AssemblyInformationalVersionAttribute>()?
                                    .InformationalVersion
                                    .ToString();
    
            Console.WriteLine($"botsay v{versionString}");
            Console.WriteLine("-------------");
            Console.WriteLine("\nUsage:");
            Console.WriteLine("  botsay <message>");
            return;
        }
    
        ShowBot(string.Join(' ', args));
    }
    

    Si aucun argument n’est passé, un court message d’aide s’affiche. Autrement, tous les arguments sont concaténés en une seule chaîne et imprimés en appelant la méthode ShowBot que vous créez à l’étape suivante.

  4. Ajoutez une nouvelle méthode nommée ShowBot qui accepte un paramètre de chaîne. La méthode imprime le message et l’image d’un robot à l’aide de lignes de texte.

    static void ShowBot(string message)
    {
        string bot = $"\n        {message}";
        bot += @"
        __________________
                          \
                           \
                              ....
                              ....'
                               ....
                            ..........
                        .............'..'..
                     ................'..'.....
                   .......'..........'..'..'....
                  ........'..........'..'..'.....
                 .'....'..'..........'..'.......'.
                 .'..................'...   ......
                 .  ......'.........         .....
                 .    _            __        ......
                ..    #            ##        ......
               ....       .                 .......
               ......  .......          ............
                ................  ......................
                ........................'................
               ......................'..'......    .......
            .........................'..'.....       .......
         ........    ..'.............'..'....      ..........
       ..'..'...      ...............'.......      ..........
      ...'......     ...... ..........  ......         .......
     ...........   .......              ........        ......
    .......        '...'.'.              '.'.'.'         ....
    .......       .....'..               ..'.....
       ..       ..........               ..'........
              ............               ..............
             .............               '..............
            ...........'..              .'.'............
           ...............              .'.'.............
          .............'..               ..'..'...........
          ...............                 .'..............
           .........                        ..............
            .....
    ";
        Console.WriteLine(bot);
    }
    
  5. Enregistrez vos modifications.

Test de l’application

Exécutez le projet et observez le résultat. Essayez ces variantes sur la ligne de commande pour afficher différents résultats :

dotnet run
dotnet run -- "Hello from the bot"
dotnet run -- Hello from the bot

Tous les arguments après le délimiteur -- sont passés à votre application.

Empaqueter l’outil

Avant de pouvoir empaqueter et distribuer l’application en tant qu’outil, vous devez modifier le fichier projet.

  1. Ouvrez le fichier microsoft.botsay.csproj et ajoutez trois nouveaux nœuds XML à la fin du nœud <PropertyGroup> :

    <PackAsTool>true</PackAsTool>
    <ToolCommandName>botsay</ToolCommandName>
    <PackageOutputPath>./nupkg</PackageOutputPath>
    

    <ToolCommandName> est un élément facultatif qui spécifie la commande qui appellera l’outil après son installation. Si cet élément n’est pas fourni, le nom de commande de l’outil correspond au nom de l’assembly, soit, en général, le nom du fichier projet sans l’extension .csproj.

    <PackageOutputPath> est un élément facultatif qui détermine où le package NuGet sera généré. Le package NuGet est ce que l’interface CLI .NET utilise pour installer votre outil.

    Le fichier projet ressemble maintenant à l’exemple suivant :

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
    
        <OutputType>Exe</OutputType>
        <TargetFramework>net6.0</TargetFramework>
    
        <PackAsTool>true</PackAsTool>
        <ToolCommandName>botsay</ToolCommandName>
        <PackageOutputPath>./nupkg</PackageOutputPath>
    
      </PropertyGroup>
    
    </Project>
    
  2. Créez un package NuGet en exécutant la commande dotnet pack :

    dotnet pack
    

    Le fichier microsoft.botsay.1.0.0.nupkgest créé dans le dossier identifié par la valeur <PackageOutputPath> du fichier microsoft.botsay.csproj, qui dans cet exemple est le dossier ./nupkg .

    Lorsque vous voulez distribuer un outil publiquement, chargez-le sur https://www.nuget.org. Une fois l’outil disponible sur NuGet, les développeurs peuvent installer l’outil à l’aide de la commande dotnet tool install. Pour ce tutoriel, vous installez le package directement à partir du dossier nupkg local. Vous n’avez donc pas besoin de charger le package sur NuGet.

Dépanner

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

Étapes suivantes

Dans ce tutoriel, vous avez créé une application console et l’avez empaquetée en tant qu’outil. Pour savoir comment utiliser l’outil comme outil global, passez au tutoriel suivant.

Si vous préférez, vous pouvez ignorer le tutoriel sur les outils globaux et accéder directement au didacticiel sur les outils locaux.