Going 100% async + Naming convention changes

[jansenbe]

Problem description

We're facing following problems:

• We need to get rid of all GetAwaiter() method calls (used to make an async call sync) as they're causing deadlocks/exceptions when used in Blazor (maybe as well on mobile platforms). @PaoloPia is almost done implementing async LINQ support, but there's still several places where we use GetAwaiter().
• Our public API naming might be confusing: below tables shows our current implementation, notice how our the method calls that add a request to a batch are synchronous and named like Get() or Update(). This might be confusing for library users as one would expect a result for a Get().

Proposed solution - need your input here

As a way around both problems I was thinking of the following:

• All public methods are always async: this will allow us to also fully use internal async methods and as such remove the need for GetAwaiter() in our SDK code base
• If library users want to make sync call they'll have to add GetAwaiter().GetResult() themselves. Question: would that bother developer a lot you think?
• Due to above we also need to make the 'batch' methods async. To avoid name conflicts and to be clear on what a method does I was thinking about adding the BatchAsync suffic to method calls that add a request to a batch. Below table shows then then the new names:

Tagging @PaoloPia , @ypcode , @pkbullock , @JarbasHorst for awareness, but feedback from anyone is welcome!

[ypcode]

Hi @jansenbe,

I totally support the naming convention!
Regarding the use of GetAwaiter().GetResult(), I think that might be a bit cumbersome in user code, especially in console apps, webjobs, etc...
More than cumbersome, it could be really a pain to use because in sync programs, it stops before the tasks are done, and it can quickly become hard to figure out...

Do you think it would be that big deal to add a specific synchronous variant (for instance with a "-Synchronously" suffix that would emphasize it has to be used in specific context ?
That combined with relevant docs that it should be async first and , synchronous in context it's specifically needed (console apps, ...)

The main thing is indeed to switch to always async code in the internals but then a wrapper would be useful on sync, in a sense, just the other way around of what it is right now.

[jansenbe]

Adding a sync wrapper does make sense, assuming it's only done at the "top" level, the internal implementation must be fully async to ensure our public async methods stay working. So then we would have something like this:

Method	Async
GetAsync()	Yes
Get()	No
GetBatchAsync()	Yes
GetBatch()	No

In above the Get() would simply use call GetAsync().GetAwaiter().GetResult().

[ypcode]

Sure, but I would even emphasize more the Synchronous behaviour with a suffix
So the user won't be tempted to use a method with a generic name (e.g GetSynchronously() instead of Get()) in a context that does not support it.

You know me :P I find it definitively less elegant, but still,... simply Get() would be misleading, I'd think

I know it's not really following the common Async naming convention in .NET (Will that convention really last long, anyway, all modern library tend to be async only nowadays...). But that would ensure that users know that synchronous method are for specific purposes.

What do you think?

[JarbasHorst]

Hello @jansenbe, hello @ypcode

the suggested naming convention is a very good idea! If we want to support sync methods, I wouldn't add the synchronous suffix to the end of a sync method. If we would have GetAsync and Get, I believe it is clear what Get is therefor. What do you think?

[pkbullock]

I believe we should stay with industry recognised naming for synchronous E.g no suffix for sync. It is implied that if we method is Async, the other is not.

Naming is good, best to align now before this comes out of preview.

[jansenbe]

Think we've quorum then, once Paolo has committed the async LINQ updates I'll update the solution based upon this naming convention:

Method	Purpose	Async
GetAsync()	Regular get	Yes
Get()	Regular sync get	No
GetBatchAsync()	Batch method	Yes
GetBatch()	Sync batch method	No
GetByTitleAsync()	LINQ extension method	Yes
GetByTitle()	Sync LINQ extension method	No

Thanks everyone for your input.