Added new anti pattern blocking async code

[dhedgepeth]

📋 Description

Adds new section documenting an anti-pattern for blocking async code, something we are seeing more frequently.

✅ Contributor Checklist

I've followed the Umbraco Documentation Style Guide and can confirm that:

• Code blocks are correctly formatted.
• Sentences are short and clear (preferably under 25 words).
• Passive voice and first-person language (“we”, “I”) are avoided.
• Relevant pages are linked.
• All links work and point to the correct resources.
• Screenshots or diagrams are included if useful.
• Any code examples or instructions have been tested.
• Typos, broken links, and broken images are fixed.

Product & Version (if relevant)

CMS 13-17

📚 Helpful Resources

• 🧾 Umbraco Contribution Guidelines
• ✍️ Umbraco Documentation Style Guide

[sofietoft]

Thanks for the PR @dhedgepeth ! 🙌

Could you remove the changes to the v15 article from this PR? The version has been unpublished and removed, so that's why it's currently causing merge conflict.

Also, the vale linter is warning about the use of "relatively" and "significantly". Could you rewrite the sentences where these words are used?

Finally: Do you need a technical review on this as well?

[dhedgepeth]

Hey @sofietoft I've removed the changes to the v15 article and updated the articles to no longer use "significantly" or "relatively"😁

What's the right/best process for a technical review of the article?
And thank you for taking a look, please let me know if you have any further suggestions! 🙌

[sofietoft]

Great, @dhedgepeth ! Thanks for resolving the merge conflicts 💪

Post a link to the PR in the umbraco-cms channel on our internal Slack.
Then someone from the CMS teams will help us with a review 🙌

[kjac]

The changes look good 👍

But ... are we really supposed to document ASP.NET Core best practices in our documentation? One might argue that these things belong at the source (MS docs), not on our docs platform. Something to consider, before merging this.

[meyntony]

@kjac Totally agree, but we need this somewhere in our docs because we have a lot of customers in Cloud doing this, so maybe this does not belong to the CMS specifically.

@dhedgepeth Maybe you could include the examples on how customers use int.Max to get all the content and then using a .Result as examples so its a lot more relevant to the cases we see in our Code reviews. Lets keep them to common problems we see with regarding to implementing on top of Umbraco?

[dhedgepeth]

@meyntony I think I will open a new PR to add the use of int.MaxValue

I definitely see the argument since this is more .NET best practice, but we have seen an increase in customers using this antipattern.
@sofietoft what are your thoughts about having this added?

[sofietoft]

I agree that we shouldn't document common ASP.NET practices in our docunmentation, when we could refer them to Microsofts own docs instead.
This, however, seems like something that could benefit our Cloud users, seeing it's something you're often dealing with in the support channels.

How about we do either of the following:

a) Add a note to the beginning of this new section, mentioning how this is especially relevant for Cloud projects.
b) We move this to a new "Common pitfalls" or similar, article in the Cloud documentation.

I'm happy with either.

[kjac]

@sofietoft ah but this is not especially relevant to Cloud projects. It is relevant to any .NET project, and perhaps ASP.NET Core projects in particular, since they're likely serving a lot of requests as public facing websites.

Now, don't get me wrong... I don't mind this section being added. I simply wanted to note that we have historically shunned from replicating MS docs in our own to the extent possible, to avoid having to keep our docs in line with the MS docs.

[meyntony]

@sofietoft ah but this is not especially relevant to Cloud projects. It is relevant to any .NET project, and perhaps ASP.NET Core projects in particular, since they're likely serving a lot of requests as public facing websites.

Now, don't get me wrong... I don't mind this section being added. I simply wanted to note that we have historically shunned from replicating MS docs in our own to the extent possible, to avoid having to keep our docs in line with the MS docs.

I guess we could point to the official docs describing this common pitfall from ours? Would it be this? https://learn.microsoft.com/en-us/dotnet/csharp/asynchronous-programming/async-scenarios#synchronous-access-to-asynchronous-operations

The reason we need it in ours, is because customers use our docs to check what the common pitfalls are before submitting a Code Review ticket, and although this is specific to .NET implementation, its a very common anti pattern we notice almost in all the tickets we get these days.

[sofietoft]

I should have been more clear: I merely meant that it sounds like Davis is adding this due to them seeing issue related to it on Cloud sites.
Therefor my suggestion to add a note about it, or move it to the Cloud docs.

I strongly agree that we should continue to shun from replicated the Microsoft docs in ours. We can't maintain those docs easily.

@meyntony If we could describe it shortly in our docs, and then reference the microsoft docs article, that would be a great solution!
As long as you feel it covers what you need our customers to be aware of in terms of the issue you're seeing on Cloud 💪