Replace Microsoft.AspNet.WebApi.Client with built-in abstractions

[jmbryan4]

Problem

The Pathoschild.Http.FluentClient package depends on Microsoft.AspNet.WebApi.Client, which originates from the aspnet/AspNetWebStack repository. That is the legacy ASP.NET stack for MVC 5.x, Web API 2.x, and Web Pages 3.x.

This dependency is problematic for several reasons:

1. End of support: ASP.NET Web API 2 reached end of support on July 1, 2019.
2. No active development: No stable source release since October 2020 (5+ years).
3. System.Net.Http.Formatting and the MediaTypeFormatter abstraction were deliberately not brought forward to ASP.NET Core
4. Newtonsoft.Json: The package pulls in a transitive dependency on Newtonsoft.Json. .NET moved to System.Text.Json as the platform default since .NET Core 3.0.
5. System.Net.Http.Json (actively maintained in dotnet/runtime) is the official successor for HTTP content serialization.

Prior discussion

This has come up several times:

• Remove System.Net.Http.Formatting dependency  #52 (2017) asked for removal, closed as wontfix
• Review supported frameworks #91 (2020) asked to modernize targets, declined
• Vulnerabilities Detected #120 (2022) related discussion
• System.Text.Json - json formatter #128 (2024) asked about System.Text.Json support

From #128: MediaTypeFormatter concept is a legacy part that the .NET team chose not to bring forward.

1. System.Net.Http.Json design doc explains why they created a new assembly instead of extending System.Net.Http.Formatting: "The existing assembly (which ships in Microsoft.AspNet.WebApi.Client package) provides the integration between HttpClient and JSON.NET. Mixing this with the new System.Text.Json would create a mess."

2. .NET runtime code in dotnet/runtime's HttpMessageHandlerBuilder.cs explicitly avoids the old package: "This is similar to [System.Net.Http.Formatting/HttpClientFactory.cs] but we don't want to take that package as a dependency."

3. David Fowler explained in dotnet/aspnetcore#3313 why the shared HTTP model that MediaTypeFormatter depended on was abandoned.

The modern approach is System.Net.Http.Json with simple extension methods (GetFromJsonAsync<T>(), etc.) no formatters, no content negotiation. A rewrite toward that model would be cleaner but would break the entire
public API surface (Formatters on IClient/IRequest/IResponse, IBodyBuilder.Model(), MediaTypeFormatterBase subclasses, etc.). That felt too disruptive for this change.

Proposed solution

Replace Microsoft.AspNet.WebApi.Client with lightweight, built-in abstractions:

1. Define a new IMediaTypeFormatter interface (replacing System.Net.Http.Formatting.MediaTypeFormatter)
2. Provide JsonMediaTypeFormatter (using Newtonsoft.Json, preserving existing behavior) and XmlMediaTypeFormatter (using DataContractSerializer)
3. Create a MediaTypeFormatterCollection (same class name to minimize consumer breakage)
4. Update target frameworks to netstandard2.0;net8.0

This removes the legacy dependency while keeping Newtonsoft.Json for backward compatibility (consumers can still configure JSON serialization the same way). A future version could add System.Text.Json support as an alternative formatter.

What could be added later (non-breaking):

• A SystemTextJsonMediaTypeFormatter so consumers can choose between Newtonsoft.Json and System.Text.Json
• Make System.Text.Json the default, with Newtonsoft.Json as opt-in

PR #134

[Pathoschild]

(The prior discussions you mention seem mostly unrelated:

• #52 was a unit test project with an old target framework, so it used older dependencies.
• #91 proposed dropping support for older target frameworks entirely (not just changing the dependencies or API design).
• #120 is unrelated (it was just an outdated package version).
• #128 was about adding custom support for System.Text.Json, not changing the underlying client.

)

[Pathoschild]

Hi! Microsoft's new philosophy seems to be that HttpClient just handles transport, and deserialization should be handled at a higher level.

I don't mind updating FluentHttpClient to match that philosophy, but it puts us in an awkward spot:

• If we reimplement MediaTypeFormatter (like your PR does), all code which uses that feature will break since none of the implementations use our custom interface. So: major breaking change.
• If we drop content negotiation in newer target frameworks to match the newer HttpClient versions, we lose API parity between target frameworks. So: major breaking change.

Since it's a big breaking change either way, maybe we should just plan for a FluentHttpClient 5.0.0 which revamps the API design across all target frameworks instead of trying to unify the legacy and modern approaches (which isn't possible).

That would mean:

• Should we support content negotiation at all by default?

  FluentHttpClient is meant to be a thin wrapper around HttpClient, but content negotiation is in a gray area between wrapper features (like filters) and custom client logic. Reimplementing the full MediaTypeFormatter ecosystem isn't in scope for this library, and I think it's rarely needed (since we usually know which formats a given API uses).

  If we switch to extension-based deserialization methods, re-adding content negotiation as optional extensions using Microsoft.AspNet.WebApi.Client should be pretty straightforward if we want to.

• Since we're already changing the API, we can also switch to System.Text.Json by default (while still allowing Json.NET or custom deserializers as an option).

• This is a good opportunity to address API design issues like #129 (e.g. make it easier to properly dispose the response).

I'd be interested in @Jericho's thoughts on a 5.0.0 API redesign too.

[Jericho]

I am 100% on board with major changes, even if it "costs" me time and effort when I eventually transition to FluentHttpClient 5.0. I think the up-side (dropping legacy and obsolete references, modernizing the list of targeted frameworks, etc.) makes this effort totally worth it.

And I agree with your statement:

Reimplementing the full MediaTypeFormatter ecosystem isn't in scope for this library, and I think it's rarely needed (since we usually know which formats a given API uses).

In the ten years or so that I have been using FluentHtpClient I can't recall a single scenario where having multiple formatters was beneficial to me. Like you said, the format used by a given API is typically well documented and you only need to convert data to/from this known format. In fact, the standard config for FluentHtpClient in my projects is to remove all the built-in formatters and replace them with a single one (which I wrote) to serialize/deserialize json using System.Text.Json. It looks like this:

// Remove all the built-in formatters and replace them with our custom JSON formatter
_fluentClient.Formatters.Clear();
_fluentClient.Formatters.Add(new JsonFormatter()); // <-- this JsonFormatter is a custom class I wrote

[jmbryan4]

I like the idea of major changes for a 5.0 release too.
@Pathoschild What are your thoughts on targeting netstandard2.0 and net8.0 like StrongGrid's 0.115.0 release

Should we support content negotiation at all by default?

My vote is no for the core/base. Most APIs today are JSON only.
You could have a WebApiFormatters extension for legacy consumers that do not want to change.

Since we're already changing the API, we can also switch to System.Text.Json by default (while still allowing Json.NET or custom deserializers as an option).

I like the idea of moving Json.NET to an extension package outside of the core one. That seems to be a common pattern in related libraries (Refit, Restsharp, etc.)

I think we can close this in favor of a major 5.0 refactor. I opened this issue and PR as a goal to not have the Microsoft.AspNet.WebApi.Client dependency.

Full Native AOT compatibility could be a good goal for 5.0 release too

[Jericho]

@Pathoschild The more I think about it more I realize that what I appreciate the most about FluentHttpClient is: nice fluent syntax, configurable automatic retries, configurable interceptors (they allow me to catch errors, log diagnostic information, add OAuth token to all requests, etc.). It's not "content negotiation", as evidenced by the fact that I have turned off the built-in serializing/deserializing and I wrote my own custom code to achieve this. I'll go even further and say that content negotiation could be completely removed from FluentHttpClient and I would still be happy with the client.

I guess this means that I am leaning towards your idea of making FluentHttpClient a thin wrapper around HttpClient.

Here's my suggestion:

• the main FluentHttpClient NuGet package should not contain any content negotiation
• Optionally, release a second package called something like "FluentHttpClient.JsonNet". This package would contain an extension method off of IRequest called public static IRequest WithJsonBody<T>(this IRequest request, T body) which would convert an object of type T into HttpContent using Newtonsoft's Json.NET. Also, this package would contain a few extension methods off of IResponse to convert the response payload to a Json document, convert the payload into a given model class, etc.
• Optionally, release another NuGet package called something like "FluentHttpClient.System.Text.Json". This package would contain extension methods similar to the ones I described above but it would use Microsoft's System.Text.Json to perform serialization/deserialization.

Developers would be able to choose which of the two Json parsers they whish to use and they could even decide to use neither and perform serialization/deserialization themselves.

This would achieve a clean separation between the main FluentHttpClient and the Json parsers.

[jmbryan4]

@Pathoschild any update on this?

[Pathoschild]

@jmbryan4 With the recent rise of AI, I've been forced to overhaul a lot of the work I do in the Stardew Valley modding community to keep up. So I haven't had time recently to plan out what the new API would look like unfortunately.

It's definitely still something I want to do though. Proposals are welcome if anyone wants to plan out a possible API or implementation before I can get back to this.