Custom formatters in ASP.NET Core MVC web APIs

By Tom Dykstra

ASP.NET Core MVC has built-in support for data exchange in web APIs by using JSON, XML, or plain text formats. This article shows how to add support for additional formats by creating custom formatters.

View or download sample from GitHub.

When to use custom formatters

Use a custom formatter when you want the content negotiation process to support a content type that isn't supported by the built-in formatters (JSON, XML, and plain text).

For example, if some of the clients for your web API can handle the Protobuf format, you might want to use Protobuf with those clients because it's more efficient. Or you might want your web API to send contact names and addresses in vCard format, a commonly used format for exchanging contact data. The sample app provided with this article implements a simple vCard formatter.

Overview of how to use a custom formatter

Here are the steps to create and use a custom formatter:

  • Create an output formatter class if you want to serialize data to send to the client.
  • Create an input formatter class if you want to deserialize data received from the client.
  • Add instances of your formatters to the InputFormatters and OutputFormatters collections in MvcOptions.

The following sections provide guidance and code examples for each of these steps.

How to create a custom formatter class

To create a formatter:

  • Derive the class from the appropriate base class.
  • Specify valid media types and encodings in the constructor.
  • Override CanReadType/CanWriteType methods
  • Override ReadRequestBodyAsync/WriteResponseBodyAsync methods

Derive from the appropriate base class

For text media types (for example, vCard), derive from the TextInputFormatter or TextOutputFormatter base class.

public class VcardOutputFormatter : TextOutputFormatter

For binary types, derive from the InputFormatter or OutputFormatter base class.

Specify valid media types and encodings

In the constructor, specify valid media types and encodings by adding to the SupportedMediaTypes and SupportedEncodings collections.

public VcardOutputFormatter()
{
    SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));

    SupportedEncodings.Add(Encoding.UTF8);
    SupportedEncodings.Add(Encoding.Unicode);
}
备注

You can't do constructor dependency injection in a formatter class. For example, you can't get a logger by adding a logger parameter to the constructor. To access services, you have to use the context object that gets passed in to your methods. A code example below shows how to do this.

Override CanReadType/CanWriteType

Specify the type you can deserialize into or serialize from by overriding the CanReadType or CanWriteType methods. For example, you might only be able to create vCard text from a Contact type and vice versa.

protected override bool CanWriteType(Type type)
{
    if (typeof(Contact).IsAssignableFrom(type) 
        || typeof(IEnumerable<Contact>).IsAssignableFrom(type))
    {
        return base.CanWriteType(type);
    }
    return false;
}

The CanWriteResult method

In some scenarios you have to override CanWriteResult instead of CanWriteType. Use CanWriteResult if the following conditions are true:

  • Your action method returns a model class.
  • There are derived classes which might be returned at runtime.
  • You need to know at runtime which derived class was returned by the action.

For example, suppose your action method signature returns a Person type, but it may return a Student or Instructor type that derives from Person. If you want your formatter to handle only Student objects, check the type of Object in the context object provided to the CanWriteResult method. Note that it's not necessary to use CanWriteResult when the action method returns IActionResult; in that case, the CanWriteType method receives the runtime type.

Override ReadRequestBodyAsync/WriteResponseBodyAsync

You do the actual work of deserializing or serializing in ReadRequestBodyAsync or WriteResponseBodyAsync. The highlighted lines in the following example show how to get services from the dependency injection container (you can't get them from constructor parameters).

public override Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding selectedEncoding)
{
    IServiceProvider serviceProvider = context.HttpContext.RequestServices;
    var logger = serviceProvider.GetService(typeof(ILogger<VcardOutputFormatter>)) as ILogger;

    var response = context.HttpContext.Response;

    var buffer = new StringBuilder();
    if (context.Object is IEnumerable<Contact>)
    {
        foreach (Contact contact in context.Object as IEnumerable<Contact>)
        {
            FormatVcard(buffer, contact, logger);
        }
    }
    else
    {
        var contact = context.Object as Contact;
        FormatVcard(buffer, contact, logger);
    }
    return response.WriteAsync(buffer.ToString());
}

private static void FormatVcard(StringBuilder buffer, Contact contact, ILogger logger)
{
    buffer.AppendLine("BEGIN:VCARD");
    buffer.AppendLine("VERSION:2.1");
    buffer.AppendFormat($"N:{contact.LastName};{contact.FirstName}\r\n");
    buffer.AppendFormat($"FN:{contact.FirstName} {contact.LastName}\r\n");
    buffer.AppendFormat($"UID:{contact.ID}\r\n");
    buffer.AppendLine("END:VCARD");
    logger.LogInformation($"Writing {contact.FirstName} {contact.LastName}");
}

How to configure MVC to use a custom formatter

To use a custom formatter, add an instance of the formatter class to the InputFormatters or OutputFormatters collection.

services.AddMvc(options =>
{
    options.InputFormatters.Add(new VcardInputFormatter());
    options.OutputFormatters.Add(new VcardOutputFormatter());
});

Next steps

See the sample application, which implements simple vCard input and output formatters. The application reads and writes vCards that look like the following example:

BEGIN:VCARD
VERSION:2.1
N:Davolio;Nancy
FN:Nancy Davolio
UID:20293482-9240-4d68-b475-325df4a83728
END:VCARD

To see vCard output, run the application and send a Get request with Accept header "text/vcard" to http://localhost:63313/api/contacts/ (when running from Visual Studio) or http://localhost:5000/api/contacts/ (when running from the command line).

To add a vCard to the in-memory collection of contacts, send a Post request to the same URL, with Content-Type header "text/vcard" and with vCard text in the body, formatted like the example above.