async.txt

----------
20200312

async-await-TASK 摘要: (另外可參考 AsyncAwaitTask 目錄).
1. async 跟 await 是成對的關鍵字. 
2. asycn 後面的函數, 會以非同步方式執行, 不會封鎖 (blocking) 原來呼叫的主執行緒.
3. 在函數內必須包含 await 指令.
4. 在函數內碰到 await 指令時, 將會等待 await 指令的工作完成, 才會繼續執行 await 之後的程式碼.
5. 函數內可以包含多個 awailt 工作.
6. async 函數名稱建議字尾為async.
7. 回傳值有4種:
	A. Task: 完成的工作, 無工作回傳值.
	B. Task<TResult>: 完成工作含回傳值TResult. 可以 await 
	C. void. 呼叫者不能以 await 方式呼叫, 也無法捕捉到內部 exception. 主要使用於 event handlers 事件處理函數. 
	D. 內含GetAwaiter()方法的回傳值. (C# 7.0 以上才支援. VS 2017, .NET 4.6.2)
8. Exception: 
	A. 除了(回傳 void)的方式, 無法捕捉到 exception 以外, 其餘均可由外部(呼叫端), 捕捉到(async 函數)內部的 exception.
	B. 建議 Task 函數內部的錯誤處理, 應直接拋送到外部, 不應封裝 exception, 否則無法捕捉到正確的錯誤資訊. 
9. 中止非同步工作: CancellationToken

----------
Asynchronous Programming with async and await:
Task asynchronous programming model:
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/
async-await-Task-Programming.pdf

An async method runs synchronously until it reaches its first await expression, at which point the method is suspended until the awaited task is complete. In the meantime, control returns to the caller of the method, as the example in the next section shows.
If the method that the async keyword modifies doesn't contain an await expression or statement, the method executes synchronously. A compiler warning alerts you to any async methods that don't contain await statements, because that situation might indicate an error. 


Return Types

An async method can have the following return types:
1. Task
2. Task<TResult>
3. void. 
async void methods are generally discouraged for code other than event handlers because callers cannot await those methods and must implement a different mechanism to report successful completion or error conditions.

4. Starting with C# 7.0, any type that has an accessible GetAwaiter method. The System.Threading.Tasks.ValueTask<TResult> type is one such implementation. It is available by adding the NuGet package System.Threading.Tasks.Extensions.

The async method can't declare any in, ref or out parameters, nor can it have a reference return value, but it can call methods that have such parameters.

You specify Task<TResult> as the return type of an async method if the return statement of the method specifies an operand of type TResult. You use Task if no meaningful value is returned when the method is completed. That is, a call to the method returns a Task, but when the Task is completed, any await expression that's awaiting the Task evaluates to void.

You use the void return type primarily to define event handlers, which require that return type. The caller of a void-returning async method can't await it and can't catch exceptions that the method throws.

Starting with C# 7.0, you return another type, typically a value type, that has a GetAwaiter method to minimize memory allocations in performance-critical sections of code.

public static async void DelayAsync(int iMs)
{
	// CodeHelper
	// 備忘:	
	// 1. async 跟 await 是成對的關鍵字. 
	// 2. asycn 後面的函數, 會以非同步方式執行, 不會封鎖 (blocking) 原來呼叫的主執行緒.
	// 3. 在函數內必須包含 await 指令.
	// 4. 在函數內碰到 await 指令時, 將會等待 await 指令的工作完成, 才會繼續執行 await 之後的程式碼.
	// 5. 函數內可以包含多個 awailt 工作.
	// 6. 回傳值有4種
	

	await Task.Delay(iMs);  // Sample: async, await.
}


以下 sample 以非同步方式呼叫httpClient.GetStringAsync()

private async void StartButton_Click(object sender, RoutedEventArgs e)
{
    // ExampleMethodAsync returns a Task<int>, which means that the method  
    // eventually produces an int result. However, ExampleMethodAsync returns  
    // the Task<int> value as soon as it reaches an await.  
    ResultsTextBox.Text += "\n";

    try
    {
        int length = await ExampleMethodAsync();
        // Note that you could put "await ExampleMethodAsync()" in the next line where  
        // "length" is, but due to when '+=' fetches the value of ResultsTextBox, you  
        // would not see the global side effect of ExampleMethodAsync setting the text.  
        ResultsTextBox.Text += String.Format("Length: {0:N0}\n", length);
    }
    catch (Exception)
    {
        // Process the exception if one occurs.  
    }
}

public async Task<int> ExampleMethodAsync()
{
    var httpClient = new HttpClient();
    int exampleInt = (await httpClient.GetStringAsync("http://msdn.microsoft.com")).Length;
    ResultsTextBox.Text += "Preparing to finish ExampleMethodAsync.\n";
    // After the following return statement, any method that's awaiting  
    // ExampleMethodAsync (in this case, StartButton_Click) can get the   
    // integer result.  
    return exampleInt;
}
// The example displays the following output:  
// Preparing to finish ExampleMethodAsync.  
// Length: 53292


----------
20181226

The following example shows how you declare and call a method that returns a Task<TResult> or a Task.

ref:
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/index

// Signature specifies Task<TResult>  
async Task<int> TaskOfTResult_MethodAsync()  
{  
    int hours;  
    // . . .  
    // Return statement specifies an integer result.  
    return hours;  
}  
  
// Calls to TaskOfTResult_MethodAsync  
Task<int> returnedTaskTResult = TaskOfTResult_MethodAsync();  
int intResult = await returnedTaskTResult;  
// or, in a single statement  
int intResult = await TaskOfTResult_MethodAsync();  
  
// Signature specifies Task  
async Task Task_MethodAsync()  
{  
    // . . .  
    // The method has no return statement.    
}  
  
// Calls to Task_MethodAsync  
Task returnedTask = Task_MethodAsync();  
await returnedTask;  
// or, in a single statement  
await Task_MethodAsync();

----------
20181117

ref:
In .Net 4.5 Microsoft has added the new Async/Await feature to simplify asynchronous coding. However, I wonder 
1.Can Async/Await completely replace the old way of using Threads?
2.Is Async/Await capable of doing whatever a Thread can do asynchronously?
3.Can Async/Await only be used with some methods like WebClient.DownloadStringAsync or can I convert any synchronous method to make it use Async/Await and not to block the main thread?

can it completely replace the old way of using Threads ?
No. A thread can do many more useful things. Await is specifically designed to deal with something taking time, most typically an I/O request. Which traditionally was done with a callback when the I/O request was complete. Writing code that relies on these callbacks is quite difficult, await greatly simplifies it.
Await可取代Threads的作法嗎?
No! Thread可以做更多的事情. Await則較適用於耗時, 尤其是輸入輸出的作業. 傳統上在輸入輸出作業完成時, 會呼叫回呼函數. 撰寫回呼函數較困難, 利用Await可簡化程式撰寫.

capable of doing what ever a Thread can do asynchronously ?
Roughly. Await just takes care of dealing with the delay, it doesn't otherwise do anything that a thread does. The await expression, what's at the right of the await keyword, is what gets the job done. Ideally it doesn't use a thread at all, it posts a driver request and once the driver completes the data transfer it generates a completion notification callback. Networking is by far the most common usage, latencies of hundreds of milliseconds are common and an inevitable side-effect of services moving from the desktop or a LAN into "the cloud". Using such services synchronously would make a UI quite unresponsive.
Async可以完成所有Thread的非同步做法嗎?
幾乎都可以完成. Await 敘述僅處理延遲的問題, 不像thread還可以做其他的事情. 在 await關鍵字後面銜接需要完成的工作. 理論上, 完全沒有使用到thread, 就可以提出請求作業, 直到請求完成時, 再通知回呼函數. 網路作業是目前最常見的用法, 數百毫秒的延遲是常見的, 並且服務從桌面或區網轉移到雲是必然的影響. 以同步方式使用這類網路服務, 將會讓操作介面無法回應. 

only can be used with some methods like WebClient.DownloadStringAsync
No. You can use it with any method that returns a Task. The XxxxAsync() methods are just precooked ones in the .NET framework for common operations that take time. Like downloading data from a web server.
Async只能用在類似 WebClient.DownloadStringAsync ?
No! 可以用在任何回傳Task的方法. 字尾為...Async()方法是.net framework常見的需要時間完成的命名習慣.



----------
20181112

async [Task<TResult>] await [Task<TResult>]

ref: 
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/index

// Three things to note in the signature:  
//  - The method has an async modifier.   
//  - The return type is Task or Task<T>. (See "Return Types" section.)  
//    Here, it is Task<int> because the return statement returns an integer.  
//  - The method name ends in "Async."  
async Task<int> AccessTheWebAsync()   // 1. 方法必須有async修飾詞, 2. 回傳類型為 Task 或 Task<T>, 3. 方法習慣以"Async"結尾.
{   
    // You need to add a reference to System.Net.Http to declare client.  
    HttpClient client = new HttpClient();  
  
    // GetStringAsync returns a Task<string>. That means that when you await the  
    // task you'll get a string (urlContents).  
    Task<string> getStringTask = client.GetStringAsync("https://msdn.microsoft.com");  // HttpClient.GetStringAsync() 回傳 Task<string>.
  
    // You can do work here that doesn't rely on the string from GetStringAsync.  
    DoIndependentWork();  // 此處會同步執行, 不會等待 HttpClient.GetStringAsync() 完成後才執行.
  
    // The await operator suspends AccessTheWebAsync.  
    //  - AccessTheWebAsync can't continue until getStringTask is complete.  
    //  - Meanwhile, control returns to the caller of AccessTheWebAsync.  
    //  - Control resumes here when getStringTask is complete.   
    //  - The await operator then retrieves the string result from getStringTask.  
    string urlContents = await getStringTask;  // await 指令會在此處等待 getStringTask 完成後, 取得結果的字串, 再繼續執行. 
  
    // The return statement specifies an integer result.  
    // Any methods that are awaiting AccessTheWebAsync retrieve the length value.  
    return urlContents.Length;  // 回傳 整數值. 
}

The following characteristics summarize what makes the previous example an async method.
以下摘要前一個範例的實作非同步方法:
1. The method signature includes an async modifier.
   在方法的簽名中, 包含一個'async'修飾詞.
2. The name of an async method, by convention, ends with an "Async" suffix.
   習慣上命名非同步的方法名稱, 以"Async"結尾.  
3. The return type is one of the following types:
   回傳類型如下:
3.1 Task<TResult> if your method has a return statement in which the operand has type TResult.
   若 呼叫的方法有回傳值, 則以 TResult 回傳.
3.2 Task if your method has no return statement or has a return statement with no operand.
   若 呼叫的方法沒有回傳值.
3.3 void if you're writing an async event handler.
   若 呼叫的方法為非同步事件處理函數.
3.4 Any other type that has a GetAwaiter method (starting with C# 7.0).
   若 使用 C# 7.0, 則可以 GetAwaiter 方法回傳.
   
4. The method usually includes at least one await expression, which marks a point where the method can't continue until the awaited asynchronous operation is complete. In the meantime, the method is suspended, and control returns to the method's caller. The next section of this topic illustrates what happens at the suspension point.
非同步方法中, 通常包含至少1個 await 運算式, 代表必須等待 此非同步作業完成後, 才會繼續執行.

In async methods, you use the provided keywords and types to indicate what you want to do, and the compiler does the rest, including keeping track of what must happen when control returns to an await point in a suspended method. Some routine processes, such as loops and exception handling, can be difficult to handle in traditional asynchronous code. In an async method, you write these elements much as you would in a synchronous solution, and the problem is solved.
For more information about asynchrony in previous versions of the .NET Framework, see TPL and Traditional .NET Framework Asynchronous Programming.




Return types and parameters
An async method typically returns a Task or a Task<TResult>. Inside an async method, an await operator is applied to a task that's returned from a call to another async method.
async 方法通常回傳 Task 或 Task<TResult>. 在 async 方法中可使用 await 運算子 回傳再呼叫的非同步方法.

You specify Task<TResult> as the return type if the method contains a return statement that specifies an operand of type TResult.
You use Task as the return type if the method has no return statement or has a return statement that doesn't return an operand.
Starting with C# 7.0, you can also specify any other return type, provided that the type includes a GetAwaiter method. ValueTask<TResult> is an example of such a type. It is available in the System.Threading.Tasks.Extension NuGet package.
The following example shows how you declare and call a method that returns a Task<TResult> or a Task.
以下範例示範回傳Task<TResult> or a Task:

// 回傳 Task<TResult>
// Signature specifies Task<TResult>   
async Task<int> TaskOfTResult_MethodAsync()  
{  
    int hours;  
    // . . .  
    // Return statement specifies an integer result.  
    return hours;  
}  
  
// Calls to TaskOfTResult_MethodAsync  
Task<int> returnedTaskTResult = TaskOfTResult_MethodAsync();  
int intResult = await returnedTaskTResult;  
// or, in a single statement  
int intResult = await TaskOfTResult_MethodAsync();  
  
// 回傳 Task
// Signature specifies Task  
async Task Task_MethodAsync()  
{  
    // . . .  
    // The method has no return statement.    
}  
  
// Calls to Task_MethodAsync  
Task returnedTask = Task_MethodAsync();  
await returnedTask;  
// or, in a single statement  
await Task_MethodAsync();


以下為簡單使用 async...await 實作 非同步方法 呼叫.
        public static async void BlinkAsync(Control control1, Color color1) // Sample: async
        {
            Color colorOld = control1.BackColor;
            while (true)  // 可由外面改變這個Boolean決定是否結束迴圈. 但是不能透過ref或out參數傳送.
            {
                await Task.Delay(500);  // Sample: await.
                //label1.BackColor = label1.BackColor == Color.Red ? Color.Green : Color.Red;
                //c1.BackColor = c1.BackColor == Color.Red ? Color.Green : Color.Red;
                control1.BackColor = control1.BackColor == colorOld ? color1 : colorOld;
            }
        }



----------
20181109

async and await

C# 5 and .NET Framework 4.5 above support.

ref: 
https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/await
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/index
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/async-return-types


----------
摘要.
1. async, await 關鍵字在(C# 5(即vs 2012) and .NET Framework 4.5)以上才支援.
2. await 只能在 async 的函數中使用.
3. await 依據銜接的函數回傳以下型態: 
    參考: async-ReturnTypes.txt:
	
    1. Task<TResult> 呼叫方法有回傳值
	   await keyword used with a method that returns a Task<TResult>.
       Task<TResult> if your method has a return statement in which the operand has type TResult. 
       語法: TResult result = await AsyncMethodThatReturnsTaskTResult();  
	   
    2. Task 呼叫方法無回傳值
	   await keyword used with a method that returns a Task.
	   Task if your method has no return statement or has a return statement with no operand. 
       語法: await AsyncMethodThatReturnsTask();  
	   
此方式在 Task 方法中, 若因 compile不通過, 需要回傳值時, 則可如下例回傳:			 
timer.Elapsed += async ( sender, e ) => await HandleTimer();
private Task HandleTimer()
{
    Console.WriteLine("\nHandler not implemented..." ); 
    return Task.FromResult<object>(null);
}
	   
    3. void: which should only be used for event handlers.
	   The caller of a void-returning async method can't await it and can't catch exceptions that the method throws. 
	   注意此方式不會捕捉方法拋出的exception!
  
    4. Any other type that has a GetAwaiter method (starting with C# 7.0).
4. await 不會鎖住(Block)目前的執行緒, 而是((繼續執行下一個指令) 並且 (非同步執行 指定的函數)). 

5. 
            // 若async方法中缺少await關鍵字, 則會以同步方式執行.
            // 因此需評估使用await關鍵字, 呼叫(非封鎖的api), 或利用'await Task.Run(...)'的方式執行CPU負荷較重的背景程序.
            // 以免封鎖住主形成的執行!
            // This async method lacks 'await' operator and will runs synchronously.
            // Consider using the 'await' operator to await non-blocking API calling, 
            // or 'await Task.Run(...)' to do CPU-bound work on a background thread.
 

----------
20181109

ref:
https://stackoverflow.com/questions/8043296/whats-the-difference-between-returning-void-and-returning-a-task
In looking at various C# Async CTP samples I see some async functions that return void, and others that return the non-generic Task. I can see why returning a Task<MyType> is useful to return data to the caller when the async operation completes, but the functions that I've seen that have a return type of Task never return any data. Why not return void?

Your first question is essentially about what methods can be marked async.

A method marked as async can return void, Task or Task<T>. What are the differences between them?

標示為async非同步執行的方法, 有3種回傳類型:
1. A Task<T> returning async method can be awaited, and when the task completes it will proffer up a T.
   回傳 Task<T>: 回傳可以(再被非同步等待awaited)方法, 執行完成後, 會轉發T值後, 繼續執行主行程.
   
2. A Task returning async method can be awaited, and when the task completes, the continuation of the task is scheduled to run.
   回傳 Task: 回傳可以(再被非同步等待awaited)方法, 執行完成後, 繼續執行主行程.

3. A void returning async method cannot be awaited; it is a "fire and forget" method. It does work asynchronously, and you have no way of telling when it is done. This is more than a little bit weird; as SLaks says, normally you would only do that when making an asynchronous event handler. The event fires, the handler executes; no one is going to "await" the task returned by the event handler because event handlers do not return tasks, and even if they did, what code would use the Task for something? It's usually not user code that transfers control to the handler in the first place.
   回傳 void: 不可(再被非同步等待awaited), 方法本身已(非同步執行), 但是你無法控制該方法的結束點. 




----------
private async void BlinkAsync(Control control1, Color color1)
{
	if (mbBlinking) // 不需重複執行本函數.
		return;

	mbBlinking = true;
	Color colorOld = control1.BackColor;
	while (mbBlinking) // 可由外面改變這個Boolean決定是否結束迴圈.
	{
		await Task.Delay(500);
		control1.BackColor = control1.BackColor == colorOld ? color1 : colorOld;
	}
	control1.BackColor = colorOld;
}

----------
using System;
using System.Threading.Tasks;
using System.Timers;

class Example
{
   static void Main()
   {
	 // 當以非同步方式執行，並包含事件處理常式await, 例外狀況會傳播回呼叫執行緒, 不會被Timer元件攔截且抑制來自事件處理常式所擲回的例外狀況.
      Timer timer = new Timer(1000);
      timer.Elapsed += async ( sender, e ) => await HandleTimer();
      timer.Start();
      Console.Write("Press any key to exit... ");
      Console.ReadKey();
   }

   private static Task HandleTimer()
   {
     Console.WriteLine("\nHandler not implemented..." );
     throw new NotImplementedException();
   }
}
// The example displays output like the following:
//   Press any key to exit...
//   Handler not implemented...
//   
//   Unhandled Exception: System.NotImplementedException: The method or operation is not implemented.
//      at Example.HandleTimer()
//      at Example.<<Main>b__0>d__2.MoveNext()
//   --- End of stack trace from previous location where exception was thrown ---
//      at System.Runtime.CompilerServices.AsyncMethodBuilderCore.<>c__DisplayClass2.<ThrowAsync>b__5(Object state)
//      at System.Threading.ExecutionContext.RunInternal(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
//      at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
//      at System.Threading.QueueUserWorkItemCallback.System.Threading.IThreadPoolWorkItem.ExecuteWorkItem()
//      at System.Threading.ThreadPoolWorkQueue.Dispatch()


----------
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/index

The following characteristics summarize what makes the previous example an async method. 

•The method signature includes an async modifier. 
•The name of an async method, by convention, ends with an "Async" suffix. 
•The return type is one of the following types: 
 ◦Task<TResult> if your method has a return statement in which the operand has type TResult. 
 ◦Task if your method has no return statement or has a return statement with no operand. 
 ◦void if you're writing an async event handler. 
 ◦Any other type that has a GetAwaiter method (starting with C# 7.0).

 For more information, see the Return Types and Parameters section. 

•The method usually includes at least one await expression, which marks a point where the method can't continue until the awaited asynchronous operation is complete. In the meantime, the method is suspended, and control returns to the method's caller. The next section of this topic illustrates what happens at the suspension point. 

In async methods, you use the provided keywords and types to indicate what you want to do, and the compiler does the rest, including keeping track of what must happen when control returns to an await point in a suspended method. Some routine processes, such as loops and exception handling, can be difficult to handle in traditional asynchronous code. In an async method, you write these elements much as you would in a synchronous solution, and the problem is solved. 

What happens in an async method 圖例很清楚地畫出程式流程

----------
In the following example, the HttpClient.GetByteArrayAsync method returns a Task<byte[]>. The task is a promise to produce the actual byte array when the task is complete. The await operator suspends execution until the work of the GetByteArrayAsync method is complete. In the meantime, control is returned to the caller of GetPageSizeAsync. When the task finishes execution, the await expression evaluates to a byte array. 

using System;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      string[] args = Environment.GetCommandLineArgs();
      if (args.Length > 1)
         GetPageSizeAsync(args[1]).Wait();
      else
         Console.WriteLine("Enter at least one URL on the command line.");
   }

   private static async Task GetPageSizeAsync(string url)  
   {  
       var client = new HttpClient();  
       var uri = new Uri(Uri.EscapeUriString(url));
       byte[] urlContents = await client.GetByteArrayAsync(uri);
       Console.WriteLine($"{url}: {urlContents.Length/2:N0} characters");  
   }  
}
// The following call from the command line:
//    await1 http://docs.microsoft.com
// displays output like the following: 
//   http://docs.microsoft.com: 7,967 characters


As shown in the previous example, if await is applied to the result of a method call that returns a Task<TResult>, then the type of the await expression is TResult. If await is applied to the result of a method call that returns a Task, then the type of the await expression is void. The following example illustrates the difference. 

// await keyword used with a method that returns a Task<TResult>.  
TResult result = await AsyncMethodThatReturnsTaskTResult();  

// await keyword used with a method that returns a Task.  
await AsyncMethodThatReturnsTask();  

// await keyword used with a method that returns a ValueTask<TResult>.
TResult result = await AsyncMethodThatReturnsValueTaskTResult();

An await expression does not block the thread on which it is executing. Instead, it causes the compiler to sign up the rest of the async method as a continuation on the awaited task. Control then returns to the caller of the async method. When the task completes, it invokes its continuation, and execution of the async method resumes where it left off. 

An await expression can occur only in the body of its enclosing method, lambda expression, or anonymous method, which must be marked with an async modifier. The term await serves as a keyword only in that context. Elsewhere, it is interpreted as an identifier. Within the method, lambda expression, or anonymous method, an await expression cannot occur in the body of a synchronous function, in a query expression, in the block of a lock statement, or in an unsafe context. 


----------
The following example returns the total number of characters in the pages whose URLs are passed to it as command line arguments. The example calls the GetPageLengthsAsync method, which is marked with the async keyword. The GetPageLengthsAsync method in turn uses the await keyword to await calls to the HttpClient.GetStringAsync method. 

using System;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;

class Example
{
   static void Main()
   {
      string[] args = Environment.GetCommandLineArgs();
      if (args.Length < 2)
         throw new ArgumentNullException("No URLs specified on the command line.");
      
      long characters = GetPageLengthsAsync(args).Result;
      Console.WriteLine($"{args.Length - 1} pages, {characters:N0} characters");
   }

   private static async Task<long> GetPageLengthsAsync(string[] args)
   {
      var client = new HttpClient();
      long pageLengths = 0;

      for (int ctr = 1; ctr < args.Length; ctr++) {
         var uri = new Uri(Uri.EscapeUriString(args[ctr]));
         string pageContents = await client.GetStringAsync(uri);
         Interlocked.Add(ref pageLengths, pageContents.Length);
      }
      return pageLengths;
   }
}

Because the use of async and await in an application entry point is not supported, we cannot apply the async attribute to the Main method, nor can we await the GetPageLengthsAsync method call. We can ensure that the Main method waits for the async operation to complete by retrieving the value of the Task<TResult>.Result property. For tasks that do not return a value, you can call the Task.Wait method.