liveBook · Manning

Formatter

As explained in ASP.NET Core in Action, 3e

A formatter is an ASP.NET Core component that serializes or deserializes HTTP content in a particular representation format.

A formatter turns an API model into a response representation, such as JSON or XML. In a web API controller, an output formatter fills the role that a Razor view fills in a page application: it produces the content sent to the caller. section 20.2

Returning a model

An action such as `public IEnumerable<string> ListCars() => new[] { "Nissan Micra", "Ford Focus" };` returns data, not a ready-made response body. An `IOutputFormatter` serializes that data. If a client requests XML with an `Accept: text/xml` header but XML support is not configured, the response falls back to JSON by default. section 20.5

The client’s `Accept` header and the available formatters guide content negotiation. By default, ASP.NET Core supports `application/json`, `text/plain`, and `text/html`. With no `Accept` header, a string is formatted as plain text, while other API models typically use JSON; a null model produces `204 No Content`. A browser header containing `*/*` normally bypasses negotiation and uses the default formatter. section 20.5.1 section 20.5.2

services.AddControllers()
   .AddXmlSerializerFormatters();

Add `.AddXmlSerializerFormatters()` after `AddControllers()` to support XML responses and XML request bodies. An `Accept: text/xml` request can then receive XML. section 20.5.1 section 20.7

For different JSON behavior, `.AddNewtonsoftJson()` replaces the default System.Text.Json formatter. ASP.NET Core 3.0 onward uses System.Text.Json by default; its stricter deserialization can matter when incoming JSON does not meet its expectations. section 20.5.1

Listing 20.14 Customizing MVC to respect the browser’s Accept header in web APIs
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddControllers(options =>                           #1
{
    options.RespectBrowserAcceptHeader = true;                       #2
    options.OutputFormatters.RemoveType<StringOutputFormatter>();    #3
});
#1 AddControllers has an overload that takes a lambda function.
#2 False by default; several other properties are also available to be set.
#3 Removes the output formatter that formats strings as text/plain

Set `RespectBrowserAcceptHeader` to `true` to honor a browser’s `Accept` header. The same configuration removes `StringOutputFormatter` if strings should no longer be returned as `text/plain`. section 20.5.2

How ASP.NET Core in Action, 3e covers it

How deep it goes
Explains default format selection, negotiation exceptions, and configuration; does not implement a custom formatter.
Examples
Uses a car-list controller, an XML request that falls back to JSON, and configuration for XML and browser Accept headers.
What it assumes
Assumes controller action methods and API models as context while defining what an output formatter does.
What you can do after
Operate/configure it with `AddXmlSerializerFormatters()`, `AddNewtonsoftJson()`, or controller options to change supported formats and negotiation behavior.
How it connects
Connects API models, web API controllers, content negotiation, and the HTTP Accept header.
Cover of ASP.NET Core in Action, 3e
liveBookmanning.com
Read ASP.NET Core in Action, 3e on liveBook Get the book at manning.com

Also explained in

Compare how 2 books explain Formatter →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of ASP.NET Core in Action, 3e. The section links point to the parts of the book it draws on.