チュートリアル

[!注] 次の例では .NET Core CLI を使用していますが、お好みの IDE で同等の機能を使用しても、同じ結果を得られます。

CLI プラグインは単なるクラス ライブラリです。 クラス ライブラリを作成するには、次のコマンドを実行します。

> mkdir Walkthrough
> cd Walkthrough
> dotnet new classlib --framework netcoreapp3.1

プロジェクトを作成したら、CLI のコア機能への参照を追加する必要があります。

dotnet add package Sitecore.CH.Cli.Core --source https://slpartners.myget.org/F/m-public/api/v3/index.json

Sitecore.CH.Cli.Core は、プラグイン インフラストラクチャへのアクセス、ファイル システム アクセス/設定管理/コンソール出力に関する便利なユーティリティに加えて、Web クライアント SDK への依存関係を提供します。

アプリケーションの起動時に、CLI はプラグインの検索パスをスキャンして、Sitecore.CH.Cli.Core.Abstractions.Infrastructure.IPlugin から継承するタイプを探します。

以前に作成したプロジェクトに新しいクラスを作成します。

using Sitecore.CH.Cli.Core.Abstractions.Infrastructure;

namespace Walkthrough
{
    public class WalkthroughPlugin : IPlugin
    {
        public void ConfigureServices(IServiceCollection services)
        {
        }

        public void RegisterCommands(ICommandRegistry registry)
        {
        }
    }
}

• ConfigureServices - 共有サービス コレクションにカスタム サービスを登録し、コマンド実行中の後の時点でそれらを解決できるようにします。
• RegisterCommands - このプラグインの一部として提供されている新しいコマンドを登録し、CLI から利用できるようにします。

実際のコマンドを作成する場合、次の 2 つの方法が考えられます。

• 個別のコマンド宣言とコマンド処理。 これは、コマンド ハンドラー実装をより適切かつ簡単に単体テストできるため、推奨されるアプローチです。

  using Sitecore.CH.Cli.Core.Abstractions.Commands;
  using Sitecore.CH.Cli.Core.Abstractions.IO;
  
  namespace Walkthrough
  {
      public class EchoCommand : BaseCommand<EchoCommandHandler>
      {
          public EchoCommand() : base("echo")
          {
              // Arguments
              AddArgument(new Argument<string>("value"));
          }
      }
  
      public class EchoCommandHandler : ICommandHandler
      {
          private readonly IConsoleOutput _consoleOutput;
  
          // Inject services from service provider
          public EchoCommand(IConsoleOutput consoleOutput)
          {
              _consoleOutput = consoleOutput;
          }
  
          public string Value { get; set; }
  
          // Command handling
          public Task<int> InvokeAsync(InvocationContext context)
          {
              _consoleOutput.WriteLine(Value);
          }
      }
  }

• Specify arguments, options, and command handling in the same class:

  using Sitecore.CH.Cli.Core.Abstractions.Commands;
  using Sitecore.CH.Cli.Core.Abstractions.IO;
  
  namespace Walkthrough
  {
      public class EchoCommand : BaseCommand
      {
          public EchoCommand() : base("echo")
          {
              // Arguments
              AddArgument(new Argument<string>("value"));
  
              // Command handling
              Handler = CommandHandler.Create<string, IHost>((value, host) =>
              {
                  host.Services.GetService<IConsoleOutput>().WriteLine(value);
              });
          }
      }
  }

  In this case, arguments are passed into the function. IHost contains a reference to the service provider that resolves previously registered services.

In both cases the value "echo" that is passed to the base constructor is the name under which the command will be made available later.

Now that the plugin class and the command itself are created, they need to be connected. For that you need to go back to the previously created plugin class and add the following to the RegisterCommands method:

registry.RegisterCommandGroup(
    "walkthrough",
    new List<Command>
    {
        new EchoCommand()
    },
    "Walkthrough plugin for demonstration purposes only");

コマンド グループは、領域またはコンテキストごとにコマンドを構造化する方法です。 すぐに使用できるコマンド グループの例を次に示します。

• app
• audit
• content
• jobs
• orders
• queues

新しいコマンドは、上記のコマンドを使用して新しいコマンド グループに追加することも、次のコードを使用して既存のコマンド グループ (この例ではアプリ) に追加することもできます。

registry.RegisterCommand("app", new EchoCommand());

別のコマンド ハンドラーを使用した場合は、次のコードを使用して、ConfigureServices メソッドのサービス コレクションに追加します。

services.AddTransient(typeof(EchoCommandHandler));

コンパイルして検出可能なプラグイン検索パスにコピーすると、コマンド グループとコマンドが CLI ヘルプに組み込まれます。

これにより、既存のコマンド グループの中で新しく追加されたコマンド グループが返されます。

ch-cli --help

これにより、walkthrough コマンド グループの一部として echo コマンドが返されます。

ch-cli walkthrough --help