Share via

how to name a method starting async but not returning awaitable type

rajesh yadav 291 Reputation points
2025-07-07T10:13:30.8666667+00:00

this is a line from msdn which i could not understand as there  was no examle pls give one example

https://learn.microsoft.com/en-us/dotnet/csharp/asynchronous-programming/task-asynchronous-programming-model#BKMK_ReturnTypesandParameters

Methods that start an asynchronous operation but do not return an awaitable type should not have names that end with "Async", but may start with "Begin", "Start", or some other verb to suggest this method does not return or throw the result of the operation.

Developer technologies | ASP.NET | ASP.NET Core

2 answers

Sort by: Most helpful
  1. Jack Dang (WICLOUD CORPORATION) 17,170 Reputation points Microsoft External Staff Moderator
    2025-07-08T07:55:31.3333333+00:00

    Hello @rajesh yadav ,

    Thanks for reaching out.

    Let's clarify the MSDN Guidance on Async Naming first.The original MSDN line states that: "Methods that start an asynchronous operation but do not return an awaitable type should not have names that end with 'Async', but may start with 'Begin', 'Start', or some other verb to suggest this method does not return or throw the result of the operation."

    What this means is that in C#, it's a common convention to name asynchronous methods with the suffix Async only if they return an awaitable type like Task or Task<T>. This tells developers, "Hey, you can await this method." But if a method starts an asynchronous operation and doesn't return a Task, then it shouldn't end with Async. Instead, use a prefix like Begin, Start, or something similar to indicate that the method kicks off an async process but doesn't itself support await.

    Let’s say you’re working with a legacy API or a custom event-based async pattern.

    public class FileDownloader
    {
        // This method starts an async operation but does NOT return a Task.
        public void BeginDownload(string url)
        {
            // Starts downloading the file asynchronously.
            // The result will be delivered via an event or callback.
            WebClient client = new WebClient();
            client.DownloadFileCompleted += (s, e) =>
            {
                Console.WriteLine("Download completed!");
            };
            client.DownloadFileAsync(new Uri(url), "localfile.txt");
        }
    }
    

    BeginDownload starts downloading a file asynchronously, but it doesn't return a Task, so you can't await it.

    Instead, it uses the event-based async pattern (DownloadFileAsync + DownloadFileCompleted).

    The method name starts with Begin to signal that it initiates an async operation, but you’ll get the result via an event, not a return value.

    If you named it DownloadAsync, it would imply that you could do this:

    await downloader.DownloadAsync(url); // Misleading — this won't compile
    

    But since the method doesn't return a Task, that would be incorrect and confusing.

    // Correct usage:
    downloader.BeginDownload(url); // Starts the operation, result comes via event
    

    Final thoughts:

    Use Async suffix only if the method returns Task or Task<T>.

    Don’t use Async if the method doesn’t return an awaitable type.

    Use prefixes like Begin, Start, etc., for methods that kick off async work but don’t return a result directly.

    Hope my answer helps clarify your concern.

    1 person found this answer helpful.

  2. SurferOnWww 5,931 Reputation points
    2025-07-07T12:05:15.5533333+00:00

    Please write your quetion properly.

    You took the description in your question form the Microsoft document Naming convention, not the url you wrote in your question.

    "By convention, methods that return commonly awaitable types (for example, Task, Task<T>, ValueTask, ValueTask<T>) should have names that end with "Async". Methods that start an asynchronous operation but do not return an awaitable type should not have names that end with "Async", but may start with "Begin", "Start", or some other verb to suggest this method does not return or throw the result of the operation."

    "You can ignore the convention where an event, base class, or interface contract suggests a different name. For example, you shouldn't rename common event handlers, such as OnButtonClick."

    Are you looking for an example which uses "Begin"? If so, see the Microsoft document Asynchronous Programming Model (APM).

    Note that the APM is old as shown below and probably nobody uses it now.

    enter image description here

    0 comments No comments

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.