Page 61 - MSDN Magazine, March 2018

The OWIN specification and Katana, the implementation of it fortheIIS/ASP.NETenvironment,playnoroleinASP.NETCore. But the experience with these platforms matured the technical vision (especially with Web API edge cases), which shines through the dazzling new pipeline of ASP.NET Core.
The funny thing is that once the entire ASP.NET pipeline was redesigned—deeply inspired by the ideal hosting environment for Web API—that same Web API as a separate framework ceased to be relevant. In the new ASP.NET Core pipeline there’s the need for just one application model—the MVC application model— based on controllers, and controller classes are a bit richer than in classic ASP.NET MVC, thus incorporating the functions of old ASP.NET controllers and Web API controllers.
Extended ASP.NET Core Controllers
In ASP.NET Core, you work with controller classes whether you intend to serve HTML or any other type of response, such as JSON or PDF. A bunch of new action result types have been added to make building RESTful interfaces easy and convenient. Content negoti- ation is fully supported for any controller classes, and formatting helpers have been baked into the action invoker infrastructure. If you want to build a Web API that exposes HTTP endpoints, all you do is build a plain controller class, as shown here:
public class ApiController : Controller {
// Your methods here }
The name of the controller class is arbitrary. While having /api somewhere in the URL is desirable for clarity, it’s in no way required. You can have /api in the URL being invoked both if you use con- ventional routing (an ApiController class) to map URLs to action methods, or if you use attribute routing. In my personal opinion, attribute routing is probably preferable because it allows you to expose multiple endpoints with the same /api item in the URL, while being defined in distinct, arbitrarily named controller classes.
In ASP.NET Core, you work with controller classes whether you intend to serve HTML or any other type of response, such as JSON or PDF.
The Controller class in ASP.NET Core has a lot more features than the class in classic ASP.NET MVC, and most of the exten- sions relate to building a RESTful Web API. First and foremost, all ASP.NET Core controllers support content negotiation. Content negotiation refers to a silent negotiation taking place between the caller and the API regarding the actual format of returned data.
Content negotiation doesn’t happen all the time and for just every request. It takes place only if the incoming request contains an Accept HTTP header that advertises the MIME types the caller
is able to understand. In this case, the ASP.NET Core infrastructure goes through the types listed in the header content until it finds one for which a formatter exists in the current configuration of the application. If no matching formatter is found in the list of types, then the default JSON formatter is used, like so:
[HttpGet]
public ObjectResult Get(Guid id) {
// Do something here to retrieve the resource data var data = FindResourceDataInSomeWay(id);
return Ok(data); }
The Controller class in ASP.NET Core has a lot more features than theclassinclassicASP.NETMVC, and most of the extensions relate to building a RESTful Web API.
Another remarkable aspect of content negotiation is that while it won’t produce any change in the serialization process without an Accept HTTP header, it’s technically triggered only if the response being sent back by the controller is of type ObjectResult. The most common way to return an ObjectResult action result type is by serializing the response via the Ok method. It’s important to note that if you serialize the controller response via, say, the Json method, no negotiation will ever take place regardless of the headers sent. Support for output formatters can be added programmatically through the options of the AddMvc method. Here’s an example:
services.AddMvc(options => {
options.OutputFormatters.Add(new PdfFormatter()); });
In this example, the demo class PdfFormatter contains internally the list of supported MIME types it can handle.
Note that by using the Produces attribute you override the con- tent negotiation, as shown here:
[Produces("application/json")]
public class ApiController : Controller {
// Action methods here }
The Produces attribute, which you can apply at the controller or method level, forces the output of type ObjectResult to be always serialized in the format specified by the attribute, regardless of the Accept HTTP header.
For more information on how to format the response of a control- ler method, you might want to check out the content at bit.ly/2klDgdY.
REST-Oriented Action Result Types
Whether a Web API is better off with a REST design is a highly debat- able point. In general, it’s safe enough to say that the REST approach is based on a known set of rules and, in this regard, it is more stan- dard. For this reason, it’s generally recommended for a public API
msdnmagazine.com
March 2018 55