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.

Prerequisites​

Authentication​

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

There are two different scenarios for using the Taskurai API:

  • Local development
  • Hosted environment (your dev, test, production, etc. environment)

The lifetime of the access token should be matched to the use-case:

  • Short for local development
  • Can have an unlimited lifetime if needed for hosted environments.

Read Worker Setup for more information about authentication in worker applications.

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.

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
...
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

The expected output should be:

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]
      Content root path: /Users/taskuraidev/Dev/taskurai/samples/tasks-aspnetcore-sample
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:

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

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

...
    public async Task<OrderResponse> CreateOrder()
    {
        ...
        var orderResponse = new OrderResponse()
        {
            OrderId = Guid.NewGuid(),
            CustomerName = customerName,
            OrderTimestamp = DateTime.UtcNow
        };

        // Generate an order confirmation (pdf + email)

        var taskInput = new TaskConfig("generateOrderConfirmation")
        {            
            Arguments = new List<TaskArgument>()
            {
                new TaskArgument("orderId")
                {
                    Value = orderResponse.OrderId.ToString()
                }
            },
            Category = "Create order",
            Subject = $"Creating order {orderResponse.OrderId.ToString()} for customer {customerName}"
        };

        var taskResponse = await _taskurai.CreateTaskAsync(taskInput);

        // Store the task id for the client to follow up
        orderResponse.OrderConfirmationTaskId = taskResponse.Id;

        return orderResponse;
    }
...
}

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

The expected output should be:

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.