Clarification on how IAsyncEnumerable works with ASP.NET Web API

Question

I encountered an interesting behavior while exploring IAsyncEnumerable in an ASP.NET Web API project. Consider the following code samples:

    // Code Sample 1
    [HttpGet]
    public async IAsyncEnumerable<int> GetAsync()
    {
        for (int i = 0; i < 10; i++)
        {
            await Task.Delay(1000);
            yield return i;
        }
    }


    // Code Sample 2
    [HttpGet]
    public async IAsyncEnumerable<string> GetAsync()
    {
        for (int i = 0; i < 10; i++)
        {
            await Task.Delay(1000);
            yield return i.ToString();
        }
    }

Sample 1 (int array) returns {} as JSON result.

Sample 2 returns expected result ["0","1","2","3","4","5","6","7","8","9"]. However, entire JSON array is returned at once after 10 seconds of wait. Shouldn't it be returned as data becomes available as expected from IAsyncEnumerable interface? Or is there any specific way this web api should be consumed?

Answer 1

In .NET 6, about 2 years after the question was asked, it works as you expected.

[HttpGet]
public async IAsyncEnumerable<int> Get()
{
    for(int i = 0; i < 10; i++)
    {
        await Task.Delay(TimeSpan.FromSeconds(1));
        yield return i;
    }
}

will result in the browser receiving partial results over time.

After ~3 seconds:

After ~5 seconds:

After ~10 seconds:

---

Pre .NET6

Up to .NET 6, at the time your question was asked, the web api call will not return partial json every second. It's the json serialiser who has to wait 10x1second (or the code that calls the json serialiser, which is part of ASP .NET). Once the framework code and the serialiser get all data, it will be serialised and served to the client as a single response.

In Controller action return types in ASP.NET Core web API we can read:

In ASP.NET Core 3.0 and later, returning IAsyncEnumerable from an action:

• No longer results in synchronous iteration.
• Becomes as efficient as returning IEnumerable.

ASP.NET Core 3.0 and later buffers the result of the following action before providing it to the serializer: (...)

Answer 2

In ASP.NET Core 5 indeed instances of the type IAsyncEnumerable have been processed by buffering the sequence in memory and formatting the buffered collection all at once. This explains, why you did not receive partial results.

However, with ASP.NET Core 6.0 this will be possible!

In ASP.NET Core 6, when formatting using System.Text.Json, MVC no longer buffers IAsyncEnumerable instances. Instead, MVC relies on the support that System.Text.Json added for these types (reference)

The release for ASP.NET Core 6 is planned for November 2021 (reference). It is already possible to test the new behavior using preview releases. I successfully tested the following code using the preview release 6.0.100-preview.6.21355.2. The code produces an infinite stream of integers and returns it via a controller using IAsyncEnumerable. The while (true) loop "proves" that data is returned before everything is processed because obviously the loop will never terminate*.

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;

namespace dot_net_api_streaming.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class LoopController : ControllerBase
    {

        [HttpGet]
        public IAsyncEnumerable<int> Get()
        {
            return GetInfiniteInts();
        }

        private async IAsyncEnumerable<int> GetInfiniteInts()
        {
            int index = 0;
            while (true)
                yield return index++;
        }
    }
}
 

*Please keep that in mind when experimenting with my code so your machine will not crash :)