Example uses feature only available in C# 7.1

[Camios]

In the example, the entry point's signature "static async Task Main()" is only available for c# v7.1 and above.
Visual Studio defaults to the major version which at time of writing is only 7.0 and most users will get a compilation error, unless they modify the advanced build properties to change the c# version. Is this asking too much of someone trying to learn the framework?
For those using C# 7.0 the main method would look more like this:
static void Main()
{
ReadCharacters().Wait();
}

Note: there's appears to be conflicting opinions on using Wait() vs GetAwaitor().GetResult(). The documentation for GetAwaiter states it is for compiler use only, but I've seen discussions suggesting it should be used: https://stackoverflow.com/questions/17284517/is-task-result-the-same-as-getawaiter-getresult

BTW C# 7.1 and above use GetAwaitor().GetResult() - it generates code which replaces and wraps the async entry point with GetAwaitor().GetResult().
public static void Main(string[] args) => $MainEntrypoint$(args).GetAwaitor().GetResult();
private static async Task $MainEntrypoint$(string[] args) { await ... }
https://blogs.msdn.microsoft.com/mazhou/2017/05/30/c-7-series-part-2-async-main/

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: aa3850da-1adf-a7e9-4c64-5d8327839798
• Version Independent ID: 167ba859-4b1e-eaa4-8d9a-c2e695583187
• Content: StreamReader.ReadLineAsync Method (System.IO)
• Content Source: xml/System.IO/StreamReader.xml
• Product: dotnet-api
• GitHub Login: @dotnet-bot
• Microsoft Alias: dotnetcontent

[BillWagner]

Thanks for writing this @Camios

One concern will be addressed by dotnet/roslyn#26326 That will raise visibility on the warning to upgrade to 7.1

I prefer the GetAwaiter().GetResult() recommendation because it does work with other possible return types, such as ValueTask.

I'll leave this open and add it to the backlog.

The right fix would be to mention that C# 7.1 is needed for this sample. I've added it to our backlog, and added the "up for grabs" lable.

[Camios]

Hi Bill, My outstanding concern about the use of GetAwaiter method is the framework documentation where in the remarks paragraph says it is for compiler use. I assume the Application code alternative is to call the Result property. Kind regards, Cameron

On Mon, 12 Nov 2018 at 9:56 am, Bill Wagner ***@***.***> wrote: Thanks for writing this @Camios <https://github.com/Camios> One concern will be addressed by dotnet/roslyn#26326 <dotnet/roslyn#26326> That will raise visibility on the warning to upgrade to 7.1 I prefer the GetAwaiter().GetResult() recommendation because it does work with other possible return types, such as ValueTask. I'll leave this open and add it to the backlog. The right fix would be to mention that C# 7.1 is needed for this sample. I've added it to our backlog, and added the "up for grabs" lable. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <https://github.com/dotnet/docs/issues/8850#issuecomment-437717696>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACrj0171cDU8lG0Q-oIfluDt4FhfTUJJks5uuLkggaJpZM4YNyfL> .

-- Sent from Gmail Mobile, I apologise for any typos.

[BillWagner]

Ping @stephentoub

What are your thoughts on the above discussion re: Task.Result vs. GetAwaiter().GetResult()?

[stephentoub]

The difference ends up being entirely about exception propagation. Task.Result/.Wait() wrap the one or more exceptions stored in the Task into an AggregateException and throw that aggregate exception. Task.GetAwaiter().GetResult() uses the same support as for await, hence GetAwaiter(), in order to propagate one exception stored in the Task. If you know that the Task will never contain more than one exception and you want that instance propagated, then use .GetAwaiter().GetResult(); that will be the case for any Task created as the result of an async Task method. If you know that Task may contain multiple exceptions and if you care about them all (e.g. Task.WhenAll used on multiple operations that may each fail), then you may want the .Result/.Wait behavior. And if you don't care about exceptions and just want slim code, .Result/.Wait are shorter.

I prefer the GetAwaiter().GetResult() recommendation because it does work with other possible return types, such as ValueTask.

.GetAwaiter().GetResult() should only be used with ValueTask if the ValueTask is known to already be completed. It should not be assumed to block, as it won't in various implementations. See https://blogs.msdn.microsoft.com/dotnet/2018/11/07/understanding-the-whys-whats-and-whens-of-valuetask/ for more details. You're welcome to poach from that for docs.

My outstanding concern about the use of GetAwaiter method is the framework
documentation where in the remarks paragraph says it is for compiler use. I
assume the Application code alternative is to call the Result property.

We should just update those docs. It's fine to use directly.