チュートリアル

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

> mkdir Walkthrough
> cd Walkthrough
> dotnet new classlib --framework net6.0

プロジェクトを作成したら、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", "Echo a value")
  {
  // options
  AddOption<string>("Value to echo", true, "--value", "-v");
  }
  }
  
  public class EchoCommandHandler : ICommandHandler
  {
  private readonly IOutputRenderer _renderer;
  
  // Inject services from service provider
  public EchoCommandHandler(IOutputRenderer renderer)
  {
  _renderer = renderer;
  }
  
  public string Value { get; set; }
  
  // Command handling
  public Task<int> InvokeAsync(InvocationContext context)
  {
  _renderer.WriteLine(Value);
  }
  }
  }

  引数とオプションに別のクラスを使用する:

  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", "Echo a value")
  {
  // options
  AddOption<string>("Value to echo", true, "--value", "-v");
  }
  }
  
  public class EchoCommandParameters
  {
  public string Value { get; set; }
  }
  
  public class EchoCommandHandler : ICommandHandler
  {
  private readonly IOutputRenderer _renderer;
  
  // Inject services and parameters from service provider
  public EchoCommandHandler(
  IOutputRenderer renderer, IOptions<EchoCommandParameters> parameters)
  {
  _renderer = renderer;
  
  Parameters = parameters;
  }
  
  public EchoCommandParameters Parameters { get; set; }
  
  // Command handling
  public Task<int> InvokeAsync(InvocationContext context)
  {
  _renderer.WriteLine(Parameters.Value);
  }
  }
  }

  これらは、コマンド ハンドラーに挿入できる、すぐに使用できるサービスの一部です。

  • IOutputRenderer。ユーザーに対してコンテンツをレンダリングします。
  • Lazy<IWebMClient>。Content Hub Web SDK クライアント。
  • IFileProvider。基本的なファイル管理ルーチンを提供します。

• オプションとコマンド処理を同じクラスで指定する:

  using Sitecore.CH.Cli.Core.Abstractions.Commands;
  using Sitecore.CH.Cli.Core.Abstractions.IO;
  
  namespace Walkthrough
  {
  public class EchoCommand : BaseCommand
  {
  public EchoCommand() : base("echo", "Echo a value")
  {
  // Options
  AddOption<string>("Value to echo", true, "--value", "-v");
  
  // Command handling
  Handler = CommandHandler.Create<string, IHost>((value, host) =>
  {
  host.Services.GetService<IOutputRenderer>().WriteLine(value);
  });
  }
  }
  }

  この例では、引数は関数に渡されます。IHost には、以前に登録されたサービスを解決するサービス プロバイダーへの参照が含まれています。

どちらの例も、基本コンストラクターに渡される値 "echo" が、コマンドが後で使用可能になったときの名前になります。

コマンド オプション

• 必要なオプションを追加するには

  AddOption<string>("<option description>", true, "--my-option", "-o");

• エイリアス付きのオプションを追加するには

  AddOption<string>("<option description>", false, "--my-option", "-o");

• 既定値でオプションを追加するには

  AddOption<int>("<option description>", false, () => 123, "--my-option");

プラグイン クラスとコマンド自体が作成されたので、それらを接続する必要があります。そのためには、以前に作成したプラグインクラスに戻り、以下を RegisterCommands メソッドに追加する必要があります。

public class WalkthroughPlugin : IPlugin
{
...

public void RegisterCommands(ICommandRegistry registry)
{
// register the command to an existing command group
registry.RegisterCommand("walkthrough", new EchoCommand());

// register a new command group and its commands
registry.RegisterCommandGroup(
"walkthrough", new List<Command> { new EchoCommand() }, "Walkthrough plugin for demonstration purposes only");
}

...
}

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

• audit
• content
• jobs
• orders
• queues
• scripting
• print
• system
• serialization

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

public class WalkthroughPlugin : IPlugin
{
...

public void ConfigureServices(IServiceCollection services)
{
services.AddCommandHandler<EchoCommandHandler>();

// registers a command handler with options and arguments nested in a separate class.
services.AddCommandHandler<EchoCommandHandler, EchoCommandParameters>();
}

...
}

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

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

ch-cli --help

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

ch-cli walkthrough --help

これは echo コマンドを実行します。

ch-cli walkthrough echo --value Hello