{"id":2473,"date":"2023-06-28T13:37:41","date_gmt":"2023-06-28T06:37:41","guid":{"rendered":"https:\/\/csharptutorial.net\/?page_id=2473"},"modified":"2023-06-28T13:37:57","modified_gmt":"2023-06-28T06:37:57","slug":"iasyncenumerable","status":"publish","type":"page","link":"https:\/\/www.csharptutorial.net\/csharp-linq\/iasyncenumerable\/","title":{"rendered":"IAsyncEnumerable"},"content":{"rendered":"\n

Summary<\/strong>: in this tutorial, you will learn how to handle async streams using the IAsyncEnumerable<T><\/code> interface.<\/p>\n\n\n\n

Introduction to the IAsyncEnumerable interface<\/h2>\n\n\n\n

Suppose you have an async<\/a> method GetMessage()<\/code> that returns a message after one second:<\/p>\n\n\n

async<\/span> Task<string<\/span>> GetMessage<\/span>(int<\/span> n<\/span>)<\/span>\n{\n    await<\/span> Task.Delay(1000<\/span>);\n    return<\/span> $\"Message #{n}<\/span>\"<\/span>;\n}<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
To define a method that returns a sequence of messages based on the GetMessage()<\/code> method, you use the IAsyncEnumerable<T><\/code> interface:<\/p>\n\n\n
async<\/span> IAsyncEnumerable<string<\/span>> GetMessages<\/span>(int<\/span> max<\/span>)<\/span>\n{\n    for<\/span> (var<\/span> i = 1<\/span>; i <= max; i++)\n    {\n        var<\/span> message = await<\/span> GetMessage(i);\n        yield<\/span> return<\/span> message;\n    }\n}<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
The GetMessages()<\/code> method calls the GetMessage()<\/code> method to generate a sequence of messages. It returns an IAsyncEnumerable<\/code><T> interface that iterates the sequences asynchronously.<\/p>\n\n\n\n
The IAsyncEnumerable<T><\/code> has the GetAsyncEnumerator()<\/code> method that returns an enumerator which iterates asynchronously through the collection:<\/p>\n\n\n
IAsyncEnumerator GetAsyncEnumerator<\/span>(\n    CancellationToken cancellationToken = default<\/span>\n<\/span>)<\/span>;<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
The GetAsyncEnumerator()<\/code> method has a parameter CancellationToken<\/code> that allows you to cancel the asynchronous iteration. It returns an IAsyncEnumerator<T><\/code> interface that has the Current<\/code> and MoveNextAsync()<\/code> methods:<\/p>\n\n\n\n
Member<\/th>IEnumerable<T><\/th>IAsyncEnumerator<T><\/th><\/tr><\/thead>
Method<\/td>GetEnumerator<\/code><\/td>GetAsyncEnumerator<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Member<\/th>IEnumerator<T><\/th>IAsyncEnumerator<T><\/th><\/tr><\/thead>
Property<\/td>Current<\/code><\/td>Current<\/code><\/td><\/tr>
Method <\/td>MoveNext()<\/code><\/td>MoveNextAsync()<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
To consume an IAsyncEnumerator<\/code>, you use the await foreach<\/code> statement instead of the foreach<\/code> statement:<\/p>\n\n\n
await<\/span> foreach<\/span> (var<\/span> message in<\/span> GetMessages<\/span>(5<\/span><\/span>))<\/span>\n{\n    WriteLine(message);\n}<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Message #1<\/span>\nMessage #2<\/span>\nMessage #3<\/span>\nMessage #4<\/span>\nMessage #5<\/span><\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
The program displays five messages after every second.<\/p>\n\n\n\n
Put it all together.<\/p>\n\n\n
using<\/span> static<\/span> System.Console;\n\n\nawait<\/span> foreach<\/span> (var<\/span> message in<\/span> GetMessages<\/span>(5<\/span><\/span>))<\/span>\n{\n    WriteLine(message);\n}\n\n\nasync<\/span> IAsyncEnumerable<string<\/span>> GetMessages<\/span>(int<\/span> max<\/span>)<\/span>\n{\n    for<\/span> (var<\/span> i = 1<\/span>; i <= max; i++)\n    {\n        var<\/span> message = await<\/span> GetMessage(i);\n        yield<\/span> return<\/span> message;\n    }\n}\n\nasync<\/span> Task<string<\/span>> GetMessage<\/span>(int<\/span> n<\/span>)<\/span>\n{\n    await<\/span> Task.Delay(1000<\/span>);\n    return<\/span> $\"Message #{n}<\/span>\"<\/span>;\n}<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
Using the IAsyncEnumerable interface with CancellationToken<\/h2>\n\n\n\n
The following example shows how to use the CancellationToken<\/code> to request the cancellation of an operation:<\/p>\n\n\n
using<\/span> System.Runtime.CompilerServices;\nusing<\/span> static<\/span> System.Console;\n\nvar<\/span> cts = new<\/span> CancellationTokenSource();\ncts.CancelAfter(TimeSpan.FromSeconds(3<\/span>));\n\ntry<\/span>\n{\n    await<\/span> foreach<\/span> (var<\/span> message in<\/span> GetMessages<\/span>(5<\/span>, cts.Token<\/span>))<\/span>\n    {\n        WriteLine(message);\n    }\n}\ncatch<\/span>(TaskCanceledException ex)\n{\n    WriteLine(ex.Message);\n}\n\nasync<\/span> IAsyncEnumerable<string<\/span>> GetMessages<\/span>(int<\/span> max, [EnumeratorCancellation] CancellationToken token = default<\/span><\/span>)<\/span>\n{\n    for<\/span> (var<\/span> i = 1<\/span>; i <= max; i++)\n    {\n        var<\/span> message = await<\/span> GetMessage(i, token);\n        yield<\/span> return<\/span> message;\n    }\n}\n\nasync<\/span> Task<string<\/span>> GetMessage<\/span>(int<\/span> n, CancellationToken token=default<\/span><\/span>)<\/span>\n{\n    await<\/span> Task.Delay(1000<\/span>, token);\n    return<\/span> $\"Message #{n}<\/span>\"<\/span>;\n}<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Message #1<\/span>\nMessage #2<\/span>\nA task was canceled.<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
How it works.<\/p>\n\n\n\n
First, create a CancellationTokenSource<\/code> object and schedule a cancel operation after 3 seconds:<\/p>\n\n\n
var<\/span> cts = new<\/span> CancellationTokenSource();\ncts.CancelAfter(TimeSpan.FromSeconds(3<\/span>));<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
Second, add the CancellationToken<\/code> to both GetMessage()<\/code> and GetMessages()<\/code> methods. In the GetMessage()<\/code> method, pass the token to the Task.Delay<\/code>() method.<\/p>\n\n\n\n
Practical use of the IAsyncEnumerable interface<\/h2>\n\n\n\n
The following program illustrates how to retrieve the content of a list of URLs<\/code> and writes the length of each downloaded text to the console using the IAsyncEnumerable<\/code> and HttpClient<\/code>:<\/p>\n\n\n
using<\/span> static<\/span> System.Console;\n\nvar<\/span> urls = new<\/span> List<string<\/span>>()\n{\n    \"https:\/\/datatracker.ietf.org\/doc\/html\/rfc791\"<\/span>,\n    \"https:\/\/datatracker.ietf.org\/doc\/html\/rfc1180\"<\/span>,\n    \"https:\/\/datatracker.ietf.org\/doc\/html\/rfc2616\"<\/span>\n};\n\n\nawait<\/span> foreach<\/span> (var<\/span> result in<\/span> GetTexts<\/span>(urls<\/span>))<\/span>\n{\n    WriteLine(result?.Length);\n}\n\nstatic<\/span> async<\/span> IAsyncEnumerable<string<\/span>?> GetTexts(List<string<\/span>> urls)\n{\n\n    foreach<\/span> (var<\/span> url in<\/span> urls)\n    {\n        var<\/span> text = await<\/span> Download(url);\n        yield<\/span> return<\/span> text;\n    }\n}\n\nstatic<\/span> async<\/span> Task<string<\/span>?> Download(string<\/span> url)\n{\n    try<\/span>\n    {\n        using<\/span> var<\/span> client = new<\/span> HttpClient();\n        \n        var<\/span> response = await<\/span> client.GetAsync(url);\n        response.EnsureSuccessStatusCode();\n        var<\/span> text = await<\/span> response.Content.ReadAsStringAsync();\n        return<\/span> text;\n    }\n    catch<\/span> (HttpRequestException ex)\n    {\n        WriteLine(ex.Message);\n        return<\/span> null<\/span>;\n    }\n}<\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
126891<\/span>\n102930<\/span>\n580146<\/span><\/code><\/span>Code language:<\/span> C#<\/span> (<\/span>cs<\/span>)<\/span><\/small><\/pre>\n\n\n
Summary<\/h2>\n\n\n\n
    \n
  • Use IAsyncEnumerable<T><\/code> and await foreach<\/code> statement to iterate over a sequence of items asynchronously.<\/li>\n<\/ul>\n
    \n\t
    \n\t\t
    Was this tutorial helpful ?<\/div>\n\t\t
    \n\t\t\t\n\t\t\t\t\n\t\t\t\t\t<\/path>\n\t\t\t\t<\/svg>\n\t\t\t\t Yes <\/span>\n\t\t\t<\/button>\n\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t<\/path>\n\t\t\t\t<\/svg>\n\t\t\t\t No <\/span>\n\t\t\t<\/button>\n\t\t<\/div>\n\t<\/header>\n\n\t
    \n\t\t
    \n\t\t\t
    <\/div>\n\t\t\t\n\t\t\t