A deep dive into the ASP.NET Web API Runtime Architecture NDC London 2013 Pedro Félix @pmhsfelix [email protected] 1 

whoami • Professor at the Lisbon Polytechnic Institute • Independent Consultant • Web APIs, Identity and Access Control • Co-author of Designing Evolvable Web APIs with ASP.NET (to be published in 2014 by O’Reilly) 2 

Concrete Controller HTTP HTTP is a stateless request/response protocol that operates by exchanging messages An HTTP "server" is a program that accepts connections in order to service HTTP requests by sending HTTP responses. In Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing 3 Request Message Response Message ? ASP.NET Web API 

Outline • “What” - Message Representation • The System.Net.Http model • “How” - Message Processing • Processing layers • Extensibility points 4 

System.Net.Http 5 

System.Net.Http 6 New in .NET 4.5 Extended by System.Net.Http.Formatting (Install-Package Microsoft.AspNet.WebApi.Client) Same model on the cliente and on the server 

System.Net.Http 7 New in .NET 4.5 Extended by System.Net.Http.Formatting (Install-Package Microsoft.AspNet.WebApi.Client) Messages as Values with some encoding and validation behavior Rich typed class model Easy to instantiate Same model on the cliente and on the server 

Instantiability and testability 8 [Fact] public void HttpRequestMessage_is_easy_to_instantiate() { var request = new HttpRequestMessage( HttpMethod.Get, new Uri("http://www.ietf.org/rfc/rfc2616.txt")); Assert.Equal(HttpMethod.Get, request.Method); Assert.Equal("http://www.ietf.org/rfc/rfc2616.txt", request.RequestUri.ToString()); Assert.Equal(new Version(1,1), request.Version); } [Fact] public void HttpResponseMessage_is_easy_to_instantiate() { var response = new HttpResponseMessage(HttpStatusCode.OK); Assert.Equal(HttpStatusCode.OK, response.StatusCode); Assert.Equal(new Version(1,1), response.Version); } 

Typed headers 9 

Typed headers 10 [Fact] public void Header_classes_expose_headers_in_a_strongly_typed_way() { var request = new HttpRequestMessage(); request.Headers.Add("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"); HttpHeaderValueCollection accept = request.Headers.Accept; Assert.Equal(4, accept.Count); MediaTypeWithQualityHeaderValue third = accept.Skip(2).First(); Assert.Equal("application/xml", third.MediaType); Assert.Equal(0.9, third.Quality); Assert.Null(third.CharSet); } 

HttpContent 11 

HttpContent 12 ReadAsAsync extension method Push Pull 

HttpContent 13 CustomContent 

HttpContent 14 CustomContent 

Custom content 15 public class FileContent : HttpContent { private readonly Stream _fstream; public FileContent(string path, string mediaType = "application/octet-stream") { _fstream = new FileStream(path, FileMode.Open, FileAccess.Read); base.Headers.ContentType = new MediaTypeHeaderValue(mediaType); } protected override Task SerializeToStreamAsync(Stream stream, …) { return _fstream.CopyToAsync(stream); } protected override bool TryComputeLength(out long length) { if (!_fstream.CanSeek){ length = 0; return false; } else{ length = _fstream.Length; return true; } } protected override void Dispose(bool disposing) { _fstream.Dispose(); } } 

System.Net.Http 16 • Faithful to RFC 2616 • Easier to instantiate and test • Both typed and untyped access to message members (e.g. headers) • Extensible HTTP content class hierarchy • Based on the Task Asynchronous Pattern • Similar on both the client and server sides 

Message Processing 17 

Runtime Architecture Web Host | Self Host | OWIN Host Message Handler ApiController Concrete Controller GetAction PostAction ... 18 HttpRequestMessage HttpResponseMessage HttpRequestMessage HttpResponseMessage HttpRequestMessage HttpResponseMessage Message Handler Message Handler • Controller Layer • From messages to method invocations • Controllers, actions, parameters • Model binding, validation and formatters • Filters • Message Handling Layer • Message transformation • HTTP intermediaries • Host adaptation Layer • Request message generation • Response message consuption 

Message Handlers 19 HttpRequestMessage HttpResponseMessage Message Handler HttpRequestMessage Task DelegatingHandler HttpRequestMessage HttpResponseMessage 

Message Handlers 20 HttpRequestMessage HttpResponseMessage Message Handler HttpRequestMessage Task DelegatingHandler HttpRequestMessage HttpResponseMessage 

Message Handlers 21 HttpRequestMessage HttpResponseMessage Message Handler HttpRequestMessage Task DelegatingHandler HttpRequestMessage HttpResponseMessage Same model on the client and server sides 

E.g. Basic Authentication 22 async protected override Task SendAsync( HttpRequestMessage request, CancellationToken cancellationToken) { 

E.g. Basic Authentication 23 async protected override Task SendAsync( HttpRequestMessage request, CancellationToken cancellationToken) { if (HasAuthorizationHeaderWithBasicScheme(request)) { var username = TryExtractAndValidateCredentials( request.Headers.Authorization.Parameter); if (username == null) return UnauthorizedResponseMessage(_realm); SetPrincipal(request, username); } 

E.g. Basic Authentication 24 async protected override Task SendAsync( HttpRequestMessage request, CancellationToken cancellationToken) { if (HasAuthorizationHeaderWithBasicScheme(request)) { var username = TryExtractAndValidateCredentials( request.Headers.Authorization.Parameter); if (username == null) return UnauthorizedResponseMessage(_realm); SetPrincipal(request, username); } var response = await base.SendAsync(request, cancellationToken); 

E.g. Basic Authentication 25 async protected override Task SendAsync( HttpRequestMessage request, CancellationToken cancellationToken) { if (HasAuthorizationHeaderWithBasicScheme(request)) { var username = TryExtractAndValidateCredentials( request.Headers.Authorization.Parameter); if (username == null) return UnauthorizedResponseMessage(_realm); SetPrincipal(request, username); } var response = await base.SendAsync(request, cancellationToken); if(response.StatusCode == HttpStatusCode.Unauthorized) response.Headers.WwwAuthenticate.Add( new AuthenticationHeaderValue("Basic", string.Format("realm={0}", _realm))); return response; } 

HttpServer 26 Delegating Handler Http Configuration Route Dispatcher Controller Dispatcher Per-Route Handler Delegating Handler 

HttpServer 27 Delegating Handler Http Configuration Route Dispatcher Controller Dispatcher Per-Route Handler Delegating Handler 

HttpServer 28 Delegating Handler Http Configuration Route Dispatcher Controller Dispatcher Per-Route Handler Delegating Handler 

HttpServer 29 Delegating Handler Http Configuration Route Dispatcher Controller Dispatcher Per-Route Handler Delegating Handler 

HttpServer 30 Delegating Handler Http Configuration Route Dispatcher Controller Dispatcher Per-Route Handler Delegating Handler 

31 Web Host | Self Host | OWIN Hosts ApiController Concrete Controller GetAction PostAction ... HttpRequestMessage HttpResponseMessage HttpRequestMessage HttpResponseMessage Delegating Handler Http Configuration Delegating Handler Route Dispatcher Controller Dispatcher Per-Route Handler Configuration • Routing HttpRouteCollection Routes { get; } • Extensibility points Collection MessageHandlers { get; } HttpFilterCollection Filters { get; } MediaTypeFormatterCollection Formatters { get; } ParameterBindingRulesCollection ParameterBindingRules { get; } • Service location IDependencyResolver DependencyResolver { get; set; } ServicesContainer Services { get; internal set; } 

Message Processing Host Adaptation Layer 32 

Host Adaptation Layer Web Host | Self Host | OWIN Host 33 HttpRequestMessage HttpResponseMessage Delegating Handler Http Configuration Delegating Handler … 

OWIN 34 Middleware Middleware Server IDictionary … 

OWIN Adapter • Creates HttpRequestMessage from OwinRequest • Uses StreamContent • Buffers the Input stream, if needed • IHostBufferPolicySelector • Sends the request to the Web API pipeline • Buffers the output stream, if needed • Writes the response into the OwinResponse HttpMessageHandlerAdapter : OwinMiddleware 35 HttpRequestMessage HttpResponseMessage Delegating Handler Http Configuration Delegating Handler … Middleware Server IDictionary 

HttpRequestContext • Creates HttpRequestMessage from OwinRequest • Uses StreamContext • Defines the HttpRequestContext • Buffers the Input stream, if needed • IHostBufferPolicySelector • Sends the request to the Web API pipeline • Buffers the output stream, if needed • Writes the response into the OwinResponse HttpMessageHandlerAdapter : OwinMiddleware 36 HttpRequestMessage HttpResponseMessage Delegating Handler Http Configuration Delegating Handler … Middleware Server IDictionary // New in v2 public class HttpRequestContext { public virtual X509Certificate2 ClientCertificate { get; set; } public virtual IPrincipal Principal { get; set; } … } // Accessed via extension messages on HttpRequestMessage public static HttpRequestContext GetRequestContext(this HttpRequestMessage request) { return request.GetProperty(HttpPropertyKeys.RequestContextKey); } public static void SetRequestContext(this HttpRequestMessage request, HttpRequestContext context) { request.Properties[HttpPropertyKeys.RequestContextKey] = context; } 

OWIN Web API Registration • Creates HttpRequestMessage from OwinRequest • Uses StreamContext • Defines the HttpRequestContext • Buffers the Input stream, if needed • IHostBufferPolicySelector • Sends the request to the Web API pipeline • Buffers the output stream, if needed • Writes the response into the OwinResponse HttpMessageHandlerAdapter : OwinMiddleware 37 HttpRequestMessage HttpResponseMessage Delegating Handler Http Configuration Delegating Handler … Middleware Server IDictionary using(var server = TestServer.Create(app => { var config = new HttpConfiguration(); app.UseWebApi(config); })){ … } public static IAppBuilder UseWebApi(this IAppBuilder builder, HttpConfiguration configuration) { return builder.Use(typeof(HttpMessageHandlerAdapter), new HttpServer(configuration), …) } 

In-memory hosting with Katana 38 HttpMessageHandlerAdapter : OwinMiddleware 38 HttpRequestMessage HttpResponseMessage Delegating Handler Http Configuration Delegating Handler … Middleware TestServer IDictionary Message Handler HttpClient 

In-memory hosting without Katana • Since a HttpServer is also a delegating handler... 39 Message Handler HttpClient Delegating Handler Http Configuration Delegating Handler … [Fact] public async Task Memory_host_by_connecting_the_client_to_the_server() { var config = new HttpConfiguration(); config.MapHttpAttributeRoutes(); var server = new HttpServer(config); var client = new HttpClient(server); var resp = await client.GetAsync("http://does.not.matter/resources"); Assert.Equal(HttpStatusCode.OK, resp.StatusCode); } 

In-memory hosting • Because a HttpServer is also a delegating handler... 40 Message Handler HttpClient Delegating Handler Http Configuration Delegating Handler … 

Service Bus Relay Hosting 41 Service Bus Relay HttpMessageHandlerAdapter : OwinMiddleware 41 HttpRequestMessage HttpResponseMessage Delegating Handler Http Configuration Delegating Handler … Middleware AzureServiceBusOwinServer IDictionary 

Message Processing Controller Layer 42 

Controller Dispatching 43 IHttpController Concrete Controller GetAction PostAction ... HttpControllerDispatcher HttpResponseMessage HttpRequestMessage HttpControllerContext HttpRequestMessage HttpControllerDescriptor HttpResponseMessage ApiController (actions, filters, model binding, formatters) Concrete Controller ExecuteAsync 

Controller selection, instantiation and invocation 44 

ApiController.ExecuteAsync • Initialize properties (e.g. Request, User) from controller context • Use IHttpActionSelector to get HttpActionDescriptor • Filters • Parameter binding • Result convertion • Create HttpActionContext • Create action pipeline • filters, parameter binding and result conversion • Invoke pipeline 45 

Action pipeline 46 HttpActionContext Action method HttpResponseMessage HttpRequestMessage 

Action pipeline 47 HttpActionContext Action method HttpRequestMessage AuthorizationFilter AuthenticationFilter HttpResponseMessage HttpRequestMessage 

Action pipeline 48 AuthorizationFilter HttpResponseMessage HttpActionContext AuthorizationFilter Action method HttpRequestMessage AuthorizationFilter AuthenticationFilter HttpResponseMessage HttpRequestMessage 

Action pipeline 49 AuthorizationFilter HttpResponseMessage HttpActionContext AuthorizationFilter HttpActionBinding action arguments Action method HttpRequestMessage AuthorizationFilter AuthenticationFilter HttpResponseMessage HttpRequestMessage Parameters 

Action pipeline 50 AuthorizationFilter HttpResponseMessage HttpActionContext AuthorizationFilter HttpActionBinding AuthorizationFilter ActionFilter HttpResponseMessage action arguments Action method HttpRequestMessage AuthorizationFilter AuthenticationFilter HttpResponseMessage HttpRequestMessage Parameters 

Action pipeline 51 AuthorizationFilter HttpResponseMessage HttpActionContext AuthorizationFilter HttpActionBinding AuthorizationFilter ActionFilter HttpResponseMessage action arguments Action method object HttpRequestMessage IHttpActionResult AuthorizationFilter AuthenticationFilter HttpResponseMessage HttpRequestMessage Parameters 

Action pipeline 52 AuthorizationFilter HttpResponseMessage HttpActionContext AuthorizationFilter HttpActionBinding AuthorizationFilter ActionFilter HttpResponseMessage action arguments Action method ResultConverter object HttpResponseMessage HttpRequestMessage IHttpActionResult AuthorizationFilter AuthenticationFilter HttpResponseMessage HttpRequestMessage Parameters 

Action pipeline 53 AuthorizationFilter HttpResponseMessage HttpActionContext AuthorizationFilter HttpActionBinding AuthorizationFilter ActionFilter HttpResponseMessage action arguments Action method ResultConverter object HttpResponseMessage HttpRequestMessage IHttpActionResult AuthorizationFilter AuthenticationFilter HttpResponseMessage HttpRequestMessage Parameters 

IHttpActionResult • New in v2 • Just an async factory for HttpResponseMessage • Similar to ActionResult in MVC • Many concrete implementations: JsonResult, OkResult, RedirectResult • Many ApiController protected methods for creating them • Used for • Unit testing • Delayed message construction 54 public interface IHttpActionResult { Task ExecuteAsync(CancellationToken cancellationToken); } 

Authorization and action filters 55 public interface IActionFilter : IFilter { Task ExecuteActionFilterAsync( HttpActionContext actionContext, CancellationToken cancellationToken, Func> continuation); } public interface IAuthorizationFilter : IFilter { /* identical */ } 

Authentication filters - AuthenticateAsync 56 public class BasicAuthenticationFilter : IAuthenticationFilter { public async Task AuthenticateAsync(HttpAuthenticationContext context, CancellationToken cancellationToken) { var req = context.Request; if (req.HasAuthorizationHeaderWithBasicScheme()) { var principal = await req.TryGetPrincipalFromBasicCredentialsUsing(_validator); if (principal != null) { context.Principal = principal; } else { context.ErrorResult = new UnauthorizedResult( new AuthenticationHeaderValue[0], context.Request); } } } } 

Authentication filters - ChallengeAsync 57 public class BasicAuthenticationFilter : IAuthenticationFilter { public Task ChallengeAsync(HttpAuthenticationChallengeContext context, CancellationToken cancellationToken) { context.Result = new ActionResultDelegate(context.Result, async (ct, next) => { var res = await next.ExecuteAsync(ct); if (res.StatusCode == HttpStatusCode.Unauthorized) { res.Headers.WwwAuthenticate.Add(new AuthenticationHeaderValue("Basic", _realm)); } return res; }); return Task.FromResult(null); } } 

The "Content-Type" header field indicates the media type of the associated representation The indicated media type defines both the data format and how that data is intended to be processed by a recipient In Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content (bolds are mine) • Examples • text/plain, text/html, application/json, application/xml • application/hal+json, application/vnd.collection+json • application/vnd.github+json • See http://www.iana.org/assignments/media-types 58 

MediaTypeFormatter Media Type Formatters 59 HttpRequestMessage Request URI Headers Body Content-Type: media-type stream MediaTypeFormatter CLR Object 

MediaTypeFormatter • Examples • JsonMediaTypeFormatter • XmlMediaTypeFormatter • FormUrlEncodedMediaTypeFormatter • MediaTypeFormatter is selected based on • The content media type and the action’s parameter CLR type • The action’s return CLR type and request info (e.g. Accept header) • Can be explicitly define when producing a response 60 Request.CreateResponse(HttpStatusCode.OK, new {msg = "hello"}, new JsonMediaTypeFormatter()); 

Result conversion • Object returned by the action  HttpResponseMessage • If IHttpActionResult – just calls ExecuteAsync • Otherwise – uses a ActionResultConverter • IActionResultConverter interface • HttpResponseMessage Convert( HttpControllerContext controllerContext, object actionResult); • Implementations • ResponseMessageResultConverter • ValueResultConverter • VoidResultConverter 61 

ValueResultConverter • Uses a MediaTypeFormatter to convert CLR object  byte sequence • The MediaTypeFormatter is chosen based on • The CLR object type • The request message, namely • The Accept header • The request URI • Server-driven content negotiation 62 

Parameter binding • Handled by HttpParameterBinding derived classes • ModelBinderParameterBinding • Based on model binders and value providers (similar to ASP.NET MVC) • Used to bind from request URI • Related to FromUriAttribute • Multiple parameters • Default for simple types • FormatterParameterBinding • Based on the MediaTypeFormatter concept • Used to bind from request body • Related to FromBodyAttribute • One parameter only • Default for complex types 63 

Custom parameter binding 64 public class IPAddressParameterBinding : HttpParameterBinding { public override Task ExecuteBindingAsync(ModelMetadataProvider metadataProvider, HttpActionContext actionContext, CancellationToken cancellationToken) { var request = actionContext.Request; var ipString = GetClientIpAddressFrom(request); SetValue(actionContext, IPAddress.Parse(ipString)); return Task.FromResult(null); } public static Func Rule(Func getip) { return prm => prm.ParameterType == typeof (IPAddress) ? new IpAddressParameterBinding(prm, getip) : null; } } config.ParameterBindingRules.Add( IpAddressParameterBinding.Rule(req => req.GetOwinContext().Request.RemoteIpAddress)) 

Conclusions and final remarks • Layered runtime architecture • Hosting Adaptation • Message Handling Pipeline • Controller Layer • HTTP messages are first-class using the new class model • Multiple extensibility points 65 

References • “Use the source, Luke” git clone https://git01.codeplex.com/aspnetwebstack git clone https://git01.codeplex.com/katanaproject • G. Block, P. Cibraro, P. Félix, H. Dierking & D. Miller Designing Evolvable Web APIs with ASP.NET • To be published by O’Reilly in 2014 • Preview available at O’Reilly Atlas - http://chimera.labs.oreilly.com/books/1234000001708 • Samples at https://github.com/pmhsfelix 66