如何在Azure Durable Functions中优雅终止持久编排并自定义状态

I have a Durable Function with the following rough code structure. The else branch is entered due to a functional issue (in this case, unauthenticated because auth info isn't cached). I want to self-terminate the current orchestration instance. I can do this by throwing an exception, but I'm looking for a cleaner way (if it exists) to terminate the active instance with a friendly message explaining why. Is this possible, and if so, how?

[FunctionName(nameof(UserHistorySyncWorkflow))]
public async Task<List<Match>> RunOrchestrator(
    [OrchestrationTrigger] IDurableOrchestrationContext orchestrationContext,
    ILogger logger)
{
    if(CanConnect())
    {
        // Call Activity function and return results
    }
    else
    {
        // How to gracefully Terminate here?
    }
}

Absolutely, you can gracefully terminate a Durable Function orchestration without throwing an exception—here’s the cleanest way to do it with a friendly status message:

Option 1: Use TerminateAsync (Recommended) #

The IDurableOrchestrationContext has a built-in TerminateAsync method made exactly for this scenario. It marks the orchestration as Terminated (a distinct status from "Failed") and lets you attach a custom reason message that will show up in the orchestration’s history and status queries.

Update your else branch like this:

else
{
    string terminationReason = "Cannot connect: Authentication information is not cached. Orchestration terminated gracefully.";
    await orchestrationContext.TerminateAsync(terminationReason);
    
    // Since TerminateAsync doesn't exit the method immediately, return a value matching your method's return type
    return new List<Match>();
}

Key Details: #

• TerminateAsync is async, so don’t forget to await it.
• Once called, the orchestration moves to the Terminated status right away—any code after this won’t run, but you still need to return a valid value to satisfy the compiler.
• Your custom reason will be visible in:
  • The orchestration status view in the Azure Portal
  • Durable Functions HTTP API responses
  • Orchestration history logs

Option 2: Return a "failure state" value (if Terminated status isn’t needed) #

If you don’t need the orchestration to show as "Terminated" in status tracking, you could return a special value (like an empty list) alongside a logged warning. This keeps the orchestration marked as "Completed", though it’s less explicit than using TerminateAsync.

Example:

else
{
    logger.LogWarning("Cannot connect: Authentication information is not cached. Orchestration exiting early.");
    return new List<Match>();
}

Why TerminateAsync is better than throwing an exception: #

• Throwing an exception marks the orchestration as Failed, which implies an unexpected error. TerminateAsync makes it clear this was an intentional, graceful shutdown for a known condition.
• The custom reason message gives immediate visibility into why the orchestration stopped, no need to dig through stack traces.

For your scenario, TerminateAsync is the most clean and explicit approach to handle graceful termination with a friendly explanation.

内容的提问来源于stack exchange，提问作者Sam Vanhoutte