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 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 command versions

C#

To support multiple versions of a command, create a new command file:

Commands/TestCommandV2.cs

using Taskurai.Models;
using Taskurai.Worker;

public class TestCommandV2 : TaskuraiCommand
{
	public override async Task ExecuteAsync(TaskuraiTaskContext context, CancellationToken cancellationToken)
	{
		// Execute the command...
	
		var completeInput = new CompleteTaskInput()
		{
			Status = TaskStatusType.Succeeded,
			StatusCode = 200
		};

    await context.CompleteTaskAsync(completeInput);
	}
}

Register the new version in the Program.cs file like this:

Program.cs

using Taskurai.Worker;

await TaskuraiWorkerSetup.CreateDefaultBuilder(args)
    .ConfigureHost((options) =>
    {
    })
    .Commands((commands) => 
    {
        commands
            .Command<TestCommand>("testCommand@1") // Both commands must have a version number
            .Command<TestCommandV2>("testCommand@2")  // Both commands must have a version number
            .Command<TestCommandV2>("testCommand")  // Optionally: fallback command with no version
        ;
    })
	.RunAsync();

Update the worker configuration:

  TestWorker:
...
    commands:
      - testCommand
...      

Next, deploy the worker:

taskurai worker deploy

Reusing commands

It is possible to reuse a command and handle different versions in one command:

C#

To support multiple versions of a command, use the RequestedVersion property on the TaskuraiCommand.

Commands/TestCommandV2.cs

using Taskurai.Models;
using Taskurai.Worker;

public class TestCommand : TaskuraiCommand
{
  private const int LATEST_VERSION = 2;
  
	public override async Task ExecuteAsync(TaskuraiTaskContext context, CancellationToken cancellationToken)
	{    
		// Execute the command...

		switch (RequestedVersion.GetValueOrDefault(LATEST_VERSION)) // Default to latest version
		{
			case 1:
        // Version one handling
				break;
			case 2:
        // Version two handling
				break;
			default:
				throw new Exception($"Command version not found!");
		}
	
		var completeInput = new CompleteTaskInput()
		{
			Status = TaskStatusType.Succeeded,
			StatusCode = 200
		};

    await context.CompleteTaskAsync(completeInput);
	}
}

Register the new version in the Program.cs file like this, reusing the same command:

Program.cs

using Taskurai.Worker;

await TaskuraiWorkerSetup.CreateDefaultBuilder(args)
    .ConfigureHost((options) =>
    {
    })
    .Commands((commands) => 
    {
        commands
            .Command<TestCommand>("testCommand@1") // Both commands must have a version number
            .Command<TestCommand>("testCommand@2")  // Both commands must have a version number
            .Command<TestCommand>("testCommand")  // Optionally: fallback command with no version
        ;
    })
	.RunAsync();

Update the worker configuration:

  TestWorker:
...
    commands:
      - testCommand
...      

Next, deploy the worker:

taskurai worker deploy

Calling versioned commands

Using the latest version

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

• When an explicit fallback version is defined, this version is called when the task is executed.
• When no explicit fallback version is defined, the latest version available is called when the task is executed.

C#

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

}, cancellationToken);

Optionally, register an explicit fallback version in the Program.cs file like this:

Program.cs

using Taskurai.Worker;

await TaskuraiWorkerSetup.CreateDefaultBuilder(args)
    .ConfigureHost((options) =>
    {
    })
    .Commands((commands) => 
    {
        commands
            .Command<TestCommand>("testCommand@1") // Both commands must have a version number
            .Command<TestCommandV2>("testCommand@2")  // Both commands must have a version number
            .Command<TestCommand>("testCommand")  // Explicit fallback command with no version
        ;
    })
	.RunAsync();

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@1")
{

}, cancellationToken);