Cancellationtoken In C# Complete Guide

What is CancellationToken?

CancellationToken is a way to signal that a task or operation should be cancelled. It is commonly used for cooperative cancellation, where tasks periodically check whether they should be stopped and then exit gracefully.

Step-by-Step Guide with Examples

Step 1: Setting up a CancellationTokenSource

The CancellationTokenSource is responsible for creating CancellationToken instances and for cancelling them.

using System;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // Create a CancellationTokenSource
        CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();

        // Optionally, set a cancellation token timeout
        // cancellationTokenSource.CancelAfter(TimeSpan.FromSeconds(5));

        // Create a CancellationToken
        CancellationToken cancellationToken = cancellationTokenSource.Token;

        // Launch the long running task
        Task task = LongRunningTask(cancellationToken);

        // Wait for user input to cancel
        Console.WriteLine("Press 'C' to cancel the task...");
        if (Console.ReadKey().KeyChar == 'C')
        {
            cancellationTokenSource.Cancel();
        }

        // Wait for the task to complete
        try
        {
            await task;
            Console.WriteLine("Task completed successfully.");
        }
        catch (OperationCanceledException)
        {
            Console.WriteLine("Task was cancelled.");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An error occurred: {ex.Message}");
        }
    }

    static async Task LongRunningTask(CancellationToken cancellationToken)
    {
        for (int i = 0; i < 100; i++)
        {
            // Check if cancellation is requested
            cancellationToken.ThrowIfCancellationRequested();

            // Simulate some work
            Console.WriteLine($"Working... {i + 1}/100");
            await Task.Delay(100);
        }
    }
}

Explanation:

• CancellationTokenSource: This is used to create a CancellationToken and to request cancellation.
• CancellationToken: This is passed to the long-running task. The task uses it to check for a cancellation request.
• Task Delay: This simulates a long-running task.
• ThrowIfCancellationRequested: This method throws an OperationCanceledException if a cancellation is requested.
• CancelAfter: Optionally, set a timeout for cancellation.

Step 2: Cancellation with User Input

In the above example, if the user presses 'C', we call cancellationTokenSource.Cancel(); which sends a cancellation request to the task. The task checks for the cancellation request in the loop and throws an OperationCanceledException if it is requested.

Step 3: Handling Multiple Tasks

You can also manage multiple tasks using a single CancellationToken.

using System;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
        CancellationToken cancellationToken = cancellationTokenSource.Token;

        Task task1 = LongRunningTask("Task1", cancellationToken);
        Task task2 = LongRunningTask("Task2", cancellationToken);

        Console.WriteLine("Press 'C' to cancel all tasks...");
        if (Console.ReadKey().KeyChar == 'C')
        {
            cancellationTokenSource.Cancel();
        }

        try
        {
            await Task.WhenAll(task1, task2);
            Console.WriteLine("All tasks completed successfully.");
        }
        catch (OperationCanceledException)
        {
            Console.WriteLine("One or more tasks were cancelled.");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An error occurred: {ex.Message}");
        }
    }

    static async Task LongRunningTask(string name, CancellationToken cancellationToken)
    {
        for (int i = 0; i < 10; i++)
        {
            cancellationToken.ThrowIfCancellationRequested();

            Console.WriteLine($"{name} Working... {i + 1}/10");
            await Task.Delay(500);
        }
    }
}

Explanation:

• Task.WhenAll: This method waits for all of the provided tasks to complete. If a cancellation is requested, it will cancel all tasks.
• Multiple Tasks: We have two tasks running simultaneously, and they can be cancelled together.

Step 4: Cancellation with Timeouts

You can also use CancellationToken to cancel tasks after a specified time.

using System;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
        cancellationTokenSource.CancelAfter(TimeSpan.FromSeconds(10)); // Cancel after 10 seconds
        CancellationToken cancellationToken = cancellationTokenSource.Token;

        Task task = LongRunningTask(cancellationToken);

        try
        {
            await task;
            Console.WriteLine("Task completed successfully.");
        }
        catch (OperationCanceledException)
        {
            Console.WriteLine("Task was cancelled due to timeout.");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An error occurred: {ex.Message}");
        }
    }

    static async Task LongRunningTask(CancellationToken cancellationToken)
    {
        for (int i = 0; i < 100; i++)
        {
            cancellationToken.ThrowIfCancellationRequested();

            Console.WriteLine($"Working... {i + 1}/100");
            await Task.Delay(100);
        }
    }
}

Explanation:

• CancelAfter: The task will be automatically cancelled after 10 seconds.

Summary

The CancellationToken is a powerful mechanism for cooperative cancellation in C#. It allows you to stop long-running operations gracefully, either manually or after a timeout. By understanding and using CancellationToken, you can make your applications more robust and responsive.