Minimal APIs | IResult or TypedResult specifically for IAsyncEnumerable

[toupswork]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

It cannot be that I am the only one to ever think of this, so there must a good reason why there is no member of the Results or TypedResults class specifically designed for IAsyncEnumerable<T>.

The reason that I think it should be there is because if I return IAsyncEnumerable<T> directly from my endpoint, then that makes it difficult to also be able to return Results.Problem() (for FluentValidation) or Result.Status() if an error occurs before the stream. That's of course because the return type cannot be inferred, because one is IResult and the other is IAsyncEnumerable<T>.

I did build my own IResult to get around this, and in the process of doing so, my throughput jumped dramatically. I do not know for certain why, but I speculate that it may have something to do with the fact that I am using a JsonSerializerContext and source generated (de)serialization code, but unbeknownst to me, even though the type I was returning was decorated with the JsonSerializable attribute, what actually needed to be decorated was my type being wrapped with IAsyncEnumerable.

Describe the solution you'd like

All I am asking is that there be method, call it what you will, or at least give an overload, on TypedResults and/or Results specifically for IAsyncEnumerable

---

Here's the code I wrote. If anything, I hope this helps someone else out who is running into the same problem.
The ServiceResultAccessor is just a type I created that is similar in concept to IHttpContextAccessor in that it uses AsyncLocal<T> for storing, not HttpContext, but a result status enum. So if there is any error on the backend pulling the data that I am sending out, the status will be written to it, then when I await the first entry in the IAsyncEnumerable, I am able to see if a backend error occurs and update the response status code to reflect that. This provides me a workaround for not being able to use the Result<T> pattern when using a stream.

// ReSharper disable StaticMemberInGenericType

using System.Reflection;
using System.Runtime.CompilerServices;
using API.Logging;
using Microsoft.AspNetCore.Http.Metadata;
using Services.ApiClients.Infrastructure;
using static API.Serialization.ApiJsonContext;
using static Microsoft.AspNetCore.Http.StatusCodes;
namespace API.ApiResults;

public sealed class AsyncEnumerableResult<T>(IAsyncEnumerable<T> stream, ServiceResultStatusAccessor accessor, CancellationToken cancellationToken): IEndpointMetadataProvider, IResult
{
  private static readonly JsonSerializerOptions JsonOptions = Default.Options;
  private const string JsonContentType = "application/json; charset=utf-8";

  public async Task ExecuteAsync(HttpContext httpCtx)
  {
    var (response, logger) = (httpCtx.Response, httpCtx.RequestServices.GetService<ILogger<AsyncEnumerableResult<T>>>());
    try
    {
      await using var enumerator = stream.GetAsyncEnumerator(cancellationToken);

      switch (await enumerator.MoveNextAsync(cancellationToken))
      {
        // some problem occurred in the processing, write the status code and bail
        case true or false when accessor.IsResultFailed(out var status):
          if(!response.HasStarted) response.StatusCode = status.ToHttpStatusCodeInt();
          logger?.AsyncEnumerableErrorStatusCode(response.StatusCode);
          break;

        case false:
          if (!response.HasStarted) response.StatusCode = Status200OK;
          await response.WriteAsJsonAsync(GetEmpty(), JsonOptions, cancellationToken);
          break;

        case true:
          if (!response.HasStarted) response.StatusCode = Status200OK;
          await response.WriteAsJsonAsync(GetRemainingItems(enumerator, cancellationToken), JsonOptions, cancellationToken);
          break;
      }
    }
    catch (Exception ex)
    {
      logger?.AsyncEnumerableResultException(typeof(T).Name, ex);
    }
  }

  private static IAsyncEnumerable<T> GetEmpty() => AsyncEnumerable.Empty<T>();
  private static async IAsyncEnumerable<T> GetRemainingItems(IAsyncEnumerator<T> enumerator, [EnumeratorCancellation] CancellationToken ct)
  {
    yield return enumerator.Current;
    while (await enumerator.MoveNextAsync(ct)) yield return enumerator.Current;
  }

  static void IEndpointMetadataProvider.PopulateMetadata(MethodInfo method, EndpointBuilder builder)
  {
    builder.Metadata.Add(new ProducesResponseTypeMetadata(Status200OK, typeof(IAsyncEnumerable<T>), [JsonContentType]));
    builder.Metadata.Add(new ProducesResponseTypeMetadata(Status400BadRequest));
    builder.Metadata.Add(new ProducesResponseTypeMetadata(Status401Unauthorized));
    builder.Metadata.Add(new ProducesResponseTypeMetadata(Status404NotFound));
    builder.Metadata.Add(new ProducesResponseTypeMetadata(Status500InternalServerError));
    builder.Build();
  }
}

Additional context

No response

[josephmoresena]

I was just about to ask about this topic, since it had been a long time since I worked with ASP.NET. However, I recently had the chance to review, at least superficially, minimal API, IResult, and IEndpointMetadataProvider, and I was pleasantly surprised—especially with Native AOT. That said, I couldn't find a way to handle this type of return, and my question was whether it’s discouraged or not.

Here is my implementation:

using System.Diagnostics.CodeAnalysis;
using System.Reflection;
using System.Runtime.CompilerServices;
using System.Text.Json;

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Http.Json;
using Microsoft.AspNetCore.Http.Metadata;
using Microsoft.Extensions.Options;
using Microsoft.Net.Http.Headers;

public abstract class JsonAsyncEnumerableResult
{
	/// <inheritdoc cref="IEndpointMetadataProvider.PopulateMetadata(MethodInfo, EndpointBuilder)"/>
	[MethodImpl(MethodImplOptions.AggressiveInlining)]
	protected static void PopulateMetadata<TProvider>(MethodInfo method, EndpointBuilder builder)
		where TProvider : IEndpointMetadataProvider
		=> TProvider.PopulateMetadata(method, builder);

	[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Uses ASP .NET serialization context.")]
	[UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Uses ASP .NET serialization context.")]
	protected sealed class ResponseWriter : IAsyncDisposable
	{
		private readonly HttpResponse _response;
		private readonly JsonSerializerOptions _serializerOptions;
		private readonly Utf8JsonWriter _writer;

		[MethodImpl(MethodImplOptions.AggressiveInlining)]
		public ResponseWriter(HttpContext httpContext) : this(httpContext.Response, httpContext.RequestServices) { }
		[MethodImpl(MethodImplOptions.AggressiveInlining)]
		private ResponseWriter(HttpResponse response, IServiceProvider serviceProvider) : this(
			response, serviceProvider.GetService<IOptions<JsonOptions>>()?.Value) { }
		private ResponseWriter(HttpResponse response, JsonOptions? jsonOptions)
		{
			this._response = response;
			this._serializerOptions =
				ResponseWriter.GetSerializerOptions(jsonOptions, out JsonWriterOptions writerOptions);
			this._writer = new(response.BodyWriter, writerOptions);
		}

		public async ValueTask WriteEmptyArray(Boolean isHttps)
		{
			this.WriteArrayBegin(isHttps);
			await this.WriteArrayEnd();
		}
		public void WriteArrayBegin(Boolean isHttps)
		{
			this._response.Headers.Append(HeaderNames.ContentType, "application/json; charset=utf-8");
			if (!isHttps)
				this._response.Headers.Append(HeaderNames.Connection, "keep-alive");
			this._writer.WriteStartArray();
		}
		public async ValueTask WriteElement<T>(T value, Boolean hasNext)
		{
			await Task.Yield();
			if (hasNext)
			{
				await this._writer.FlushAsync();
				await this._response.Body.FlushAsync();
			}
			JsonSerializer.Serialize(this._writer, value, this._serializerOptions);
		}
		public async ValueTask WriteArrayEnd()
		{
			this._writer.WriteEndArray();
			await this._writer.FlushAsync();
			await this._response.Body.FlushAsync();
		}

		public async ValueTask DisposeAsync()
		{
			await this._writer.DisposeAsync();
			await this._response.CompleteAsync();
		}

		private static JsonSerializerOptions GetSerializerOptions(JsonOptions? jsonOptions,
			out JsonWriterOptions writerOptions)
		{
			if (jsonOptions is null)
			{
				writerOptions = new();
				return new();
			}
			writerOptions = new()
			{
				IndentCharacter = jsonOptions.SerializerOptions.IndentCharacter,
				Indented = jsonOptions.SerializerOptions.WriteIndented,
				IndentSize = jsonOptions.SerializerOptions.IndentSize,
				MaxDepth = jsonOptions.SerializerOptions.MaxDepth,
				Encoder = jsonOptions.SerializerOptions.Encoder,
				NewLine = jsonOptions.SerializerOptions.NewLine,
				SkipValidation = true,
			};
			return jsonOptions.SerializerOptions;
		}
	}
}

public sealed class JsonAsyncEnumerableResult<T>(IAsyncEnumerable<T> asyncEnumerable) : JsonAsyncEnumerableResult,
	IResult, IEndpointMetadataProvider, IValueHttpResult<IAsyncEnumerable<T>>, IValueHttpResult
{
	IAsyncEnumerable<T> IValueHttpResult<IAsyncEnumerable<T>>.Value => asyncEnumerable;
	Object IValueHttpResult.Value => asyncEnumerable;

	/// <inheritdoc />
	public async Task ExecuteAsync(HttpContext httpContext)
	{
		await using IAsyncEnumerator<T> enumerator = asyncEnumerable.GetAsyncEnumerator();
		await using ResponseWriter writer = new(httpContext);
		if (!await enumerator.MoveNextAsync())
		{
			await writer.WriteEmptyArray(httpContext.Request.IsHttps);
			return;
		}

		T current = enumerator.Current;
		writer.WriteArrayBegin(httpContext.Request.IsHttps);
		while (await enumerator.MoveNextAsync())
		{
			await writer.WriteElement(current, true);
			current = enumerator.Current;
		}
		await writer.WriteElement(current, false);
		await writer.WriteArrayEnd();
	}

	static void IEndpointMetadataProvider.PopulateMetadata(MethodInfo method, EndpointBuilder builder)
		=> JsonAsyncEnumerableResult.PopulateMetadata<Ok<T[]>>(method, builder);
}

I wonder why there isn’t something built-in, considering that a few years ago IAsyncEnumerable was introduced as a significant technological advancement in the context of ASP.NET.

Note: I decided to start the enumeration before beginning the response because it's possible that the asynchronous enumeration method might write headers or cookies, and those can only be written before the response body is sent. That’s why I even write the content type headers after the enumeration has started.