Create a plugin to register a command

You can use a plugin to register a command for use with the Content Hub CLI. In this example, you'll create a command called echo and then create a plugin to register it. The echo command outputs the string values that are passed in as arguments.

This walkthrough describes how to:

Note

The following examples use the .NET CLI, but you can achieve the same results in your preferred integrated development environment (IDE).

Create a project

To create a project:

To create a class library, run the following commands:
mkdir Walkthrough
cd Walkthrough
dotnet new classlib --framework net6.0

To add a reference to the core CLI functionality, run the following command :

dotnet add package Sitecore.CH.Cli.Core --source https://nuget.sitecore.com/resources/v3/index.json

Sitecore.CH.Cli.Core provides access to the plugin infrastructure, useful utilities around file system access, configuration management, and console output. It also adds a dependency to the Web Client SDK.

Create the plugin

While starting up the application, the CLI scans the plugin search paths for any types that inherit from Sitecore.CH.Cli.Core.Abstractions.Infrastructure.IPlugin.

To create the plugin:

Rename the file Class1.cs to Plugin.cs and add the following code

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

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

    public void RegisterCommands(ICommandRegistry registry)
    {
    }
  }
}

This class contains the following methods:

ConfigureServices - lets you register custom services in the shared service collection for dependency injection. Command handlers can resolve these services in their constructor. See Dependency injection - .NET for more information.
RegisterCommands - registers new commands that are being delivered as part of this plugin, and makes them available through the CLI.

Create and register a command

In this example, you create a command called echo. There are two methods you can use to do this:

Use a separate command declaration and command handling. This is the preferred approach as it allows for better and easier unit testing of the command handler implementation.
Specify options and command handling in the same class

To create and register a command:

The value echo that is passed to the base constructor is the name under which the command will be made available later.

Arguments are passed into the function. IHost contains a reference to the service provider that resolves previously registered services. The value echo that is passed to the base constructor is the name under which the command will be made available later.

New commands can be added to existing groups, or to new groups created specifically for them. Several command groups are available as standard, including:

delivery
serialization
tenant

Create a file called EchoCommand.cs and add a separate command declaration and command handling as shown in the following code:

using System.CommandLine;
using System.CommandLine.Invocation;
using Sitecore.ContentHub.Cli.Shared.Abstractions.Commands;
using Sitecore.ContentHub.Cli.Shared.Abstractions.Rendering;

namespace Walkthrough;

public class EchoCommand : BaseCommand <EchoCommandHandler> 
{
  public EchoCommand() : base("echo", "Echo a value")
  {
    // Options
    AddOption(new Option <string> (new[] {"--value", "-v"}, "Value to echo")
    {
      IsRequired = true
    });
  }
}

public class EchoCommandHandler : BaseCommandHandler
{
  // Inject services from service provider
  public EchoCommandHandler(IOutputRenderer renderer) : base(renderer)
  {
  }

  public string Value { get; set; }

  // Command handling
  public override Task <int> InvokeDefaultAsync(InvocationContext context)
  {
    Renderer.WriteLine(Value);

    // Return exit code to indicate success or failure
    return Task.FromResult(0);
  }
}

Or, use a separate class for arguments and options, as shown in the following code:

using System.CommandLine;
using System.CommandLine.Invocation;
using Microsoft.Extensions.Options;
using Sitecore.ContentHub.Cli.Shared.Abstractions.Commands;
using Sitecore.ContentHub.Cli.Shared.Abstractions.Rendering;

namespace Walkthrough;

public class EchoCommandParameters
{
  public string Value { get; set; }
}

public class EchoCommand : BaseCommand <EchoCommandHandler> 
{
  public EchoCommand() : base("echo", "Echo a value")
  {
    // Options
    AddOption(new Option <string> (new[] {"--value", "-v"}, "Value to echo")
    {
      IsRequired = true
    });
  }
}

public class EchoCommandHandler : BaseCommandHandler <EchoCommandParameters> 
{
  // Inject services from service provider
  public EchoCommandHandler(
    IOutputRenderer renderer, 
    IOptions <EchoCommandParameters> parameters) : base(renderer, parameters)
  {
  }

  // Command handling
  public override Task <int> InvokeDefaultAsync(InvocationContext context)
  {
    Renderer.WriteLine(Parameters.Value);

    // Return exit code to indicate success or failure
    return Task.FromResult(0);
  }
}

Specify options and command handling in the same class, as shown in the following code:

  using System.CommandLine;
  using System.CommandLine.NamingConventionBinder;
  using Microsoft.Extensions.DependencyInjection; 
  using Microsoft.Extensions.Hosting;
  using Sitecore.ContentHub.Cli.Shared.Abstractions.Commands;
  using Sitecore.ContentHub.Cli.Shared.Abstractions.Rendering;       

  namespace Walkthrough
  {
      public class EchoCommand : BaseCommand
    {
      public EchoCommand() : base("echo", "Echo a value")
      {
        // Options
        AddOption(new Option <string> (new[] {"--value", "-v"}, "Value to echo")
        {
          IsRequired = true
        });

        Handler = CommandHandler.Create <string>, IHost ((value, host) = 
        {
          host.Services.GetService <IOutputRenderer> ().WriteLine(value);
        });
    }
  }

To connect the plugin class and the command, modify the Plugin.cs file updating the RegisterCommands method as follows:

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

  ...
}

After they are compiled and copied to a discoverable plugin search path, the walkthrough command group and echo command are included in the CLI. You can now run several commands to verify that everything has been set up correctly.

The following command starts from the walkthrough command group and verifies that the new echo command has been added:

ch-cli walkthrough --help

You can run the echo command as follows:

ch-cli walkthrough echo --value Hello

If you have suggestions for improving this article, let us know!