Azure-functions-durable-extension: Improve documentation on forbidden APIs in orchestrator functions

[cgillum]

Summary

Today the documentation talks generally about the things to avoid when writing orchestrator functions, like avoiding I/O, avoiding async execution, etc. but doesn't provide many concrete examples that can be referenced. This issue tracks documenting more extensively APIs that should be avoided when writing orchestrator functions.

Most likely this should exist as a wiki page on the GitHub repo since it may need to be updated frequently.

Motivation

The motivation is to minimize the number of people that run into issues. For example, issue #56 was a case where Task.Factory.StartNew was used and caused execution problems - but it's not entirely clear why this is a problem. Having documentation which explicitly calls out APIs like this will help users who may not be sure whether an API is problematic.

[SimonLuckenuik]

Please consider Roslyn analyzers as well, doing those IO inside the orchestrator function is a major issue.

[cgillum]

@fabiocav made a similar suggestion some time back. I think we should definitely look into this.

[petarvucetin]

I have spent most of my day trying to figure out why adding key vault client caused orchestrator to never complete. I did not realize that no I/O was allowed from orchestrator.

[cgillum]

For future reference, orchestrator code constraints are documented here: https://docs.microsoft.com/en-us/azure/azure-functions/durable-functions-checkpointing-and-replay#orchestrator-code-constraints

[cgillum]

Also, for C# orchestrator functions, we now have a Durable Functions Roslyn source code analyzer that can automatically flag code violations. This analyzer is included by default starting with the v2.2.0 version of the Durable Functions extension package.