Command versioning

Taskurai supports versioning of commands and makes it possible to support multiple versions of a command to be used at the same time.

info

When a task contains a version that is not defined in Taskurai, the task will fail to create.

Prerequisites

• You have completed:
  • Worker Setup
  • Creating a Docker container
  • Deploying a worker
  • Defining controllers
  • Creating commands

Version syntax

Commands are versioned using the following syntax:

commandName@version

The command name should not contain the @-character. The version should be a number.

Defining separate command versions

C#

To support multiple versions of a command, it is possible to define separate command versions.

First, use the Command attribute to define the name of the command. Next define the versions using the Version attribute.

In the following example the second version of the command is marked as default. This command will be selected when a task does not specify a specific version of the command.

Controllers/TestController.cs

using Taskurai.Models;
using Taskurai.Worker;

public class TestController: WorkerController
{
  private readonly IConfiguration _configuration;


  public TestController(IConfiguration configuration)
  {
    _configuration = configuration;
  }

  [Command("TestCommand")]
  [Version(1)]
  public async Task<TaskCommandResult> TestCommandV1(TaskuraiTaskContext context, CancellationToken cancellationToken)
  {
    Logger.LogInformation("TestCommand started...");

    // Simulate work
    await Task.Delay(5000, cancellationToken);

    return Succeeded();
  }

  [Command("TestCommand")]
  [Version(2, IsDefault = true)]
  public async Task<TaskCommandResult> TestCommandV2(TaskuraiTaskContext context, CancellationToken cancellationToken)
  {
    Logger.LogInformation("TestCommand started...");

    // Simulate work
    await Task.Delay(5000, cancellationToken);

    return Succeeded();
  }

  [Command("TestCommand")]
  [Version(3)]
  public async Task<TaskCommandResult> TestCommandV3(TaskuraiTaskContext context, CancellationToken cancellationToken)
  {
    Logger.LogInformation("TestCommand started...");

    // Simulate work
    await Task.Delay(5000, cancellationToken);

    return Succeeded();
  }
}

Reusing commands

It is possible to reuse a command and handle different versions in one command. One command can match multiple versions.

C#

In the task context, the RequestedVersion and SelectedVersion properties can be used to determine the version of the command that was selected.

Examples:

• Task command testCommand@3: RequestedVersion and SelectedVersion will be set to 3.
• Task testCommand: RequestedVersion will be null and SelectedVersion will be set to 2.

Controllers/TestController.cs

using System.Net;
using Taskurai.Models;
using Taskurai.Worker;

public class TestController: WorkerController
{
  private readonly IConfiguration _configuration;


  public TestController(IConfiguration configuration)
  {
    _configuration = configuration;
  }

  [Command("TestCommand")]
  [Version(1)]
  [Version(2, IsDefault = true)]
  public async Task<TaskCommandResult> TestCommandV1V2(TaskuraiTaskContext context, CancellationToken cancellationToken)
  {
    Logger.LogInformation("TestCommand: requested version = {RequestedVersion}, selected version = {SelectedVersion}", 
      context.RequestedVersion, 
      context.SelectedVersion);

    switch (context.SelectedVersion)
    {
      case 1:
        Logger.LogInformation("Version 1");
        break;
      case 2:
        Logger.LogInformation("Version 2");
        break;
    }

    // Simulate work
    await Task.Delay(5000, cancellationToken);

    return Succeeded();
  }

  [Command("TestCommand")]
  [Version(3)]
  public async Task<TaskCommandResult> TestCommandV3(TaskuraiTaskContext context, CancellationToken cancellationToken)
  {
    Logger.LogInformation("TestCommand started...");

    // Simulate work
    await Task.Delay(5000, cancellationToken);

    return Succeeded();
  }
}

Calling versioned commands

Using the latest version

When creating a task while omitting the version from a command, there are two options:

• When an default version is defined (eg.: [Version(2, IsDefault = true)]), this version is called when the task is executed.
• When no default version is defined, the latest version available is called when the task is executed.

C#

var createdTask = await taskurai.CreateTaskAsync(new TaskConfig("testCommand")
{

}, cancellationToken);

Using an specific version

When creating a task while specifying a specific version from a command, the exact version is called when the task is executed.

C#

var createdTask = await taskurai.CreateTaskAsync(new TaskConfig("testCommand@3")
{

}, cancellationToken);