Question: cancellation token in durable entity (isolated)

[gha-zund]

Hey there

Quick question:
I'm migrating from in-process durable function with .NET 6 to isolated model and .NET 8

I used to have a cancellation token in my durable entity, retrieved by IDurableEntityContext.FunctionBindingContext.CancellationToken to enable graceful shutdown e.g. when the function app scales in.

How do I get a cancellation token in my entities in isolated model?
Doku says "add FunctionContext as an input parameter". Does that mean to pass the Function Context where the entity is signaled? But that could be on another function app instance...

Is there something I could get via Dependency Injection which is not documented?

[cgillum]

Adding @jviau who will probably know this better than me, but I suspect the equivalent of IDurableEntityContext.FunctionBindingContext.CancellationToken is FunctionContext.CancellationToken. Just add another parameter to your entity trigger function of type FunctionContext and the runtime will bind to it automatically.

Example, from an activity function:

[Function(nameof(SayHello))]
public static string SayHello(
    [ActivityTrigger] string cityName,
    FunctionContext funcContext)
{
    funcContext.CancellationToken.ThrowIfCancellationRequested();
    return $"Hello, {cityName}!";
}

[gha-zund]

This does not really help.

The function for a durable entity is the one which dispatches the entity.
As I understand the new API correctly, there is no way to pass any parameters via the dispatcher to the entity anymore.
So adding the FunctionContext as parameter there will not help I fear.

I tryied already adding the FunctionContext as parameter on the entity operation, but this results in the operation not getting called at all (I assume this is because the signature does not match anymore).

I have the feeling I'm doing something wrong

[gha-zund]

injection FunctionContext in the entity's constructor does not work either.
That raises an exception.

[cgillum]

Can you share code snippets of what you tried?

[jviau]

You can manually construct your entity and then dispatch to it. https://github.com/Azure/azure-functions-durable-extension/blob/dev/src/Worker.Extensions.DurableTask/TaskEntityDispatcher.cs#L36

TaskEntityDispatcher dispatcher = ...;
MyEntity myEntity = new(FunctionContext.CancellationToken); // If needing DI, can use FunctionContext.InstanceServices and ActivatorUtils, which lets you combine DI and manual parameters.
return dispatcher.DispatchAsync(myEntity);

For DI'ing FunctionsContext directly in, you can also follow this: https://gist.github.com/dolphinspired/796d26ebe1237b78ee04a3bff0620ea0

[gha-zund]

@cgillum one thing I tried is this:
(trying to get FunctionContext injected in the constructor)

public class MyEntitiy(FunctionContext contex) : TaskEntity<MyState> 
{ 
    ...

    [Function(nameof(MyEntity)]
    public static Task Run([EntityTrigger] TaskEntityDispatcher dispatcher)
        => dispatcher.DispatchAsync<MyEntity>();
}

this throws an exception when dispatching the entity (while creating the object), since FucntionContext is not registered in the ServiceProvider.

[gha-zund]

@cgillum the other thing is something like this:

public class MyEntity : TaskEntity<MyState> 
{
    public void MyOperation(MyInput input, FunctionContext context)
    {   ... }

   [Function(nameof(MyEntity)]
   public static Task Run([EntityTrigger] TaskEntityDispatcher dispatcher)
        => dispatcher.DispatchAsync<MyEntity>();
}

on when signaling it:

var entityId = new EntityInstanceId(nameof(MyEntity), entityKey);
await client.Entities.SignalEntityAsync(entityId, nameof(MyOperation), myInputValue);

-> in the hope that FunctionContext gets passed to the operation somehow automagically.

This did not throw any kind of exception and did compile.
But the entity operation did never get call. I assume this is because no matching method signature was found.

[gha-zund]

If there will be no other way, I think I will do it like as proposed by @jviau, creating my entity object manually and call the other dispatcher overload. Thank you for that hint!

[gha-zund]

Works great!

[Function(nameof(MyEntity)]
   public static Task Run(
       [EntityTrigger] TaskEntityDispatcher dispatcher,
       FunctionContext functionContext)
   {
        var entity = new MyEntity(functionContext);
        return dispatcher.DispatchAsync(entity);
   }

Another benefit (in my opinion, of course that's a question of style):
Having the function context in the entity, I don't need to specify all dependencies my entity have in the constructor anymore. Instead of constructor injection, I retrieve my dependencies now via functionContext.InstanceServices at runtime of the entity's methods.

I think this way to use entities should be added to the documentation (at least to the developer's guide!)

[gha-zund]

After digging into the code for isolated entities I have a suggestion:

• TaskEntity.RunAsync should retrieve the FunctionContext (and it's cancellation token), maybe via a parameter
• here the FunctionContext could be set onto the TaskEntityContext (would be an additional property there)
• Cancellation Token is then available in the entity's methods via Context-property

Shall I open an issue or transfer this discussion to an issue?
Or shall I try to make a contribution by myself?

[gha-zund]

As an alternative, if the function context would be available by dependency injection, this would help too.
There is already an issue for that: Azure/azure-functions-dotnet-worker#950

[jviau]

You can add the context to DI yourself via: https://gist.github.com/dolphinspired/796d26ebe1237b78ee04a3bff0620ea0

[gha-zund]

Yes this looks like it would work for me. Still would have wished a way with less additional code.
I will try the other thing you proposed first :)

[gha-zund]

Anyways, I would like to get an educated advice:
Is it even a good idea to cancel entity operations for graceful shutdown?

[cgillum]

It seems perfectly valid to me to cancel operations during a host shutdown. That will at least help ensure that the shutdown can be completed in a graceful and timely manner.

[jviau]

Some nuance for canceling on shutdown. Technically throwing on host shutdown is an entity / orchestration failure - the framework cannot differentiate why the operation failed. But in the case of host shutdown, the framework will also skip persisting the failure of the operation. This is only done in Durable Functions. Canceling here will work for DF customers due to this, but not DTFx customers.

[gha-zund]

@jviau I'm not sure if I understand you correctly. Can you explain in more detail what you mean with "Canceling here will work for DF customers due to this, but not DTFx customers"?
Did I understand correctly: Durable Functions will persist the failure of the operation when cancelling?

I'm aware that cancellation is treated same as any other unhandled exception. But I would have expected that, since the host "knows" that it's going to get shut down, that the operation will not be marked as executed (so it will be executed on another function app instance later).

[gha-zund]

@cgillum thanks for your answer! so we will continue to do that this way

[gha-zund]

Edit: I opened another discussion for this, see #2791 (comment)