Skip to main content

Setup application

In this section, you'll learn how to set up an application that can interact with the Taskurai API.

These applications can be typically be your services, APIs, functions, etc, Creating tasks and interacting with the task progress.

Prerequisites​

Authentication​

Personal access tokens (PAT) are used to secure access to the Taskurai API.

It is strongly advised to handle the access token with care. In .NET, we suggest using user-secrets when developing locally. In your hosted environment, use the appropriate solution to handle sensitive data.

info

The minimum Access tokens to create tasks are:

  • Data/Buildby.Taskurai/tasks/*

When storing initial state or retrieving state from completed tasks add:

  • Data/Buildby.Taskurai/state/*

When using sensitive data or secrets in tasks, add the following scope:

  • Data/Buildby.Taskurai/sensitive/read

When global secrets are referenced in the task arguments, add the following scope:

  • Data/Buildby.Taskurai/secrets/read

A less granular permission like Data/Buildby.Taskurai/* may also be used.

Setup applications​

Any application where a Taskurai SDK is available can interact with the API.

To add the Taskurai client:

dotnet add package Taskurai

In this section, the following examples are available:

Setting up an Asp.Net Core application​

Application Setup​

In this sample, you will learn how to create an Asp.Net Core WebApi sample application.

  1. Create a sample directory:
mkdir tasks-aspnetcore-sample
cd tasks-aspnetcore-sample
  1. Create a new web API application:
info

.NET 8.0 SDK is recommended for this example.

dotnet new webapi --framework net8.0
  1. Add Taskurai SDK:
dotnet add package Taskurai
dotnet add package Taskurai.AspNetCore
  1. Setup the Taskurai client:

Change the Program.cs file:

Program.cs
using Taskurai; // Add Taskurai
using Taskurai.AspNetCore; // Add Taskurai

...

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

...

builder.Services.AddTaskurai(); // Add Taskurai

...

var app = builder.Build();
...
  1. Add application configuration:

Add the following configuration files:

appsettings.json
{
  ...
  "Taskurai": {
    "IsolationMode": false
  }
  ...
}
appsettings.Development.json
{
  ...
  "Taskurai": {
    "IsolationMode": true
  }
  ...
}
  1. Add the personal access token as a user secret, replace the PAT with the one created in the previous step:
dotnet user-secrets init
dotnet user-secrets set "Taskurai:Pat" "e8gFaA8ZaetAHiS257opAr..."
  1. Next, run the application to validate the setup:
dotnet run

Sample output:

Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5017
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
info

The application runs in Isolation Mode when the environment is set to Development mode.

In Isolation Mode, the tasks created and returned are isolated to your local session and will not affect workers running in the Taskurai instance.

Using Taskurai in controllers​

To use Taskurai in an Asp.Net Core Controller, you can inject the TaskuraiClientFactory:

using Microsoft.AspNetCore.Mvc;
using Taskurai;
using Taskurai.Models;

public class PurchaseController : ControllerBase
{
    private readonly ILogger<PurchaseController> _logger;
    private readonly TaskuraiClient _taskurai;

    public PurchaseController(ILogger<PurchaseController> logger, ITaskuraiClientFactory taskuraiClientFactory)
    {
        _logger = logger;
        _taskurai = taskuraiClientFactory.Create(); // Create a Taskurai client
    }

    public async Task SendPurchaseOrder(string refId, string purchaseOrderId, string paperSize, string orientation, List<string> approvers, List<string> receipients)
    {
        // Generate purchase order PDF and send confirmation email to approvers.
        var createdTask = await _taskurai.CreateTaskAsync(new TaskConfig("sendPurchaseOrder")
        {
          ExternalId = refId,
          Arguments = new List<TaskArgument>()
          {
            new TaskArgument("purchaseOrderId")
            {
              Value = purchaseOrderId
            },
            new TaskArgument("formatting")
            {
              Value = new
              {
                PaperSize = paperSize,
                Orientation = orientation
              }
            },
            new TaskArgument("approvers")
            {
              Value = approvers,
              Sensitive = true
            },
            new TaskArgument("receipients")
            {
              Value = receipients,
              Sensitive = true
            }
          },
          Category = "Purchase",
          Subject = "Purchase order flow",
          Description = "Generate purchase order and start approval and delivery flow.",
        });
    }
}
}

Setting up a console application​

tip

Follow the Getting started tutorial to learn how to set up a solution from scratch.

  1. Create a sample directory:
mkdir tasks-console-sample
cd tasks-console-sample
  1. Create a new sample console application:
info

.NET 8.0 SDK is recommended for this example.

dotnet new console --framework net8.0
  1. Add Taskurai SDK:
dotnet add package Taskurai
  1. Add configuration libraries:
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.UserSecrets
  1. Setup the Taskurai client:

Add the following code to your Program.cs file:

Program.cs
using Taskurai;
using Taskurai.Models;
using System.Text.Json;
using Microsoft.Extensions.Configuration;
using System.Text.Json.Serialization;

Console.WriteLine("Testing Taskurai client library...");

// Load configuration - defaults to Development
var environment = Environment.GetEnvironmentVariable("DOTNET_ENVIRONMENT") ?? "Development";

IConfigurationRoot configuration = new ConfigurationBuilder()
	.SetBasePath(Directory.GetCurrentDirectory())
	.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
	.AddJsonFile($"appsettings.{environment}.json", optional: true, reloadOnChange: true)
    .AddUserSecrets<Program>()
	.Build();

// Setup Taskurai client
var taskurai = new TaskuraiClient(configuration["Taskurai:Pat"], new TaskuraiClientOptions()
{
	IsolationMode = configuration.GetValue<bool>("Taskurai:IsolationMode", true)
});
  1. Add application configuration:

Add the following configuration files:

appsettings.json
{
  "Taskurai": {
    "IsolationMode": false
  }
}
appsettings.Development.json
{
  "Taskurai": {
    "IsolationMode": true
  }
}
  1. Add the personal access token as a user secret, replacing the PAT with the one created in the previous step:
dotnet user-secrets init

dotnet user-secrets set "Taskurai:Pat" "e8gFaA8ZaetAHiS257opAr..."
  1. Next, run the console application to validate the setup:
dotnet run

Sample output:

Testing Taskurai client library...
Entering isolation mode, looking up token information...
Running in isolation mode.
info

The console application runs in Isolation Mode when the environment is set to Development mode.

In Isolation Mode, the tasks created and returned are isolated to your local session and will not affect workers running in the Taskurai instance.

Taskurai SDK configuration​

Taskurai configuration can either be set using TaskuraiOptions or by specifying IConfiguration settings:

KeyTypeDescription
Taskurai:PatstringAccess token
Taskurai:IsolationModebooleanMust tasks run in isolation mode (dev mode)
Taskurai:IsolationKeyguidUnique isolation key