Fetching contributors…
Cannot retrieve contributors at this time
92 lines (54 sloc) 4.9 KB
uid title author description ms.assetid msc.legacyurl msc.type
Media Formatters in ASP.NET Web API 2 | Microsoft Docs

Media Formatters in ASP.NET Web API 2

by Mike Wasson

This tutorial shows how to support additional media formats in ASP.NET Web API.

Internet Media Types

A media type, also called a MIME type, identifies the format of a piece of data. In HTTP, media types describe the format of the message body. A media type consists of two strings, a type and a subtype. For example:

  • text/html
  • image/png
  • application/json

When an HTTP message contains an entity-body, the Content-Type header specifies the format of the message body. This tells the receiver how to parse the contents of the message body.

For example, if an HTTP response contains a PNG image, the response might have the following headers.


When the client sends a request message, it can include an Accept header. The Accept header tells the server which media type(s) the client wants from the server. For example:


This header tells the server that the client wants either HTML, XHTML, or XML.

The media type determines how Web API serializes and deserializes the HTTP message body. Web API has built-in support for XML, JSON, BSON, and form-urlencoded data, and you can support additional media types by writing a media formatter.

To create a media formatter, derive from one of these classes:

Deriving from BufferedMediaTypeFormatter is simpler, because there is no asynchronous code, but it also means the calling thread can block during I/O.

Example: Creating a CSV Media Formatter

The following example shows a media type formatter that can serialize a Product object to a comma-separated values (CSV) format. This example uses the Product type defined in the tutorial Creating a Web API that Supports CRUD Operations. Here is the definition of the Product object:


To implement a CSV formatter, define a class that derives from BufferedMediaTypeFormater:


In the constructor, add the media types that the formatter supports. In this example, the formatter supports a single media type, "text/csv":


Override the CanWriteType method to indicate which types the formatter can serialize:


In this example, the formatter can serialize single Product objects as well as collections of Product objects.

Similarly, override the CanReadType method to indicate which types the formatter can deserialize. In this example, the formatter does not support deserialization, so the method simply returns false.


Finally, override the WriteToStream method. This method serializes a type by writing it to a stream. If your formatter supports deserialization, also override the ReadFromStream method.


Adding a Media Formatter to the Web API Pipeline

To add a media type formatter to the Web API pipeline, use the Formatters property on the HttpConfiguration object.


Character Encodings

Optionally, a media formatter can support multiple character encodings, such as UTF-8 or ISO 8859-1.

In the constructor, add one or more System.Text.Encoding types to the SupportedEncodings collection. Put the default encoding first.


In the WriteToStream and ReadFromStream methods, call MediaTypeFormatter.SelectCharacterEncoding to select the preferred character encoding. This method matches the request headers against the list of supported encodings. Use the returned Encoding when you read or write from the stream: