Adding the System.Net.Http Assembly

Later in the chapter, I will be using the System.Net.Http.HttpClient class that is defined in the System.Net.Http assembly. The assembly isn’t added to ASP.NET projects by default, so select the SimpleApp project in the Solution Explorer and then select Add Reference from the Visual Studio Project menu; then locate the System.Net.Http assembly in the Assemblies Framework section and check the box next to it, as shown in Figure 5-1. Click the Add button to add the assembly reference and close the dialog box.

Understanding Handlers in the Request Life Cycle

A common source of confusion when working with the ASP.NET platform is the difference between modules and handlers, so it is important I explain the role of each component before digging into the details of how handlers work.

The best way to understand each component is within the scope of the request life cycle. As I explained in Chapter 4, modules have two roles in request handling. They can be used flor diagnosis and debugging, or they can provide services used by other components. The modules I created in Chapter 4 fall into the diagnosis category: They added fragments of HTML to the response that provided insight into how the request was processed. By contrast, most of the built-in modules that come with ASP.NET provide services, such as caching, security, or the management of state data. As I explained in Chapter 1, these are the services that you consume within MVC framework controllers and views, as shown in Figure 5-2.

This figure is a refinement of one I showed you in Chapter 1, expanded to show more details about the ASP.NET components and request life cycle. As the figure illustrates, modules are instantiated at the start of the request handling process, and they set up services that are consumed through the ASP.NET context objects by the MVC framework controller and view in order to generate the response that will be sent to the client.

In Figure 5-1, I have shown the MVC framework programmer’s view of the controller and view, but, as you may have guessed, the MVC functionality is integrated into the ASP.NET platform through a handler, as shown in Figure 5-3.

The first thing to notice is that there are multiple modules for each request but only one handler. The reason I am being so emphatic about the relationship between these components is because I want to be clear about they mesh with the request life-cycle events: The modules are created as soon as the request life cycle begins, but the selection and creation of the handler are built right into the life cycle, as shown in Figure 5-4.

The MapRequestHandler event is triggered before the ASP.NET platform locates the handler that will generate the content for the request, the process for which I describe in the “Creating a Handler” section later in this chapter. The PostMapRequestHandler event is triggered once the handler has been identified and instantiated. However, the handler isn’t asked to generate the content until the PreRequestHandlerExecute event is triggered, which means that modules have an opportunity to respond to the handler selection and provide services that are unique to that handler, as shown in the figure. You’ll see how this all works in the “Targeting a Specific Handler” section later in this chapter. (Modules can also override the handler selection process, as described in Chapter 6.)

Understanding Handlers

Handlers are classes that implement the System.Web.IHttpHandler interface, which defines the two methods that I have described in Table 5-3.

The ProcessRequest method is passed an HttpContext object, which can be used to inspect the request and the state of the application through the properties I described in Chapter 3.

Handlers can generate any kind of content that can be delivered over HTTP, and the ASP.NET platform does not impose any constraints on how the content is created. ASP.NET includes a set of default handlers that support the Web Forms, the MVC framework, SignalR, and Web API technology stacks, but custom handlers can be used to support new kinds of applications or data.

Handlers and the Life-Cycle Events

In Figure 5-3, I explained that handler selection and content generation are part of the request life cycle, but I describe the significant events from the perspective of modules. Table 5-4 describes the key life-cycle events from the perspective of the handler.

The life cycle of a handler is interwoven with the request and module life cycles. This may seem over complicated, but it provides for flexible interactions between handlers and modules (or the global application class if that’s where you have defined your event handlers). All of this will start to make more sense as you see some examples of handlers and the way they can be used.

The MapRequestHandler and PostMapRequestHandler events are different from the other pairs of events in the life cycle. Normally, the first event in a pair is a request for a module to provide a service, and the second event signals that phase of the life cycle is complete. So, for example, the AcquireRequestState event is a request for modules that handle state data to associate data with the request, and the PostAcquireRequestState event signals that all of the modules that handled the first event have finished responding.

The MapRequestHandler event isn’t an invitation for a module to supply a handler for a request; that’s a task that ASP.NET handles itself, and the event just signals that the selection is about to be made (a process I describe in the next section). The PostMapRequestHandler event signals that the handler has been selected, which allows modules to respond to the handler choice—generally by setting up services or data specific to the chosen handler.

The handler’s ProcessRequest method is called between the PreRequestHandlerExecute and PostRequestHandlerExecute events. Modules can use these events as the last opportunity to manipulate the context objects before the content is generated by the handler and the first opportunity to manipulate the response once the handler is done.

Registering a Handler Using URL Routing

Handlers must be registered before they can be used to generate content for requests, and there are two ways in which this can be done. The firs technique for registering a handler is to use the routing system. In Listing 5-4, you can see how I have edited the RouteConfig.cs file to set up a route that matches URLs that start with /handler to my DayOfWeekHandler class.

Listing 5-4.  Setting Up a Route for a Custom Handler in the RouteConfig.cs File

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using System.Web.Routing;
using SimpleApp.Infrastructure;
 
namespace SimpleApp {
    public class RouteConfig {
        public static void RegisterRoutes(RouteCollection routes) {
            routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
 
            routes.Add(new Route("handler/{*path}",
                new CustomRouteHandler {HandlerType = typeof(DayOfWeekHandler)}));
 
            routes.MapRoute(
                name: "Default",
                url: "{controller}/{action}/{id}",
                defaults: new { controller = "Home", action = "Index",
                    id = UrlParameter.Optional }
            );
        }
    }
 
    class CustomRouteHandler : IRouteHandler {
 
        public Type HandlerType { get; set; }
             
        public IHttpHandler GetHttpHandler(RequestContext requestContext) {
    return (IHttpHandler)Activator.CreateInstance(HandlerType);
        }
    }
}

The RouteCollection.Add method creates a route and associates it with an implementation of the IRouteHandler interface, which defines the GetHttpHandler method. This method is responsible for returning an instance of the IHttpHandler interface that will be used to generate content for the request. My implementation of IRouteHandler is configured with a C# type that I instantiate using the System.Activator class. This allows me to tie a specific custom handler to a URL pattern, like this:

...
routes.Add(new Route("handler/{*path}",
    new CustomRouteHandler {HandlerType = typeof(DayOfWeekHandler)}));
...

Registering a Handler Using the Configuration File

Using the routing system to set up custom handlers is workable, but it isn’t the approach that I use in my own projects. Instead, I use the Web.config file to register my handlers, in part because not all ASP.NET projects use the routing system (and, in part, out of habit because I have been writing web applications for a long time, and the routing system is a relatively new addition to ASP.NET). Listing 5-5 shows the additions I made to the Web.config file to register my custom handler.

Listing 5-5.  Registering a Handler in the Web.config File

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
     <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
  </appSettings>
  <system.web>
    <compilation debug="true" targetFramework="4.5.1" />
    <httpRuntime targetFramework="4.5.1" />
  </system.web>
  <system.webServer>
    <modules>
      <!--<add name="Timer" type="SimpleApp.Infrastructure.TimerModule"/>-->
      <!--<add name="Total" type="SimpleApp.Infrastructure.TotalTimeModule"/>-->
    </modules>
    <handlers>
      <add name="DayJSON" path="/handler/*.json" verb="GET"
              type="SimpleApp.Infrastructure.DayOfWeekHandler"/>
      <add name="DayHTML" path="/handler/day.html" verb="*"
              type="SimpleApp.Infrastructure.DayOfWeekHandler"/>
    </handlers>
  </system.webServer>
</configuration>

Handlers are registered in the system.webServer/handlers section of the Web.config file, through the use of the add element, which defines the attributes shown in Table 5-5. (The set of handlers is a configuration collection, which I explain in Chapter 9 when I describe the ASP.NET configuration system in detail.)

You can be as general or as specific as you want when you register a custom handler, and you can create any number of configuration entries for each handler. I created two entries in the Web.config file to set up the new handler. This isn’t essential for such a simple handler, but I wanted to demonstrate that a handler can be set up to support multiple types of request. The first entry registers the custom handler to deal with requests with URLs that start with /handlerand have the JSON extension and are made using the GET method. The second entry registers the same handler class, but only for requests made using any HTTP method for the /handler/day.html URL.

There is one more configuration step, and that’s to stop the URL routing feature from intercepting requests that I want to go to my custom handler. The default routing configuration that Visual Studio adds to ASP.NET projects assumes that all incoming requests will routed and sends a 404 – Not Found error to the client when a request can’t be matched to a route. To avoid this problem, I have edited the App_Start/RouteConfig.cs file to tell the routing system to ignore any requests intended for my custom handler, as shown in Listing 5-6.

Listing 5-6.  Ignoring Requests for the Custom handler in the RouteConfig.cs File

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using System.Web.Routing;
using SimpleApp.Infrastructure;
 
namespace SimpleApp {
    public class RouteConfig {
        public static void RegisterRoutes(RouteCollection routes) {
            routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
 
            //routes.Add(new Route("handler/{*path}",
            //    new CustomRouteHandler {HandlerType = typeof(DayOfWeekHandler)}));
 
            routes.IgnoreRoute("handler/{*path}");
 
            routes.MapRoute(
                name: "Default",
                url: "{controller}/{action}/{id}",
                defaults: new { controller = "Home", action = "Index",
                    id = UrlParameter.Optional }
            );
        }
    }
 
    class CustomRouteHandler : IRouteHandler {
 
        public Type HandlerType { get; set; }
        public IHttpHandler GetHttpHandler(RequestContext requestContext) {
            return (IHttpHandler)Activator.CreateInstance(HandlerType);
        }
    }
}

The RouteCollection.IgnoreRoute method tells the routing system to ignore a URL pattern. In the listing, I used the IgnoreRoute method to exclude any URL whose first segment is /handler. When a URL pattern is excluded, the routing system won’t try to match routes for it or generate an error when there is no route available, allowing the ASP.NET platform to locate a handler from the Web.config file.

Testing the Handler

To test the custom handler, start the application and request the /handler/day.html URL. This request will select the DayOfWeekHandler to generate the content, and the handler will return an HTML fragment, as shown in Figure 5-5.

The custom handler will also generate a JSON response. To test this, you can request any URL that starts with /handler and ends with .json, such as /handler/day.json. Internet Explorer won’t display JSON content in the browser window, and you will be prompted to open a file that contains the following content:

{"day": "Tuesday"}

Targeting a Specific Handler

The module that I defined in Listing 5-9 adds data to the Items collection for every request, whether or not the handler that is selected will use it. That doesn’t present a problem when the data is as easy to create as the current date and time, but it becomes a problem if there is significant time or expense required to obtain or generate the data. As an example, you won’t want to query a database in the module to obtain data that will be ignored by most handlers. To avoid this, you can respond to the PostMapRequestHandler life-cycle event in the module and add data to the Items collection only if the handler that ASP.NET has selected is one that will consume the data. In Listing 5-12, I have modified the DayModule so that it will add data to the collection only when DayOfWeekHandler is selected to generate content for the request.

Listing 5-12.  Targeting a Specific Handler in the DayModule.cs File

using System;
using System.Web;
 
namespace SimpleApp.Infrastructure {
    public class DayModule : IHttpModule {
 
        public void Init(HttpApplication app) {
            app.PostMapRequestHandler += (src, args) => {
                if (app.Context.Handler is DayOfWeekHandler) {
                    app.Context.Items["DayModule_Time"] = DateTime.Now;
                }
            };
        }
 
        public void Dispose() {
            // nothing to do
        }
    }
}

The module now handles the PostMapRequestHandler event, which is triggered after the handler has been selected to generate content for the request and uses the HttpContext.Handler property to check the type of the selected handler. The module adds a DateTime value to the Items collection if the handler is an instance of DayWeekHandler, but not otherwise.

namespace SimpleApp.Infrastructure {
 
    public interface IRequiresDate {
        // this interface is declarative and defines no members
    }
}

...
namespace SimpleApp.Infrastructure {
    public class DayOfWeekHandler : IHttpHandler, IRequiresDate{
...

using System;
using System.Web;
 
namespace SimpleApp.Infrastructure {
    public class DayModule : IHttpModule {
 
        public void Init(HttpApplication app) {
            app.PostMapRequestHandler += (src, args) => {
                if (app.Context.Handler is IRequiresDate) {
                    app.Context.Items["DayModule_Time"] = DateTime.Now;
                }
            };
        }
 
        public void Dispose() {
            // nothing to do
        }
    }
}

Controlling Handler Instantiation

The simplest kind of handler factory is one that controls the way that custom handlers are instantiated. The best example I have seen of this kind of factory is the one that handles requests for Web Form files, which involves a complex parsing and compilation process to generate a class that can return a response to the browser. This is similar to the process that the MVC framework uses for Razor views but is implemented using a handler factory.

Needing to generate and compile handler classes is pretty unusual; the most common kind of handler that requires a factory is one that requires some kind of initialization or a constructor argument for resource configuration, such as a database connection or a license key.

To keep the example focused on the handler factory, I am going to demonstrate how to create instances of a handler that requires a constructor argument—something that the default handler can’t resolve. I added a class file called CounterHandler.cs to the Infrastructure folder and used it to define the handler shown in Listing 5-16.

Listing 5-16.  The Content of the CounterHandler.cs File

using System.Web;
 
namespace SimpleApp.Infrastructure {
    public class CounterHandler : IHttpHandler {
        private int handlerCounter;
 
        public CounterHandler(int counter) {
            handlerCounter = counter;
        }
 
        public void ProcessRequest(HttpContext context) {
            context.Response.ContentType = "text/plain";
            context.Response.Write(string.Format("The counter value is {0}",
                handlerCounter));
        }
 
        public bool IsReusable {
            get { return false; }
        }
    }
}

This handler takes an int constructor argument, which prevents it from being instantiated by the built-in handler. In Listing 5-17, you can see the contents of the CounterHandlerFactory.cs file, which I added to the Infrastructure folder to define a handler factory that can provide the CounterHandler with the constructor argument it needs.

Listing 5-17.  The Contents of the CounterHandlerFactory.cs File

using System.Web;
 
namespace SimpleApp.Infrastructure {
    public class CounterHandlerFactory : IHttpHandlerFactory {
        private int counter = 0;
 
        public IHttpHandler GetHandler(HttpContext context, string verb,
                string url, string path) {
            return new CounterHandler(++counter);
        }
        public void ReleaseHandler(IHttpHandler handler) {
            // do nothing - handlers are not reused
        }
    }
}

ASP.NET doesn’t care how the GetHandler method provides it with a handler, just as long as it does. In this simple example, the handler factory increments a counter and uses it as the constructor argument to create a new instance of CounterHandler.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
     <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
  </appSettings>
  <system.web>
    <compilation debug="true" targetFramework="4.5.1" />
    <httpRuntime targetFramework="4.5.1" />
  </system.web>
  <system.webServer>
    <modules>
      <!--<add name="Timer" type="SimpleApp.Infrastructure.TimerModule"/>-->
      <!--<add name="Total" type="SimpleApp.Infrastructure.TotalTimeModule"/>-->
      <add name="DayPrep" type="SimpleApp.Infrastructure.DayModule"/>
    </modules>
    <handlers>
      <add name="DayJSON" path="/handler/*.json" verb="GET"
           type="SimpleApp.Infrastructure.DayOfWeekHandler"/>
      <add name="DayHTML" path="/handler/day.html" verb="*"
           type="SimpleApp.Infrastructure.DayOfWeekHandler"/>
      <add name="SiteLength" path="/handler/site" verb="*"
           type="SimpleApp.Infrastructure.SiteLengthHandler"/>
      <add name="CounterFactory" path="/handler/counter" verb="*"
          type="SimpleApp.Infrastructure.CounterHandlerFactory"/>
    </handlers>
  </system.webServer>
</configuration>

Selecting Handlers Dynamically

The Web.config file can be used to match handlers to combinations of HTTP method and URL, but that is the limit of the built-in support for matching handlers to requests. For more complex selections, a handler factory is required. Listing 5-19 shows how I have changed the CounterHandlerFactory to instantiate different handlers based on the browser that makes the request.

Listing 5-19.  Dynamically Selecting Handlers Based on Request Details in the CounterHandlerFactory.cs File

using System.Web;
 
namespace SimpleApp.Infrastructure {
    public class CounterHandlerFactory : IHttpHandlerFactory {
        private int counter = 0;
 
        public IHttpHandler GetHandler(HttpContext context, string verb,
                string url, string path) {
            if (context.Request.UserAgent.Contains("Chrome")) {
                return new SiteLengthHandler();
            } else {
                return new CounterHandler(++counter);
            }
        }
        public void ReleaseHandler(IHttpHandler handler) {
            // do nothing - handlers are not reused
        }
    }
}

As I explained earlier, ASP.NET doesn’t care how the handler factory creates handlers, but neither does it care which handlers are created. In this case, I use the context objects to get the user agent string that the browser sends as part of the HTTP request and select the SiteLengthHandler for requests made by the Google Chrome browser users and the CounterHandler otherwise. (I created the SiteLengthHandler in the “Creating Asynchronous Handlers” section earlier in this chapter.) You can see the effect of requesting the /handler/counter URL in Internet Explorer and Chrome in Figure 5-8.

Reusing Handlers

The IHttpHandler interface defines the IsReusable property, which allows handlers to indicate that they can be used to generate content for multiple requests in sequence. The built-in handler factory ignores the IsReuseable property value and always creates new handlers for each request.

The main situation where reusing handlers is attractive is when they require significant time or resources to create, typically because they need to load or generate substantial amounts of data before they are able to generate any content. Listing 5-20 shows how I have modified the CounterHandler so that it can be reused, but only for three requests. This isn’t a common scenario, but I want to emphasize the way that handler instances can control their own reuse through the IsReusable property.

Listing 5-20.  Creating a Reusable Handler in the CounterHandler.cs File

using System.Web;
 
namespace SimpleApp.Infrastructure {
    public class CounterHandler : IHttpHandler {
        private int handlerCounter;
        private int requestCounter = 0;
 
        public CounterHandler(int counter) {
            handlerCounter = counter;
        }
 
        public void ProcessRequest(HttpContext context) {
            requestCounter++;
            context.Response.ContentType = "text/plain";
            context.Response.Write(
                string.Format("The counter value is {0} (Request {1} of 3)",
                    handlerCounter, requestCounter));
        }
 
        public bool IsReusable {
            get { return requestCounter < 2; }
        }
    }
}

The handler keeps track of the number of requests for which it has generated content and uses this value as the basis for the IsReusable property. Listing 5-21 shows the changes I have made to the CounterHandlerFactory to support reusable handlers.

Listing 5-21.  Reusing Handlers in the CounterHandlerFactory.cs File

using System.Collections.Concurrent;
using System.Web;
 
namespace SimpleApp.Infrastructure {
    public class CounterHandlerFactory : IHttpHandlerFactory {
        private int counter = 0;
        private int handlerMaxCount = 3;
        private int handlerCount = 0;
        private BlockingCollection<CounterHandler> pool
            = new BlockingCollection<CounterHandler>();
         
        public IHttpHandler GetHandler(HttpContext context, string verb,
                string url, string path) {
 
                CounterHandler handler;
                if (!pool.TryTake(out handler)) {
                    if (handlerCount < handlerMaxCount) {
                        handlerCount++;
                        handler = new CounterHandler(++counter);
                        pool.Add(handler);
                    } else {
                        handler = pool.Take();
                    }
                }
                return handler;
        }
        public void ReleaseHandler(IHttpHandler handler) {
            if (handler.IsReusable) {
                pool.Add((CounterHandler)handler);
            } else {
                handlerCount--;
            }
        }
    }
}

The handler factory uses a BlockingCollection to maintain a pool of handlers, each of which will be used for three requests. The pool contains a maximum of three handlers, and requests are queued up until a handler is available.