チュートリアル: .NET CLI を使用して .NET ツールを作成するTutorial: Create a .NET tool using the .NET CLI

この記事の対象: ✔️ .NET Core 2.1 SDK 以降のバージョンThis article applies to: ✔️ .NET Core 2.1 SDK and later versions

このチュートリアルでは、.NET ツールを作成およびパッケージ化する方法について説明します。This tutorial teaches you how to create and package a .NET tool. .NET CLI では、他のユーザーがインストールおよび実行できる、コンソール アプリケーションをツールとして作成できます。The .NET CLI lets you create a console application as a tool, which others can install and run. .NET ツールは、.NET CLI でインストールする NuGet パッケージです。.NET tools are NuGet packages that are installed from the .NET CLI. ツールの詳細については、.NET ツールの概要に関する記事を参照してください。For more information about tools, see .NET tools overview.

作成するツールは、メッセージを入力として受け取り、ロボットの画像を作成するテキスト行と共にメッセージを表示するコンソール アプリケーションです。The tool that you'll create is a console application that takes a message as input and displays the message along with lines of text that create the image of a robot.

これは、3 つのチュートリアル シリーズの第 1 回です。This is the first in a series of three tutorials. このチュートリアルでは、ツールを作成してパッケージ化します。In this tutorial, you create and package a tool. 次の 2 つのチュートリアルでは、グローバル ツールとしてツールを使用する方法と、ローカル ツールとしてツールを使用する方法を説明します。In the next two tutorials you use the tool as a global tool and use the tool as a local tool.

必須コンポーネントPrerequisites

  • .NET Core SDK 3.1 以降のバージョン。.NET Core SDK 3.1 or a later version.

    このチュートリアルと次のグローバル ツールのチュートリアルは、.NET Core SDK 2.1 以降のバージョンに適用されます。これは、そのバージョンからグローバル ツールを使用できるようになったためです。This tutorial and the following tutorial for global tools apply to .NET Core SDK 2.1 and later versions because global tools are available starting in that version. ただし、このチュートリアルでは、ローカル ツールのチュートリアルに進むことができるように、3.1 以降がインストールされていることを前提としています。But this tutorial assumes you have installed 3.1 or later so that you have the option of continuing on to the local tools tutorial. ローカル ツールは .NET Core SDK 3.0 以降で使用できます。Local tools are available starting in .NET Core SDK 3.0. ツールを作成する手順は、グローバル ツールとローカル ツールのどちらとして使用する場合でも同じです。The procedures for creating a tool are the same whether you use it as a global tool or as a local tool.

  • ユーザーが選んだテキスト エディターまたはコード エディター。A text editor or code editor of your choice.

プロジェクトを作成するCreate a project

  1. コマンド プロンプトを開き、repository という名前のフォルダーを作成します。Open a command prompt and create a folder named repository.

  2. repository フォルダーに移動し、次のコマンドを入力します。Navigate to the repository folder and enter the following command:

    dotnet new console -n microsoft.botsay
    

    このコマンドを実行すると、repository フォルダーの下に microsoft.botsay という名前の新しいフォルダーが作成されます。The command creates a new folder named microsoft.botsay under the repository folder.

  3. microsoft.botsay フォルダーに移動します。Navigate to the microsoft.botsay folder.

    cd microsoft.botsay
    

コードの追加Add the code

  1. コード エディターを使用して Program.cs ファイルを開きます。Open the Program.cs file with your code editor.

  2. 次の using ディレクティブをファイルの先頭に追加します。Add the following using directive to the top of the file:

    using System.Reflection;
    
  3. Main メソッドを次のコードに置き換えて、アプリケーションのコマンドライン引数を処理します。Replace the Main method with the following code to process the command-line arguments for the 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));
    }
    

    引数が渡されなかった場合、短いヘルプ メッセージが表示されます。If no arguments are passed, a short help message is displayed. それ以外の場合、次の手順で作成する ShowBot メソッドを呼び出すと、すべての引数が 1 つの文字列に連結され、出力されます。Otherwise, all of the arguments are concatenated into a single string and printed by calling the ShowBot method that you create in the next step.

  4. 文字列パラメーターを受け取る ShowBot という新しいメソッドを追加します。Add a new method named ShowBot that takes a string parameter. このメソッドを実行すると、テキストの行を使用してメッセージとロボットの画像を出力されます。The method prints out the message and an image of a robot using lines of text.

    static void ShowBot(string message)
    {
        string bot = $"\n        {message}";
        bot += @"
        __________________
                          \
                           \
                              ....
                              ....'
                               ....
                            ..........
                        .............'..'..
                     ................'..'.....
                   .......'..........'..'..'....
                  ........'..........'..'..'.....
                 .'....'..'..........'..'.......'.
                 .'..................'...   ......
                 .  ......'.........         .....
                 .    _            __        ......
                ..    #            ##        ......
               ....       .                 .......
               ......  .......          ............
                ................  ......................
                ........................'................
               ......................'..'......    .......
            .........................'..'.....       .......
         ........    ..'.............'..'....      ..........
       ..'..'...      ...............'.......      ..........
      ...'......     ...... ..........  ......         .......
     ...........   .......              ........        ......
    .......        '...'.'.              '.'.'.'         ....
    .......       .....'..               ..'.....
       ..       ..........               ..'........
              ............               ..............
             .............               '..............
            ...........'..              .'.'............
           ...............              .'.'.............
          .............'..               ..'..'...........
          ...............                 .'..............
           .........                        ..............
            .....
    ";
        Console.WriteLine(bot);
    }
    
  5. 変更内容を保存します。Save your changes.

アプリケーションをテストするTest the application

プロジェクトを実行して出力を確認します。Run the project and see the output. 次のようにコマンド ラインを変えて、異なる結果を表示してみてください。Try these variations at the command line to see different results:

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

区切り記号 -- の後の引数は、すべてアプリケーションに渡されます。All arguments after the -- delimiter are passed to your application.

ツールをパッケージ化するPackage the tool

アプリケーションをパッケージ化してツールとして配布する前に、プロジェクト ファイルを変更する必要があります。Before you can pack and distribute the application as a tool, you need to modify the project file.

  1. microsoft.botsay.csproj ファイルを開き、3 つの新しい XML ノードを <PropertyGroup> ノードの最後に追加します。Open the microsoft.botsay.csproj file and add three new XML nodes to the end of the <PropertyGroup> node:

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

    <ToolCommandName> は、インストール後にツールを呼び出すコマンドを指定する省略可能な要素です。<ToolCommandName> is an optional element that specifies the command that will invoke the tool after it's installed. この要素を指定しない場合、ツールのコマンド名は、 .csproj 拡張子のないプロジェクト ファイル名になります。If this element isn't provided, the command name for the tool is the project file name without the .csproj extension.

    <PackageOutputPath> は、NuGet パッケージが生成される場所を決定する省略可能な要素です。<PackageOutputPath> is an optional element that determines where the NuGet package will be produced. NuGet パッケージは、.NET Core CLI でツールのインストールに使用されるものです。The NuGet package is what the .NET Core CLI uses to install your tool.

    プロジェクト ファイルは次の例のようになります。The project file now looks like the following example:

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
    
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.1</TargetFramework>
    
        <PackAsTool>true</PackAsTool>
        <ToolCommandName>botsay</ToolCommandName>
        <PackageOutputPath>./nupkg</PackageOutputPath>
    
      </PropertyGroup>
    
    </Project>
    
  2. dotnet pack コマンドを実行して、NuGet パッケージを作成します。Create a NuGet package by running the dotnet pack command:

    dotnet pack
    

    microsoft.botsay.1.0.0.nupkg ファイルは、microsoft.botsay.csproj ファイルの <PackageOutputPath> 値で識別されるフォルダー (この例では、 ./nupkg フォルダー) に作成されます。The microsoft.botsay.1.0.0.nupkg file is created in the folder identified by the <PackageOutputPath> value from the microsoft.botsay.csproj file, which in this example is the ./nupkg folder.

    ツールをリリースする場合は、https://www.nuget.org にアップロードすることができます。When you want to release a tool publicly, you can upload it to https://www.nuget.org. NuGet 上でツールを使用できるようになると、開発者は dotnet tool install コマンドを使用してツールをインストールできます。Once the tool is available on NuGet, developers can install the tool by using the dotnet tool install command. このチュートリアルでは、ローカルの nupkg フォルダーからパッケージを直接インストールするため、NuGet にパッケージをアップロードする必要はありません。For this tutorial you install the package directly from the local nupkg folder, so there's no need to upload the package to NuGet.

トラブルシューティングTroubleshoot

チュートリアルの実行中にエラー メッセージが表示された場合は、「.NET ツールの使用に関する問題のトラブルシューティング」を参照してください。If you get an error message while following the tutorial, see Troubleshoot .NET tool usage issues.

次の手順Next steps

このチュートリアルでは、コンソール アプリケーションを作成し、ツールとしてパッケージ化しました。In this tutorial, you created a console application and packaged it as a tool. このツールをグローバル ツールとして使用する方法については、次のチュートリアルに進んでください。To learn how to use the tool as a global tool, advance to the next tutorial.

必要に応じて、グローバル ツール チュートリアルをスキップし、ローカル ツール チュートリアルに直接移動できます。If you prefer, you can skip the global tools tutorial and go directly to the local tools tutorial.