Clarify CancellationToken binding vs CancellationToken from FunctionContext vs CancellationToken from HttpContext in HTTP Trigger

[JensSchadron]

Hii,

I've gotten questions from colleagues the past few days regarding the usage of CancellationTokens in an HTTP triggered function and I noticed that both in the documentation and on the internet, there's some ambiguity/discussions on when to use either token. Hence this discussion.

As mentioned in the title, I'm aware of 3 ways of acquiring a CancellationToken.

• The CancellationToken that can be bound as a method parameter

[Function("HelloWorld")]
public IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req,
    CancellationToken cancellationToken)
{
    var cts = cancellationToken;

    _logger.LogInformation("C# HTTP trigger function processed a request.");
    return new OkObjectResult("Welcome to Azure Functions!");
}

• The CancellationToken that can be acquired from the FunctionContext

[Function("HelloWorld")]
public IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req,
    FunctionContext context)
{
    var cts = context.CancellationToken;

    _logger.LogInformation("C# HTTP trigger function processed a request.");
    return new OkObjectResult("Welcome to Azure Functions!");
}

• The CancellationToken that can be acquired from the HttpContext

[Function("HelloWorld")]
public IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
{
    var cts = req.HttpContext.RequestAborted;

    _logger.LogInformation("C# HTTP trigger function processed a request.");
    return new OkObjectResult("Welcome to Azure Functions!");
}

First of all, I'd like to believe that the CancellationToken binding is just a convenience shortcut for the one found in the FunctionContext. However, the documentation (here and here) aren't exactly clear and only states that it is used for graceful shutdown. No word on mentioning that it can also be used for a request timing out, connection getting dropped or a user aborting the request.
TL;DR Only when the function app is getting shut down.

The RequestAborted CancellationToken, on the other hand, will probably just be a HTTP trigger specific CancellationToken that only reacts to consumers dropping the call.

With that all being said, I also stumbled upon this PR in the Azure Functions host repo, which would in turn would mean that the RequestAborted CancellationToken is getting linked to the both the CancellationToken in FunctionContext, as well as the one that can be bound as a method parameter (assuming that my previous assumption still holds up) and thus, that we should just use either of the latter ones.

I'd appreciate it if someone could clarify this and either confirm or deny my assumptions so we can get a better understanding of it all :)

[ErisApps]

Hiii,

I'm also curious to get an answer to this seemingly trivial question.
@liliankasem or @jviau (or any of the other team members), would it be possible to take a quick look at this?

Kind regards and thanks in advance

[liliankasem]

Hey, so you're pretty much spot on here. But the CancellationToken cancellationToken binding and context.CancellationToken are exactly the same - use which ever flavour you prefer. But we essentialy made the context's CT available as a binding so it's easier and cleaner to utilize.

The RequestAborted CancellationToken, on the other hand, will probably just be a HTTP trigger specific CancellationToken that only reacts to consumers dropping the call.

Correct

also stumbled upon Azure/azure-functions-host#9159, which would in turn would mean that the RequestAborted CancellationToken is getting linked to the both the CancellationToken in FunctionContext, as well as the one that can be bound as a method parameter

Yup, also correct (keeping in mind the bound CT and context CT are the same CT).

If I had to choose, I would suggest only using the CancellationToken binding.

However, the documentation (here and here) aren't exactly clear and only states that it is used for graceful shutdown. No word on mentioning that it can also be used for a request timing out, connection getting dropped or a user aborting the request.

Yeah the documenation is not great, I have a work item to get those docs updated. There's a draft of the text for this doc update here (in the issue) - I'll see if I can get more input on this in our next sprint.

[JensSchadron]

Thank you kindly for answering my question. 😄