Introduction

Yes, you can use CancellationToken with async Dapper calls, but the most reliable pattern is not to hunt for a special overload on every method. Instead, pass a CommandDefinition that carries the SQL, parameters, and cancellation token together.

That design matches how Dapper forwards work to the underlying ADO.NET provider. If the provider supports cancellation properly, the query can be interrupted cooperatively.

Use CommandDefinition for Cancellation

Many developers expect a method signature like QueryAsync(sql, token). In practice, Dapper's cancellation-friendly path is usually CommandDefinition.

1using System;
2using System.Data.SqlClient;
3using System.Threading;
4using System.Threading.Tasks;
5using Dapper;
6
7var cts = new CancellationTokenSource(TimeSpan.FromSeconds(2));
8
9await using var connection = new SqlConnection("Server=.;Database=AppDb;Trusted_Connection=True;");
10await connection.OpenAsync(cts.Token);
11
12var command = new CommandDefinition(
13    "select top 1000 Id, Name from dbo.Users where IsActive = @IsActive",
14    new { IsActive = true },
15    cancellationToken: cts.Token);
16
17var users = await connection.QueryAsync<User>(command);
18
19foreach (var user in users)
20{
21    Console.WriteLine(user.Name);
22}
23
24public sealed class User
25{
26    public int Id { get; init; }
27    public string Name { get; init; } = "";
28}

The important part is that the token is attached to the command object, not bolted on afterward.

Understand What Cancellation Actually Means

Cancellation is cooperative. Your code can request it, but Dapper still depends on the database provider and the server to honor that request. In other words, passing a token is necessary, but it does not guarantee the query stops at the exact instant you cancel.

This matters most for:

• slow network calls
• providers with limited cancellation behavior
• queries already deep inside server execution

Even with those caveats, adding cancellation is still worthwhile because it gives your application a clean escape path during shutdowns, user disconnects, and request timeouts.

Cancellation and Timeouts Are Different

A CancellationToken is application-driven cancellation. A command timeout is a database command limit. They often work together, but they are not interchangeable.

1var command = new CommandDefinition(
2    "waitfor delay '00:00:10'; select 1;",
3    commandTimeout: 3,
4    cancellationToken: cts.Token);

In that example, the command timeout can fail the operation even if no cancellation request is sent. Conversely, the token can cancel the query even when the timeout has not been reached.

Treat them as separate controls:

• timeout limits how long the database command may run
• cancellation lets your application stop waiting because business logic changed

Handle the Exception Path Correctly

A canceled operation should normally surface as OperationCanceledException or a provider-specific exception chain with cancellation semantics. Catch the cancellation path separately from genuine failures.

1try
2{
3    var rows = await connection.QueryAsync<User>(command);
4}
5catch (OperationCanceledException)
6{
7    Console.WriteLine("Query was canceled");
8}

That keeps your logs cleaner and prevents expected cancellations from being reported as system errors.

Common Pitfalls

One frequent mistake is passing a token to OpenAsync but not to the Dapper query itself. That only makes connection opening cancellable, not command execution.

Another mistake is assuming every async Dapper overload directly exposes a token parameter. CommandDefinition is the safer pattern to remember.

It is also easy to confuse timeout handling with cancellation. A timeout is not a substitute for cancellation during app shutdown or request aborts.

Finally, do not assume every provider cancels with identical behavior. Always test the exact database and driver combination your application uses.

Summary

• Use CommandDefinition to pass CancellationToken into async Dapper operations.
• Cancellation is cooperative and depends on the underlying provider.
• Command timeouts and cancellation tokens solve different problems.
• Catch cancellation separately from real failures.
• Test provider behavior instead of assuming all databases react the same way.