Difficult to get a grip of documentation for Azure Functions

[marnilss]

@cgillum as requested :-)

A number of reasons:

• I'm familiar with ASP.Net Core, Azure App Services and webjobs, so after seeing the first sample C# of a Function App, I thought: "this looks a lot like Webjobs"!. Documentation says nothing about it, but when looking at names of nuget packages etc. you will definitely see that it is "related" to Webjobs.
  • When searching for documentation for e.g. "Singleton" you are left with the question: - does the Webjobs-Singleton attribute work or not? I still don't know, but guess I have to test for myself.
• Versioning: "Azure functions 4.0", "v4" versus nuget package versions. Having multiple versioning schemes is confusing:
  • Microsoft.NET.Sdk.Functions is 4.0.1 - OK that might correlate to v4
  • Microsoft.Azure.Functions.Extensions is 1.1.0 - Is that still valid, or has it been superseeded by something else?
  • It isn't enought to upgrade the nuget package version, you also need to change version-number
    • in csproj
    • Run cli-command to update Azure resource - you can't do it via Azure Portal UI.
      • Text says to "To migrate an app from 3.x to 4.x, set the FUNCTIONS_EXTENSION_VERSION application setting to ~4 with the following Azure CLI command:",
        but hidden in sample is also "# For Windows function apps only, also enable .NET 6.0 that is needed by the runtime"
  • ASP.NET Core are using SDKs on project-level, which then follow the targetframework setting - easier and simple in my opinion.
• Breaking changes v3 to v4: Nice to get a list of Github issues :-( . Are all of us meant to scan all comments/commits and find out what the actual breaking change are?
  • And how about breaking changes in the packages usually used with Azure functions (e.g. in Microsoft.Azure.WebJobs.Extensions.ServiceBus). Although we analyzed the documentation of breaking changes before deciding to upgrade, we got surprised by a deprecated type when using ServiceBusTrigger, "Message" had to be changed to "ServiceBusReceivedMessage".
• Documentation isn't complete: https://docs.microsoft.com/en-us/azure/azure-functions/functions-identity-based-connections-tutorial-2
  • No mention of AZURE_CLIENT_ID which also needs to be set, otherwise you'll get an error

Generally I think it is difficult to differentiate between

• Azure Functions App (Azure resource)
• Azure Functions/Function App in broad marketing term
• Webjob packages
• Function packages
• extensions to Webjobs (DurableTask, ServiceBus etc.).

Sometimes "features"/extensions such as Durable functions are mentioned at the same time as "Azure Functions 4.0" (https://techcommunity.microsoft.com/t5/apps-on-azure-blog/azure-functions-4-0-and-net-6-support-are-now-generally/ba-p/2933245), and makes you think it is under the "Azure functions" umbrella. But at the same time other documents doesn't include it at all (like breaking changes document).
So either treat it as separate individual components, and only reference them, or include them under the "Azure Function"/"Function App" umbrella and include them all in same versioning-scheme/major-version and documentation on roadmaps, upgrade instructions and breaking changes.

[cgillum]

Thanks @marnilss for this detailed feedback. I agree with a ton of it and I'm often confused myself about things like nuget package version numbers when trying to build samples. I'm tagging @anirudhgarg and @eamonoreilly here so that they can pass this feedback along to the right folks who work on the Azure Functions documentation.

[anirudhgarg]

Thanks @marnilss - will follow up on your feedback on the documentation as well. Meanwhile for v3 to v4 breaking changes we documented them here: https://docs.microsoft.com/en-us/azure/azure-functions/functions-versions?tabs=in-process%2Cv4&pivots=programming-language-csharp#breaking-changes-between-3x-and-4x

[marnilss]

BUT, you do also on that page state:

For a full list, see Azure Functions GitHub issues labeled Breaking Change: Approved.

So it can be interpreted as only the highlights are on that page.

And as I said, it only covers the changes in Azure Functions Host, not any of the extensions/bindings.

[anirudhgarg]

Extensions and Bindings are not necessarily tied to v4, they have their own versioning. But I can see how that can be confusing. We will keep working to make this clearer.

[anirudhgarg]

Also everyone of the breaking change is formatted cleanly with all the details - you dont have to go through the PR's :)