In a recent ASP.NET MVC application I’m involved with, we had a late
in the process request to handle Content Negotiation: Returning output based on
the HTTP Accept header of
the incoming HTTP request. This is standard behavior
in ASP.NET Web API but ASP.NET MVC doesn’t support this functionality directly out of
the box. Another reason this came up
in discussion is last week’s announcements of ASP.NET vNext, which seems to indicate that ASP.NET Web API is not going to be ported to
the cloud version of vNext, but rather be replaced by a combined version of MVC and Web API. While it’s not clear what new API features will show up
in this new framework, it’s pretty clear that
the ASP.NET MVC style syntax will be
the new standard for all
the new combined HTTP processing framework. Why negotiated Content? Content negotiation is one of
the key features of Web API even though it’s such a relatively simple thing. But it’s also something that’s missing
in MVC and once you get used to automatically having your content returned based on Accept headers it’s hard to go back to manually having to create separate methods for different output types as you’ve had to with Microsoft server technologies all along (yes, yes I know other frameworks – including my own – have done this for years but for
in the box features this is relatively new from Web API). As a quick review, Accept Header content negotiation works off
the request’s HTTP Accept header:POST http://localhost/mydailydosha/Editable/NegotiateContent HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost
Content-Length: 76
Pragma: no-cache
{ ElementId: "header", PageName: "TestPage", Text: "This is a nice header" }
If I make this request I would expect to get back a JSON result based on my application/json Accept header. To request XML I‘d just change
the accept header:Accept: text/xml
and now I’d expect
the response to come back as XML. Now this only works with media types that
the server can process.
In my case here I need to handle JSON, XML, HTML (using Views) and Plain Text. HTML results might need more than just a data return – you also probably need to specify a View to render
the data into either by specifying
the view explicitly or by using some sort of convention that can automatically locate a view to match. Today ASP.NET MVC doesn’t support this sort of automatic content switching out of
the box.
Unfortunately,
in my application scenario we have an application that started out primarily with an AJAX backend that was implemented with JSON only. So there are lots of JSON results like this:[Route("Customers")]
public ActionResult GetCustomers()
{
return Json(repo.GetCustomers(),JsonRequestBehavior.AllowGet);
}
These work fine, but they are of course JSON specific. Then a couple of weeks ago, a requirement came
in that an old desktop application needs to also consume this API and it has to use XML to do it because there’s no JSON parser available for it. Ooops – stuck with JSON
in this case.
While it would have been easy to add XML specific methods I figured it’s easier to add basic content negotiation. And that’s what I show
in this post.
Missteps – IResultFilter, IActionFilter
My first attempt at this was to use IResultFilter or IActionFilter which look like they would be ideal to modify result content after it’s been generated using OnResultExecuted() or OnActionExecuted(). Filters are great because they can look globally at all controller methods or individual methods that are marked up with
the Filter’s attribute. But it turns out these filters don’t work for raw POCO result values from Action methods.
What we wanted to do for API calls is get back to using plain .NET types as results rather than result actions. That is you write a method that doesn’t return an ActionResult, but a standard .NET type like this:public Customer UpdateCustomer(Customer cust)
{
… do stuff to customer :-) return cust;
}
Unfortunately both OnResultExecuted and OnActionExecuted receive an MVC ContentResult instance from
the POCO object. MVC basically takes any non-ActionResult return value and turns it into a ContentResult by converting
the value using .ToString(). Ugh.
The ContentResult itself doesn’t contain
the original value, which is lost AFAIK with no way to retrieve it. So there’s no way to access
the raw customer object
in the example above. Bummer.
Creating a NegotiatedResult
This leaves mucking around with custom ActionResults. ActionResults are MVC’s standard way to return action method results – you basically specify that you would like to render your result
in a specific format. Common ActionResults are ViewResults (ie. View(vn,model)), JsonResult, RedirectResult etc. They work and are fairly effective and work fairly well for testing as well as it’s
the ‘standard’ interface to return results from actions.
The problem with
the this is mainly that you’re explicitly saying that you want a specific result output type. This works well for many things, but sometimes you do want your result to be negotiated.
My first
crack at this solution here is to create a simple ActionResult subclass that looks at
the Accept header and based on that writes
the output. I need to support JSON and XML content and HTML as well as text – so effectively 4 media types: application/json, text/xml, text/html and text/plain. Everything else is passed through as ContentResult – which effecively returns whatever .ToString() returns.
Here’s what
the NegotiatedResult usage looks like:public ActionResult GetCustomers()
{
return new NegotiatedResult(repo.GetCustomers());
}
public ActionResult GetCustomer(int id)
{
return new NegotiatedResult("Show", repo.GetCustomer(id));
}
There are two overloads of this method – one that returns just
the raw result value and a second version that accepts an optional view name.
The second version returns
the Razor view specified only if text/html is requested – otherwise
the raw data is returned. This is useful
in applications where you have an HTML front end that can also double as an API interface endpoint that’s using
the same model data you send to
the View. For
the application I mentioned above this was another actual use-case we needed to address so this was a welcome side effect of creating a custom ActionResult.
There’s also an extension method that directly attaches a Negotiated() method to
the controller using
the same syntax:public ActionResult GetCustomers()
{
return this.Negotiated(repo.GetCustomers());
}
public ActionResult GetCustomer(int id)
{
return this.Negotiated("Show",repo.GetCustomer(id));
}
Using either of these mechanisms now allows you to return JSON, XML, HTML or plain text results depending on
the Accept header sent. Send application/json you get just
the Customer JSON data. Ditto for text/xml and XML data. Pass text/html for
the Accept header and
the "Show.cshtml" Razor view is rendered passing
the result model data producing final HTML output.
While this isn’t as clean as passing just POCO objects back as I had intended originally, this approach fits better with how MVC action methods are intended to be used and we get
the bonus of being able to specify a View to render (optionally) for HTML.
How does it work
An ActionResult implementation is pretty straightforward. You inherit from ActionResult and implement
the ExecuteResult method to send your output to
the ASP.NET output stream. ActionFilters are an easy way to effectively do post processing on ASP.NET MVC controller actions just before
the content is sent to
the output stream, assuming your specific action result was used.
Here’s
the full code to
the NegotiatedResult class (you can also check it out on GitHub):/// <summary>
/// Returns a content negotiated result based on
the Accept header.
/// Minimal implementation that works with JSON and XML content,
/// can also optionally return a view with HTML.
/// </summary>
/// <example>
/// // model data only
/// public ActionResult GetCustomers()
/// {
/// return new NegotiatedResult(repo.Customers.OrderBy( c=> c.Company) )
/// }
/// // optional view for HTML
/// public ActionResult GetCustomers()
/// {
/// return new NegotiatedResult("List", repo.Customers.OrderBy( c=> c.Company) )
/// }
/// </example>
public class NegotiatedResult : ActionResult
{
/// <summary>
/// Data stored to be 'serialized'. Public
/// so it's potentially accessible
in filters.
/// </summary>
public object Data { get; set; }
/// <summary>
/// Optional name of
the HTML view to be rendered
/// for HTML responses
/// </summary>
public string ViewName { get; set; }
public static bool FormatOutput { get; set; }
static NegotiatedResult()
{
FormatOutput = HttpContext.Current.IsDebuggingEnabled;
}
/// <summary>
/// Pass
in data to serialize
/// </summary>
/// <param name="data">Data to serialize</param>
public NegotiatedResult(object data)
{
Data = data;
}
/// <summary>
/// Pass
in data and an optional view for HTML views
/// </summary>
/// <param name="data"></param>
/// <param name="viewName"></param>
public NegotiatedResult(string viewName, object data)
{
Data = data;
ViewName = viewName;
}
public override void ExecuteResult(ControllerContext context)
{
if (context == null)
throw new ArgumentNullException("context");
HttpResponseBase response = context.HttpContext.Response;
HttpRequestBase request = context.HttpContext.Request;
// Look for specific content types
if (request.AcceptTypes.Contains("text/html"))
{
response.ContentType = "text/html";
if (!string.IsNullOrEmpty(ViewName))
{
var viewData = context.Controller.ViewData;
viewData.Model = Data;
var viewResult = new ViewResult
{
ViewName = ViewName,
MasterName = null,
ViewData = viewData,
TempData = context.Controller.TempData,
ViewEngineCollection = ((Controller)context.Controller).ViewEngineCollection
};
viewResult.ExecuteResult(context.Controller.ControllerContext);
}
else
response.Write(Data);
}
else if (request.AcceptTypes.Contains("text/plain"))
{
response.ContentType = "text/plain";
response.Write(Data);
}
else if (request.AcceptTypes.Contains("application/json"))
{
using (JsonTextWriter writer = new JsonTextWriter(response.Output))
{
var settings = new JsonSerializerSettings();
if (FormatOutput)
settings.Formatting = Newtonsoft.Json.Formatting.Indented;
JsonSerializer serializer = JsonSerializer.Create(settings);
serializer.Serialize(writer, Data);
writer.Flush();
}
}
else if (request.AcceptTypes.Contains("text/xml"))
{
response.ContentType = "text/xml";
if (Data != null)
{
using (var writer = new XmlTextWriter(response.OutputStream, new UTF8Encoding()))
{
if (FormatOutput)
writer.Formatting = System.Xml.Formatting.Indented;
XmlSerializer serializer = new XmlSerializer(Data.GetType());
serializer.Serialize(writer, Data);
writer.Flush();
}
}
}
else
{
// just write data as a plain string
response.Write(Data);
}
}
}
/// <summary>
/// Extends Controller with Negotiated() ActionResult that does
/// basic content negotiation based on
the Accept header.
/// </summary>
public static class NegotiatedResultExtensions
{
/// <summary>
/// Return content-negotiated content of
the data based on Accept header.
/// Supports:
/// application/json - using JSON.NET
/// text/xml - Xml as XmlSerializer XML
/// text/html - as text, or an optional View
/// text/plain - as text
/// </summary>
/// <param name="controller"></param>
/// <param name="data">Data to return</param>
/// <returns>serialized data</returns>
/// <example>
/// public ActionResult GetCustomers()
/// {
/// return this.Negotiated( repo.Customers.OrderBy( c=> c.Company) )
/// }
/// </example>
public static NegotiatedResult Negotiated(this Controller controller, object data)
{
return new NegotiatedResult(data);
}
/// <summary>
/// Return content-negotiated content of
the data based on Accept header.
/// Supports:
/// application/json - using JSON.NET
/// text/xml - Xml as XmlSerializer XML
/// text/html - as text, or an optional View
/// text/plain - as text
/// </summary>
/// <param name="controller"></param>
/// <param name="viewName">Name of
the View to when Accept is text/html</param>
/// /// <param name="data">Data to return</param>
/// <returns>serialized data</returns>
/// <example>
/// public ActionResult GetCustomers()
/// {
/// return this.Negotiated("List", repo.Customers.OrderBy( c=> c.Company) )
/// }
/// </example>
public static NegotiatedResult Negotiated(this Controller controller, string viewName, object data)
{
return new NegotiatedResult(viewName, data);
}
}
Output Generation – JSON and XML
Generating output for XML and JSON is simple – you use
the desired serializer and off you go. Using XmlSerializer and JSON.NET it’s just a handful of lines each to generate serialized output directly into
the HTTP output stream.
Please note this implementation uses JSON.NET for its JSON generation rather than
the default JavaScriptSerializer that MVC uses which I feel is an additional bonus to implementing this custom action. I’d already been using a custom JsonNetResult class previously, but now this is just rolled into this custom ActionResult.
Just keep
in mind that JSON.NET outputs slightly different JSON for certain things like collections for example, so behavior may change. One addition to this implementation might be a flag to allow switching
the JSON serializer.
Html View Generation
Html View generation actually turned out to be easier than anticipated. Initially I used my generic ASP.NET ViewRenderer Class that can render MVC views from any ASP.NET application. However it turns out since we are executing inside of an active MVC request there’s an easier way: We can simply create a custom ViewResult and populate its members and then execute it.
The code
in text/html handling code that renders
the view is simply this:response.ContentType = "text/html";
if (!string.IsNullOrEmpty(ViewName))
{
var viewData = context.Controller.ViewData;
viewData.Model = Data;
var viewResult = new ViewResult
{
ViewName = ViewName,
MasterName = null,
ViewData = viewData,
TempData = context.Controller.TempData,
ViewEngineCollection = ((Controller)context.Controller).ViewEngineCollection
};
viewResult.ExecuteResult(context.Controller.ControllerContext);
}
else
response.Write(Data);
which is a neat and easy way to render a Razor view assuming you have an active controller that’s ready for rendering. Sweet – dependency removed which makes this class self-contained without any external dependencies other than JSON.NET.
Summary
While this isn’t exactly a new topic, it’s
the first time I’ve actually delved into this with MVC. I’ve been doing content negotiation with Web API and prior to that with my REST library. This is
the first time it’s come up as an issue
in MVC. But as I have worked through this I find that having a way to specify both HTML Views *and* JSON and XML results from a single controller certainly is appealing to me
in many situations as we are
in this particular application returning identical data models for each of these operations.
Rendering content negotiated views is something that I hope ASP.NET vNext will provide natively
in the combined MVC and WebAPI model, but we’ll see how this actually will be implemented.
In the meantime having a custom ActionResult that provides this functionality is a workable and easily adaptable way of handling this going forward. Whatever ends up happening
in ASP.NET vNext
the abstraction can probably be changed to support
the native features of
the future.
Anyway I hope some of you found this useful if not for direct integration then as insight into some of
the rendering logic that MVC uses to get output into
the HTTP stream…
Related Resources
Latest Version of NegotiatedResult.cs on GitHub
Understanding Action Controllers
Rendering ASP.NET Views To String© Rick Strahl, West Wind Technologies, 2005-2014Posted
in MVC ASP.NET HTTP
Tweet
!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
(function() {
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
po.src = 'https://apis.google.com/js/plusone.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
})();
