In this article, we are going to explain what is CancellationToken and the way to implement it in your Asp.Net Core APIs.

What is CancellationToken

If I want to put it in one sentence, CancellationToken is a token object providing a mechanism to stop long-running and async operations before the process is finalized (due to the client’s request).

Let’s imagine a scenario where you have a front-end application that is making an HTTP Get request to an endpoint which is performing a long-running operation on a large amount of data and responses to it. The end-user can close the browser or just move to another page and doesn’t need that result anymore, by having the ability to cancel the request in the middle of the operation when the user doesn’t need it anymore we will save some resources especially if we have a huge amount of users. Therefore; .NET made the CancellationToken and when the request-making client sets the token we will get the mentioned benefit.

When & Why You Should Consider Implementing CancellationToken

In short, you should implement CancellationToken when dealing with lengthy read operations that require significant resources or you have many async operations that are going to happen at the same time.

Saving Resources

Implementing the CancellationToken can help save resources by allowing the cancellation of long-running operations. This is particularly useful when dealing with large amounts of data and multiple users. By providing the ability to cancel requests in the middle of an operation, unnecessary resources can be freed up efficiently. It is important to properly implement the CancellationToken to achieve these benefits.

Freeing locked Resources

Implementing the CancellationToken ensures the release of locked resources. By using the token, we can terminate long-running operations that may hold locks on shared resources. This prevents potential deadlocks and improves overall system performance. It is crucial to incorporate CancellationToken in multi-threaded and asynchronous scenarios to avoid resource contention issues effectively.

Giving Option to the end-user

By incorporating the CancellationToken, end-users are given the option to cancel ongoing operations. This empowers them with more control over their interactions with the system and enhances their overall user experience.

Code Sample

Here I’m going to create an endpoint to simulate the situation and have an example of implementing the CancellationToken properly.

The following code is an endpoint that accepts a CancellationToken as a querystring parameter, and that is what you are going to use in your code to implement a cancellation process or you are going to pass that to a method that knows how to use it to cancel the specific process.

You don’t need to set the token in your API call, the browser sets that parameter for you.

[HttpGet]
public string Get(CancellationToken token = default)
{
  // Your code which needs to user the token passed in
}

For the following examples, I’m using ASP.NET Core Web API template with .NET 7.0 as a starting point.

The following code is a basic example where we pass the CancellationToken as a parameter to the action and check inside a for loop to see if any cancellation has happened yet or not using ThrowIfCancellationRequested(). This method will throw an OperationCanceledException if the client has requested cancellation, otherwise, your code will continue to the artificial 1000 ms delay. We have the delay to give us enough time to test the scenario when we cancel the request by leaving the page in the browser.

public async Task<string> Get(CancellationToken token = default)
{
    try
    {
        for (var i = 0; i < 10; i++)
        {
            token.ThrowIfCancellationRequested();
            Thread.Sleep(1000);
        }             
    }
    catch (OperationCanceledException ex)
    {
        _logger.LogDebug(ex.Message);
    }

    return "Finished";
}

When you run the application and test the API using the Swagger web interface, if you wait until the execution ends properly you will get a 200 ok.

But, if you refresh the page in the middle of the process, your web browser will send a request to cancel the execution using the CancellationToken, and your token.ThrowIfCancellationRequested(); check will throw an OperationCanceledException exception as you can see in the following screenshot.

You can also use your toke with Entity Framework to stop a database process if you get the cancellation request. You should pass the token to your EF methods that you are calling like FirstOrDefaultAsync and SaveChangesAsync methods that we used in the following example.

public async Task UpdateUserAsync(int userId, string name, CancellationToken cancellationToken = default)
{
    try
    {
        var entity = await _dbContext.Users.FirstOrDefaultAsync(e => e.Id == userId, cancellationToken);

        if (entity != null)
        {
            entity.Name = name;
            await _dbContext.SaveChangesAsync(cancellationToken);
            _logger.LogDebug($"Entity {userId} updated");
        }
        else
        {
            _logger.LogDebug($"Entity {userId} not found");
        }
    }
    catch (OperationCanceledException ex)
    {
         _logger.LogDebug($"UpdateUserAsync canceled: {ex.Message}");
    }
}

Conclusion

CancellationToken is a simple way to save your resources and add flexibility to your endpoint by giving the option to your clients to cancel a request; therefore, I will suggest using it in your APIs if you are not already doing it.

RELATED ARTICLESMORE FROM AUTHOR