[API Proposal]: Add new overloads to ReadFromJsonAsync method in HttpContentJsonExtensions

[N0D4N]

Background and motivation

Currently ReadFromJsonAsync method parameters follow pattern (with parameter names skipped): this HttpContent, Type/*if it isn't generic overload*/, JsonSerializerOptions? = null /*or JsonSerializerContext or JsonTypeInfo<T>*/, CancellationToken = default

runtime/src/libraries/System.Net.Http.Json/ref/System.Net.Http.Json.cs

Lines 85 to 89 in a5f3676

	public static System.Threading.Tasks.Task<object?> ReadFromJsonAsync(this System.Net.Http.HttpContent content, System.Type type, System.Text.Json.JsonSerializerOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
	public static System.Threading.Tasks.Task<object?> ReadFromJsonAsync(this System.Net.Http.HttpContent content, System.Type type, System.Text.Json.Serialization.JsonSerializerContext context, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
	[System.Diagnostics.CodeAnalysis.RequiresUnreferencedCodeAttribute("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo or JsonSerializerContext, or make sure all of the required types are preserved.")]
	public static System.Threading.Tasks.Task<T?> ReadFromJsonAsync<T>(this System.Net.Http.HttpContent content, System.Text.Json.JsonSerializerOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
	public static System.Threading.Tasks.Task<T?> ReadFromJsonAsync<T>(this System.Net.Http.HttpContent content, System.Text.Json.Serialization.Metadata.JsonTypeInfo<T> jsonTypeInfo, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }

Which makes impossible calling ReadFromJsonAsync method without specifying JsonSerializerOptions/JsonSerializerContext/JsonTypeInfo<T> parameters, but with passing CancellationToken parameter. Prior to S.T.J source-gen it was possible via calling for example content.ReadFromJsonAsync<MyClass>(null, cancellationToken). However with introducing json source-gen now this is impossible since compiler can't deduce type behind null passed as param, since JsonSerializerOptions overload was the only one, and now it isn't. So now user needs to specify parameter of null like this content.ReadFromJsonAsync<MyClass>((JsonSerializerOptions?)null, cancellationToken) which is additional typing, and doesn't look pleasant.

API Proposal

namespace System.Net.Http.Json;

public static partial class HttpContentJsonExtensions
{
        public static Task<object?> ReadFromJsonAsync(this HttpContent content, Type type, CancellationToken cancellationToken = default) { throw null; }
        public static Task<T?> ReadFromJsonAsync<T>(this HttpContent content, CancellationToken cancellationToken = default) { throw null; }
}

It should also be noted that HttpClientJsonExtensions methods overloads already follow the same pattern as proposed of skipping nullable JsonSerializerOptions parameter:

runtime/src/libraries/System.Net.Http.Json/ref/System.Net.Http.Json.cs

Line 25 in a5f3676

public static System.Threading.Tasks.Task<TValue?> DeleteFromJsonAsync<TValue>(this System.Net.Http.HttpClient client, [System.Diagnostics.CodeAnalysis.StringSyntaxAttribute("Uri")] string? requestUri, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }

API Usage

public async Task<MyClass> MyMethodAsync(HttpRequestMessage message, CancellationToken cancellationToken)
{
	// do some work
	return await message.Content.ReadAsJsonAsync(cancellationToken);
	// compared to
	// return await message.Content.ReadFromJsonAsync<MyClass>((JsonSerializerOptions?)null, cancellationToken)
}

Alternative Designs

Can't think of any.

Risks

Can't think of any, since it follows the same pattern present as in other class.

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Currently ReadFromJsonAsync method parameters follow pattern (with parameter names skipped): this HttpContent, Type/*if it isn't generic overload*/, JsonSerializerOptions? = null /*or JsonSerializerContext or JsonTypeInfo<T>*/, CancellationToken = default

runtime/src/libraries/System.Net.Http.Json/ref/System.Net.Http.Json.cs

Lines 85 to 89 in a5f3676

	public static System.Threading.Tasks.Task<object?> ReadFromJsonAsync(this System.Net.Http.HttpContent content, System.Type type, System.Text.Json.JsonSerializerOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
	public static System.Threading.Tasks.Task<object?> ReadFromJsonAsync(this System.Net.Http.HttpContent content, System.Type type, System.Text.Json.Serialization.JsonSerializerContext context, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
	[System.Diagnostics.CodeAnalysis.RequiresUnreferencedCodeAttribute("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo or JsonSerializerContext, or make sure all of the required types are preserved.")]
	public static System.Threading.Tasks.Task<T?> ReadFromJsonAsync<T>(this System.Net.Http.HttpContent content, System.Text.Json.JsonSerializerOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
	public static System.Threading.Tasks.Task<T?> ReadFromJsonAsync<T>(this System.Net.Http.HttpContent content, System.Text.Json.Serialization.Metadata.JsonTypeInfo<T> jsonTypeInfo, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }

Which makes impossible calling ReadFromJsonAsync method without specifying JsonSerializerOptions/JsonSerializerContext/JsonTypeInfo<T> parameters, but with passing CancellationToken parameter. Prior to S.T.J source-gen it was possible via calling for example content.ReadFromJsonAsync<MyClass>(null, cancellationToken). However with introducing json source-gen now this is impossible since compiler can't deduce type behind null passed as param, since JsonSerializerOptions overload was the only one, and now it isn't. So now user needs to specify parameter of null like this content.ReadFromJsonAsync<MyClass>((JsonSerializerOptions?)null, cancellationToken) which is additional typing, and doesn't look pleasant.

API Proposal

namespace System.Net.Http.Json;

public static partial class HttpContentJsonExtensions
{
        public static Task<object?> ReadFromJsonAsync(this HttpContent content, Type type, CancellationToken cancellationToken = default) { throw null; }
        public static Task<T?> ReadFromJsonAsync<T>(this HttpContent content, CancellationToken cancellationToken = default) { throw null; }
}

It should also be noted that HttpClientJsonExtensions methods overloads already follow the same pattern as proposed of skipping nullable JsonSerializerOptions parameter:

runtime/src/libraries/System.Net.Http.Json/ref/System.Net.Http.Json.cs

Line 15 in a5f3676

public static System.Threading.Tasks.Task<object?> DeleteFromJsonAsync(this System.Net.Http.HttpClient client, [System.Diagnostics.CodeAnalysis.StringSyntaxAttribute("Uri")] string? requestUri, System.Type type, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }

API Usage

public async Task<MyClass> MyMethodAsync(HttpRequestMessage message, CancellationToken cancellationToken)
{
	// do some work
	return await message.Content.ReadAsJsonAsync(cancellationToken);
	// compared to
	// return await message.Content.ReadFromJsonAsync<MyClass>((JsonSerializerOptions?)null, cancellationToken)
}

Alternative Designs

Can't think of any.

Risks

Can't think of any, since it follows the same pattern present as in other class.

Author:	N0D4N
Assignees:	-
Labels:	api-suggestion, area-System.Text.Json, untriaged
Milestone:	-

[eiriktsarpalis]

Sounds reasonable from a consistency standpoint, since HttpClientJsonExtensions is already doing this.

[terrajobst]

Video

The intended usage

return await message.Content.ReadAsJsonAsync(cancellationToken);

almost works today, by using named arguments:

return await message.Content.ReadAsJsonAsync(cancellationToken: cancellationToken);

Which would bind to this method:

namespace System.Net.Http.Json;

public static class HttpContentJsonExtensions
{
    [RequiresDynamicCode("...")]
    [RequiresUnreferencedCode("...")]
    public static Task<T> ReadFromJsonAsync<T>(this HttpContent content,
                                               JsonSerializerOptions? options = null,
                                               CancellationToken cancellationToken = default);
}

We're not opposed to adding this overload but then we should probably add corresponding ones for the methods on HttpClientJsonExtensions.

[N0D4N]

return await message.Content.ReadAsJsonAsync(cancellationToken: cancellationToken);

Is good workaround, i didn't think of at the time of writing a proposal.

However, HttpClientJsonExtensions is already following the approach i proposed for HttpContentJsonExtensions:

runtime/src/libraries/System.Net.Http.Json/ref/System.Net.Http.Json.cs

Line 25 in a5f3676

public static System.Threading.Tasks.Task<TValue?> DeleteFromJsonAsync<TValue>(this System.Net.Http.HttpClient client, [System.Diagnostics.CodeAnalysis.StringSyntaxAttribute("Uri")] string? requestUri, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }

runtime/src/libraries/System.Net.Http.Json/ref/System.Net.Http.Json.cs

Line 35 in a5f3676

public static System.Threading.Tasks.Task<object?> GetFromJsonAsync(this System.Net.Http.HttpClient client, [System.Diagnostics.CodeAnalysis.StringSyntaxAttribute("Uri")] string? requestUri, System.Type type, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }

runtime/src/libraries/System.Net.Http.Json/ref/System.Net.Http.Json.cs

Line 65 in a5f3676

public static System.Threading.Tasks.Task<System.Net.Http.HttpResponseMessage> PutAsJsonAsync<TValue>(this System.Net.Http.HttpClient client, [System.Diagnostics.CodeAnalysis.StringSyntaxAttribute("Uri")] string? requestUri, TValue value, System.Threading.CancellationToken cancellationToken) { throw null; }

to name a few, there is more at the source file.
That's why i think its good to have HttpContentJsonExtensions follow this approach from consistency point of view.

So i am not sure what should be done here, i assume proposal should be marked as api-ready-for-review, and go through review process once again, this time considering HttpClientJsonExtensions already follow proposed approach?

[N0D4N]

@eiriktsarpalis sorry for ping, but i figured you would be the best person to ask, since you are an area owner and you commented here already.
A month have passed but no action were taken, can you, please, point what should be done here? In my opinion it should be remarked as ready-for-review since people on review missed notes about proposed api bringing api parity, and they are generally fine (as far as i understand) with proposed API.
Or should it be postponed to a later date, since 8.0 release is more than a year away?

[eiriktsarpalis]

I missed that API review meeting, but it looks like the fact that the same overloads already exist in HttpClientJsonExtensions is something that wasn't pointed out during review. I think we should take another look cc @terrajobst