Write a well designed async / non-async API

Question

I\'m facing the problem of designing methods that with performs network I/O (for a reusable library). I\'ve read this question

c# 5 await/async pattern in API design

Answer 1

I ran into the same problem but managed to find a compromise between efficiency and maintainability using two simple facts about async methods:

• asynchronous method which does not execute any await is synchronous;
• asynchronous method which awaits only synchronous methods is synchronous.

This is better to be shown on example:

//Simple synchronous methods that starts third party component, waits for a second and gets result.
public ThirdPartyResult Execute(ThirdPartyOptions options)
{
    ThirdPartyComponent.Start(options);
    System.Threading.Thread.Sleep(1000);
    return ThirdPartyComponent.GetResult();
}

To provide maintainable sync/async version of this method it has been split to three layers:

//Lower level - parts that work differently for sync/async version.
//When isAsync is false there are no await operators and method is running synchronously.
private static async Task Wait(bool isAsync, int milliseconds)
{
    if (isAsync)
    {
        await Task.Delay(milliseconds);
    }
    else
    {
        System.Threading.Thread.Sleep(milliseconds);
    }
}

//Middle level - the main algorithm.
//When isAsync is false the only awaited method is running synchronously,
//so the whole algorithm is running synchronously.
private async Task Execute(bool isAsync, ThirdPartyOptions options)
{
    ThirdPartyComponent.Start(options);
    await Wait(isAsync, 1000);
    return ThirdPartyComponent.GetResult();
}

//Upper level - public synchronous API.
//Internal method runs synchronously and will be already finished when Result property is accessed.
public ThirdPartyResult ExecuteSync(ThirdPartyOptions options)
{
    return Execute(false, options).Result;
}

//Upper level - public asynchronous API.
public async Task ExecuteAsync(ThirdPartyOptions options)
{
    return await Execute(true, options);
}

The main advantage here is that middle level algorithm which is most likely to change is implemented only once so developer don't have to maintain two almost identical pieces of code.