Add CancellationToken overloads for reading multipart form sections

[martincostello]

Background and Motivation

While checking for other usages of ReadAsStringAsync() when working on #41531, I found one other occurrence here:

aspnetcore/src/Http/WebUtilities/src/FormMultipartSection.cs

Lines 56 to 59 in c85baf8

	public Task<string> GetValueAsync()
	{
	return Section.ReadAsStringAsync();
	}

As well as adding an overload for a CancellationToken parameter there, another would be needed here:

aspnetcore/src/Http/WebUtilities/src/MultipartSectionStreamExtensions.cs

Lines 14 to 19 in c85baf8

	/// <summary>
	/// Reads the body of the section as a string
	/// </summary>
	/// <param name="section">The section to read from</param>
	/// <returns>The body steam as string</returns>
	public static async Task<string> ReadAsStringAsync(this MultipartSection section)

The new overload could then be used here:

aspnetcore/src/Http/Http/src/Features/FormFeature.cs

Line 248 in c85baf8

var value = await formDataSection.GetValueAsync();

Proposed API

namespace Microsoft.AspNetCore.WebUtilities;

public class FormMultipartSection
{
+   public Task<string> GetValueAsync(CancellationToken cancellationToken);
}

public static class MultipartSectionStreamExtensions
{
+   public static async Task<string> ReadAsStringAsync(this MultipartSection section, CancellationToken cancellationToken);
}

Usage Examples

var formDataSection = new FormMultipartSection(section, contentDisposition);
var key = formDataSection.Name;
var value = await formDataSection.GetValueAsync(cancellationToken);

Alternative Designs

Add an optional parameter instead as a binary-breaking change for .NET 7.

namespace Microsoft.AspNetCore.WebUtilities;

public class FormMultipartSection
{
-   public Task<string> GetValueAsync();
+   public Task<string> GetValueAsync(CancellationToken cancellationToken = default);
}

public static class MultipartSectionStreamExtensions
{
-   public static async Task<string> ReadAsStringAsync(this MultipartSection section);
+   public static async Task<string> ReadAsStringAsync(this MultipartSection section, CancellationToken cancellationToken = default);
}

Risks

None known.

[Tratcher]

Ah, this is useful now because StreamReader.ReadToEndAsync now accepts a CT.
https://docs.microsoft.com/en-us/dotnet/api/system.io.streamreader.readtoendasync?view=net-7.0#system-io-streamreader-readtoendasync(system-threading-cancellationtoken)

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

Thanks for contacting us.

We're moving this issue to the .NET 7 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[davidfowl]

Opportunity for optimization! ValueTask<string> instead of Task<string>

[halter73]

API Review Notes:

• ValueTask? Yes, for when the data is already buffered. Stream already varies between Task and ValueTask.
• FileMultipartSection doesn't have a GetValueAsync

Approved:

namespace Microsoft.AspNetCore.WebUtilities;

public class FormMultipartSection
{
+   public ValueTask<string> GetValueAsync(CancellationToken cancellationToken);
}

public static class MultipartSectionStreamExtensions
{
+   public static async ValueTask<string> ReadAsStringAsync(this MultipartSection section, CancellationToken cancellationToken);
}