.NET Core CLI を使用して .NET Core グローバル ツールを作成するCreate a .NET Core Global Tool using the .NET Core CLI

この記事では、.NET Core グローバル ツールを作成してパッケージ化する方法について説明します。This article teaches you how to create and package a .NET Core Global Tool. .NET Core CLI を使用すると、他のユーザーが簡単にインストールして実行できるコンソール アプリケーションをグローバル ツールとして作成できます。The .NET Core CLI allows you to create a console application as a Global Tool, which others can easily install and run. .NET Core グローバル ツールは、.NET Core CLI からインストールされる NuGet パッケージです。.NET Core Global Tools are NuGet packages that are installed from the .NET Core CLI. グローバル ツールの詳細については、「.NET Core グローバル ツールの概要」を参照してください。For more information about Global Tools, see .NET Core Global Tools overview.

このトピックの対象: ✓ .NET Core 2.1 SDK 以降のバージョンThis topic applies to: ✓ .NET Core 2.1 SDK and later versions

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

この記事では、プロジェクトの作成と管理に .NET Core CLI を使用します。This article uses the .NET Core CLI to create and manage a project.

ここでの例のツールは、ASCII ボットを生成してメッセージを出力するコンソール アプリケーションです。Our example tool will be a console application that generates an ASCII bot and prints a message. まず、新しい .NET Core コンソール アプリケーションを作成します。First, create a new .NET Core Console Application.

dotnet new console -o botsay

前のコマンドで作成した botsay ディレクトリに移動します。Navigate to the botsay directory created by the previous command.

コードの追加Add the code

vimVisual Studio Code など、使い慣れたテキスト エディターで Program.cs ファイルを開きます。Open the Program.cs file with your favorite text editor, such as vim or Visual Studio Code.

次の using ディレクティブをファイルの先頭に追加すると、アプリケーションのバージョン情報を表示するコードを短くすることができます。Add the following using directive to the top of the file, this helps shorten the code to display the version information of the application.

using System.Reflection;

次に、Main メソッドに移動します。Next, move down to the Main method. メソッドを次のコードに置き換えて、アプリケーションのコマンドライン引数を処理します。Replace the method with the following code to process the command-line arguments for your application. 引数が渡されなかった場合、短いヘルプ メッセージが表示されます。If no arguments were passed, a short help message is displayed. それ以外の場合、それらの引数はすべて文字列に変換され、ボットで出力されます。Otherwise, all of those arguments are transformed into a string and printed with the bot.

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));
}

ボットを作成するCreate the bot

次に、文字列パラメーターを受け取る ShowBot という新しいメソッドを追加します。Next, add a new method named ShowBot that takes a string parameter. このメソッドは、メッセージと ASCII ボットを出力します。This method prints out the message and the ASCII bot. ASCII ボットのコードは、dotnetbot サンプルの一部です。The ASCII bot code was taken from the dotnetbot sample.

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

ツールをテストするTest the tool

プロジェクトを実行して出力を確認します。Run the project and see the output. 次のようにコマンドラインを変えて、異なる結果を表示してみてください。Try these variations of 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.

グローバル ツールを設定するSetup the global tool

アプリケーションをパッケージ化してグローバル ツールとして配布する前に、プロジェクト ファイルを変更する必要があります。Before you can pack and distribute the application as a Global Tool, you need to modify the project file. botsay.csproj ファイルを開き、3 つの新しい XML ノードを <Project><PropertyGroup> ノードに追加します。Open the botsay.csproj file and add three new XML nodes to the <Project><PropertyGroup> node:

  • <PackAsTool>
    [必須] アプリケーションがグローバル ツールとしてインストールされるようにパッケージ化されることを示します。[REQUIRED] Indicates that the application will be packaged for install as a Global Tool.

  • <ToolCommandName>
    [省略可能] ツールの代替名。指定しない場合、プロジェクト ファイル名に従ってツールのコマンド名が付けられます。[OPTIONAL] An alternative name for the tool, otherwise the command name for the tool will be named after the project file. 1 つのパッケージに複数のツールを含めることができます。一意のわかりやすい名前を選択すると、同じパッケージ内の他のツールと区別しやすくなります。You can have multiple tools in a package, choosing a unique and friendly name helps differentiate from other tools in the same package.

  • <PackageOutputPath>
    [省略可能] NuGet パッケージが生成される場所。[OPTIONAL] Where the NuGet package will be produced. NuGet パッケージは、.NET Core CLI グローバル ツールがツールのインストールに使用するパッケージです。The NuGet package is what the .NET Core CLI Global Tools uses to install your tool.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp2.1</TargetFramework>

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

  </PropertyGroup>

</Project>

<PackageOutputPath> は省略可能ですが、この例では使用します。Even though <PackageOutputPath> is optional, use it in this example. 必ず <PackageOutputPath>./nupkg</PackageOutputPath> を設定してください。Make sure you set it: <PackageOutputPath>./nupkg</PackageOutputPath>.

次に、アプリケーション用の NuGet パッケージを作成します。Next, create a NuGet package for your application.

dotnet pack

botsay.1.0.0.nupkg ファイルは、botsay.csproj ファイルの <PackageOutputPath> XML 値で識別されるフォルダー (この例では ./nupkg フォルダー) に作成されます。The botsay.1.0.0.nupkg file is created in the folder identified by the <PackageOutputPath> XML value from the botsay.csproj file, which in this example is the ./nupkg folder. これにより、インストールとテストが簡単になります。This makes it easy to install and test. ツールを公開する場合は、https://www.nuget.org にアップロードしてください。When you want to release a tool publicly, upload it to https://www.nuget.org. NuGet でツールを使用できるようになると、開発者は dotnet tool install コマンドの --global オプションを使用してツールのユーザー全体のインストールを実行できます。Once the tool is available on NuGet, developers can perform a user-wide installation of the tool using the --global option of the dotnet tool install command.

パッケージを用意できたので、そのパッケージからツールをインストールします。Now that you have a package, install the tool from that package:

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

--add-source パラメーターで、NuGet パッケージの追加のソース フィードとして ./nupkg フォルダー (ここでは <PackageOutputPath> フォルダー) を一時的に使用するように .NET CoreCLI に指示します。The --add-source parameter tells the .NET Core CLI to temporarily use the ./nupkg folder (our <PackageOutputPath> folder) as an additional source feed for NuGet packages. グローバル ツールのインストールの詳細については、「.NET Core グローバル ツールの概要」を参照してください。For more information about installing Global Tools, see .NET Core Global Tools overview.

インストールが成功すると、ツールの呼び出しに使用したコマンドとインストールされたバージョンを示す、次の例のようなメッセージが表示されます。If installation is successful, a message is displayed showing the command used to call the tool and the version installed, similar to the following example:

You can invoke the tool using the following command: botsay
Tool 'botsay' (version '1.0.0') was successfully installed.

これで、botsay を入力してツールから応答を取得できるようになりました。You should now be able to type botsay and get a response from the tool.

注意

インストールは成功しても botsay コマンドを使用できない場合は、新しい端末を開いて PATH を更新する必要があります。If the install was successful, but you cannot use the botsay command, you may need to open a new terminal to refresh the PATH.

ツールを削除するRemove the tool

ツールの実験を完了したら、次のコマンドでツールを削除することができます。Once you're done experimenting with the tool, you can remove it with the following command:

dotnet tool uninstall -g botsay