In this chapter, I conclude the coverage of the parameter and model binding processes by explaining how media type formatters can be used to deserialize complex types from the request body. I show you how to perform deserialization with a custom media type formatter and then detail how the built-in formatters work, including how to send data in the required format from the client. I finish this chapter by showing you how to replace the class that is responsible for integrating the behavior I have been describing since Chapter 15 with a custom implementation. Table 17-1 summarizes this chapter.

Preparing the Example Project

I am going to continue using the ExampleApp project I have been working with throughout this part of the book, but I need to make some preparatory changes for this chapter. First I need to simplify the Numbers class so that it has a parameterless constructor and settable properties—changes that are required so that I can demonstrate the default behavior. Listing 17-1 shows the changes I made, which include removing the ModelBinder and TypeConverter attributes that I applied in Chapter 16. I have left the constructor with parameters in place so that I can demonstrate dealing with objects that require special handling.

Listing 17-1. Simplifying the Class in the BindingModels.cs File

namespace ExampleApp.Models {

    public class Numbers {

        public Numbers() { /* do nothing */ }

        public Numbers(int first, int second) {
            First = first; Second = second;
        }

        public int First { get; set; }
        public int Second { get; set; }
        public Operation Op { get; set; }
        public string Accept { get; set; }
    }

    public class Operation {
        public bool Add { get; set; }
        public bool Double { get; set; }
    }
}

I need to remove the model binding configuration from the WebApiConfig.cs file. The features that I will describe in this chapter do not use value providers or model binders. Listing 17-2 shows the revised configuration file.

Listing 17-2. Simplifying the WebApiConfig.cs File

using System.Web.Http;
using System.Web.Http.ModelBinding;
using System.Web.Http.ModelBinding.Binders;
using System.Web.Http.ValueProviders;
using ExampleApp.Infrastructure;
using ExampleApp.Models;

namespace ExampleApp {
    public static class WebApiConfig {
        public static void Register(HttpConfiguration config) {

            config.DependencyResolver = new NinjectResolver();

            config.MapHttpAttributeRoutes();

            config.Routes.MapHttpRoute(
                name: "Binding Example Route",
                routeTemplate: "api/{controller}/{action}/{first}/{second}"
            );

            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );

            config.Services.Add(typeof(ValueProviderFactory),
                new HeaderValueProviderFactory());

            config.Services.Insert(typeof(ModelBinderProvider), 0,
                new SimpleModelBinderProvider(typeof(Numbers), new NumbersBinder()));
        }
    }
}

The final change is to the bindings.js file so that the jQuery Ajax request uses standard data encoding and uses the POST verb. Listing 17-3 shows the changes.

Listing 17-3. Changing the Request Verb and Data Format in the bindings.js File

var viewModel = ko.observable({
    first: 2, second: 5, "op.add": true, "op.double": true
});
var response = ko.observable("Ready");
var gotError = ko.observable(false);

var sendRequest = function (requestType) {
    $.ajax("/api/bindings/sumnumbers", {
        type: "POST",
        data: viewModel(),
        success: function (data) {
            gotError(false);
            response("Total: " + data);
        },
        error: function (jqXHR) {
            gotError(true);
            response(jqXHR.status + " (" + jqXHR.statusText + ")");
        }
    });
};

$(document).ready(function () {
    ko.applyBindings();
});

I also want to change the SumNumbers action method in the Bindings controller so that it returns an int result. I changed the result to a string so that I could include the value of the Accept header, but I only need to report the result of the calculation performed by the SumNumbers action method in this chapter. Listing 17-4 shows the change to the action method.

Listing 17-4. Changing the Action Method Result in the BindingsController.cs File

using System.Web.Http;
using System.Web.Http.ModelBinding;
using ExampleApp.Models;
using ExampleApp.Infrastructure;

namespace ExampleApp.Controllers {
    public class BindingsController : ApiController {
        private IRepository repo;

        public BindingsController(IRepository repoArg) {
            repo = repoArg;
        }

        [HttpGet]
        [HttpPost]
        public int SumNumbers(Numbers numbers) {
            var result = numbers.Op.Add ? numbers.First + numbers.Second
                : numbers.First - numbers.Second;
            return numbers.Op.Double ? result * 2 : result;
        }
    }
}

Testing the Application

To test the changes, start the application and use the browser to navigate to the /Home/Bindings URL. When you click the Send Request button, the client will display the result, which will be twice the sum of the values in the input elements, as shown in Figure 17-1.

Creating a Custom Media Type Formatter

By default, Web API assumes that any complex type parameter will be obtained from the request body and uses a media type formatter to try to get and bind a value. I introduced media type formatters in Chapter 12 and described the built-in JSON and XML media type formatters in Chapter 13, but my focus in both chapters was on using them to serialize data from action method results so that it could be sent to the client. Media type formatters are also able to deserialize data and use it to create instances of the classes required to invoke an action method.

In Chapter 12, I created the ProductFormatter class, which was responsible for formatting a Product object into a string like this:

1,Kayak,275.0

The three comma-separated values represented the ProductId, Name, and Price properties defined by the Product model object. In this section, I am going to return to this data format and create a media type formatter that can deserialize it to create Numbers objects. Table 17-2 puts creating a custom media type formatter to deserialize data into context.

Preparing the Client

The first change I need to make is to change the Ajax request that jQuery sends so that the data is in the expected format and that the Content-Type header is correctly set, as shown in Listing 17-5.

Listing 17-5. Changing the Ajax Request in the bindings.js File

var viewModel = ko.observable({
    first: 2, second: 5, add: true, double: true
});
var response = ko.observable("Ready");
var gotError = ko.observable(false);

var sendRequest = function (requestType) {
    $.ajax("/api/bindings/sumnumbers", {
        type: "POST",
        contentType: "application/x.product",
        data: [viewModel().first, viewModel().second, viewModel().add,
               viewModel().double].join(),
        success: function (data) {
            gotError(false);
            response("Total: " + data);
        },
        error: function (jqXHR) {
            gotError(true);
            response(jqXHR.status + " (" + jqXHR.statusText + ")");
        }
    });
};

$(document).ready(function () {
    ko.applyBindings();
});

I have used the contentType setting to specify that the content is in my custom application/x.product encoding (the MIME type I used in Chapter 12) and created a formatted string for the data setting by creating an array with the values from the view model and by calling the join method, which combines the values with a comma separator. If you start the application and send a request, you will see the following URL in the F12 tools:

/api/bindings/sumnumbers

It has a payload of the following:

2,5,true,true

The web service will report an error because I have not implemented the deserialization support.

Creating the Media Type Formatter

Now that I have a request I can process, it is time to create the custom media type formatter. I added a class file called XNumbersFormatter.cs to the Infrastructure folder and used it to create the media type formatter shown in Listing 17-6.

Listing 17-6. The Contents of the XNumbersFormatter.cs File

using System;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Formatting;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using ExampleApp.Models;

namespace ExampleApp.Infrastructure {
    public class XNumbersFormatter : MediaTypeFormatter {
        long bufferSize = 256;

        public XNumbersFormatter() {
            SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/x.product"));
        }

        public override bool CanWriteType(Type type) {
            return false;
        }

        public override bool CanReadType(Type type) {
            return type == typeof(Numbers);
        }

        public async override Task<object> ReadFromStreamAsync(Type type,
            Stream readStream, HttpContent content, IFormatterLogger formatterLogger) {

            byte[] buffer = new byte[Math.Min(content.Headers.ContentLength.Value,
                bufferSize)];
            string[] items = Encoding.Default.GetString(buffer, 0,
                await readStream.ReadAsync(buffer, 0, buffer.Length)).Split(',', '='),

            if (items.Length == 4) {
                return new Numbers(
                    GetValue<int>("First", items[0], formatterLogger),
                    GetValue<int>("Second", items[1], formatterLogger)) {

                    Op = new Operation {
                        Add = GetValue<bool>("Add", items[2], formatterLogger),
                        Double = GetValue<bool>("Double", items[3], formatterLogger)
                    }
                };
            } else {
                formatterLogger.LogError("", "Wrong Number of Items");
                return null;
            }
        }

        private T GetValue<T>(string name, string value, IFormatterLogger logger) {
            T result = default(T);
            try {
                result = (T)System.Convert.ChangeType(value, typeof(T));
            } catch {
                logger.LogError(name, "Cannot Parse Value");
            }
            return result;
        }
    }
}

This formatter binds instances of the Numbers class for requests whose Content-Type header is application/x.product. In the sections that follow, I’ll break down each part of the class and explain how it works.

Defining the Formatter Structure

The MediaTypeFormatter class is abstract and requires only the CanWriteType and CanReadType methods to be implemented—but there are two other steps required to create a working media type formatter. First you need to add the MIME type that you want to support to the SupportedMediaTypes collection in the class constructor, as follows:

...
public XNumbersFormatter() {
    SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/x.product"));
}
...

For my implementations of the CanWriteType and CanReadType methods, I want to tell Web API that I am not willing to serialize any data and that I can deserialize only Numbers objects.

...
public override bool CanWriteType(Type type) {
    return false;
}

public override bool CanReadType(Type type) {
    return type == typeof(Numbers);
}
...

Getting the Request Data

Media type formatters that deserialize data override the ReadFromStreamAsync method, and that is where the bulk of the work is done in the XNumbersFormatter class. The ReadFromStreamAsync method is passed arguments of the types described in Table 17-3 and is responsible for using them to instantiate an object.

The HttpContent class provides information about the request and provides methods that can be used to read the request body, but the ReadFromStreamAsync method is required to read data from the Stream object it receives as an argument. This means the value of the HttpContent object is its Headers property, which returns an instance of the HttpContentHeaders class. The HttpContentHeaders class is derived from HttpHeaders and adds convenience properties for content-related headers, as described in Table 17-4. (The HttpContentHeaders class contains properties that are used in responses and requests. I have included the request headers only in the table.)

For my purposes, it is the ContentLength property that is most useful because it tells me how much data I need to read from the Stream argument to the ReadFromStreamAsync method. Here is the code that reads the body of the request and converts it into an array of strings:

...
byte[] buffer = new byte[Math.Min(content.Headers.ContentLength.Value, bufferSize)];
string[] items = Encoding.Default.GetString(buffer, 0,
    await readStream.ReadAsync(buffer, 0, buffer.Length)).Split(',', '='),
...

These statements follow three important rules that you should follow when writing a custom media type formatter:

• Don’t use the convenience methods to read basic types.
• Limit the amount of data you read.
• Read data asynchronously.

A simple but effective denial-of-service attack is for a client to send an HTTP server misleading information in the Content-Length header, either to cause an error or to try to get the server to exhaust its memory by reading enormous amounts of data. A custom media type formatter requires care because the content is read and processed by your code, rather than that of the ASP.NET Framework as is the case in an MVC application.

The first precaution you should take is to avoid using the convenience methods provided by the stream and reader classes in the System.IO namespace. Using a ReadLine or ReadString method would allow me to simplify my media type formatter, but these methods just keep reading data from the underlying stream until they get the data they expect. Instead, you should read the content into a byte[] buffer directly from the stream.

The second precaution you should take is to limit the amount of data you read from the stream. In Listing 17-6, I defined a maximum buffer size of 256 bytes, which is enough to represent my Numbers class. When I create the byte array, I set the size of the array using the Content-Length header only if it is smaller than 256 (and I ignore negative Content-Length headers, which are sent to generate an error, although this is largely habit.

...
byte[] buffer = new byte[Math.Min(content.Headers.ContentLength.Value, bufferSize)];
...

The final rule you should follow is to read data asynchronously from the Stream to maximize the request throughput of the web service. I used the Stream.ReadAsync method to read the request body.

...
string[] items = Encoding.Default.GetString(buffer, 0,
    await readStream.ReadAsync(buffer, 0, buffer.Length)).Split(',', '='),
...

I have used the await keyword for my read operation, and that is why I have added the async keyword to the ReadFromStreamAsync method.

Creating the Model Object

Once I have the data from the request body, I can use it to create an instance of the Numbers class, which is handled by this statement:

...
return new Numbers(
    GetValue<int>("First", items[0], formatterLogger),
    GetValue<int>("Second", items[1], formatterLogger)) {

    Op = new Operation {
        Add = GetValue<bool>("Add", items[2], formatterLogger),
        Double = GetValue<bool>("Double", items[3], formatterLogger)
    }
};
...

I have used the Numbers constructor that takes parameters, just to show that you can instantiate objects in any way you need when writing a custom media type formatter. I get the values I require for the constructor parameters and the Operation properties through a method called GetValue, which I defined to let me take advantage of C# generic types so that I can easily convert string values to different types.

...
private T GetValue<T>(string name, string value, IFormatterLogger logger) {
    T result = default(T);
    try {
        result = (T)System.Convert.ChangeType(value, typeof(T));
    } catch {
        logger.LogError(name, "Cannot Parse Value");
    }
    return result;
}
...

The caller specifies the type that is required using the generic type parameter T, and I use the System.Convert.ChangeType method to perform the conversion. The important part of the GetValue method is the use of the IFormatterLogger parameter object, which is used to record any problems processing the request data to create the model object. The default implementation of the IFormatterLogger interface adds errors to the model state, which is part of the model validation process I describe in Chapter 18. The IFormatterLogger interface defines the methods I have listed in Table 17-5.

In the listing, I note any problems parsing values, but I still return the default value for the required type. This will make more sense once I describe the model validation process in Chapter 18.

Registering and Testing the Media Type Formatter

Having created the custom media type formatter (and explained how it works), I can tell Web API to start using it to deserialize Numbers objects for requests that use my application/x.product format. Listing 17-7 shows the change I made to the WebApiConfig.cs file to register the XNumbersFormatter class.

Listing 17-7. Registering a Media Type Formatter in the WebApiConfig.cs File

using System.Web.Http;
using System.Web.Http.ModelBinding;
using System.Web.Http.ModelBinding.Binders;
using System.Web.Http.ValueProviders;
using ExampleApp.Infrastructure;
using ExampleApp.Models;

namespace ExampleApp {
    public static class WebApiConfig {
        public static void Register(HttpConfiguration config) {

            config.DependencyResolver = new NinjectResolver();

            // ...routing statements omitted for brevity...

            config.Services.Add(typeof(ValueProviderFactory),
                new HeaderValueProviderFactory());

            config.Services.Insert(typeof(ModelBinderProvider), 0,
                new SimpleModelBinderProvider(typeof(Numbers), new NumbersBinder()));

            config.Formatters.Add(new XNumbersFormatter());
        }
    }
}

For variety, I am going to test the custom formatter with Postman. Set the URL to http://localhost:29844/api/bindings/sumnumbers (replacing 29844 with your application’s port number), the request type to POST, and the Content-Type header to application/x.product.

Click the Raw button to specify a request body that won’t be formatted by Postman and enter the following into the text box:

100,150,true,false

Click the Send button, and Postman will send the request to the web service, which will return the following result (the previous values specified that the web service should add 100 and 150 but not double the result):

250

Using the Built-in Media Type Formatters

The default behavior for a complex type parameter is to act as though the FromBody attribute has been applied. I introduced the FromBody attribute in Chapter 14 when I showed you how to use it to force Web API to look in the request body for a value that it would otherwise try to obtain it from the URL. Behind the scenes, the FromBody attribute is used to select a media type formatter that can process the body of a request based on the MIME type. Web API comes with four built-in media type formatters enabled by default, which I have listed in Table 17-6.

When a request arrives, the MIME type in the Content-Type header selects the media type formatter that can handle that type. In the sections that follow, I explain how each formatter works and show you how to format the client request data to target them. Table 17-7 puts binding complex types with the built-in media type formatters in context.

Handling URL-Encoded Data

If you use jQuery to write your application client, then you will usually end up dealing with form-encoded data because it is the default format that jQuery uses when sending an Ajax request. As Table 17-7 shows, two media type formatters can handle the application/x-www-form-urlencoded MIME type: FormUrlEncodedMediaTypeFormatter and JQueryMvcFormUrlEncodedFormatter. I explain the relationship between them and how each of them works in the sections that follow.

Handling URL-Encoded Requests

The FormUrlEncodedMediaTypeFormatter class can bind only to an instance of the FormDataCollection class, which is defined in the System.Net.Http.Formatting namespace and which presents form-encoded data as a collection of name-value pairs.

The real value of the FormUrlEncodedMediaTypeFormatter class is that it provides a foundation for creating formatters that handle more useful types, such as the JQueryMvcFormUrlEncodedFormatter class that I describe in the next section.

I need to change the data format for the Ajax request that jQuery makes in order to target the FormUrlEncodedMediaTypeFormatter class, as shown in Listing 17-8.

Listing 17-8. Changing the Request Format in the bindings.js File

var viewModel = ko.observable({
    first: 2, second: 5, add: true, double: true
});
var response = ko.observable("Ready");
var gotError = ko.observable(false);

var sendRequest = function (requestType) {
    $.ajax("/api/bindings/sumnumbers", {
        type: "POST",
        data: viewModel(),
        success: function (data) {
            gotError(false);
            response("Total: " + data);
        },
        error: function (jqXHR) {
            gotError(true);
            response(jqXHR.status + " (" + jqXHR.statusText + ")");
        }
    });
};

$(document).ready(function () {
    ko.applyBindings();
});

The changes to the client-side code are minor because jQuery sends URL-encoded data by default. Listing 17-9 shows the change I made to the action method to receive that data using a FormDataCollection object.

Listing 17-9. Receiving Request Data in the BindingsController.cs File

using System.Web.Http;
using System.Web.Http.ModelBinding;
using ExampleApp.Models;
using ExampleApp.Infrastructure;
using System.Net.Http.Formatting;

namespace ExampleApp.Controllers {
    public class BindingsController : ApiController {
        private IRepository repo;

        public BindingsController(IRepository repoArg) {
            repo = repoArg;
        }

        [HttpGet]
        [HttpPost]
        public IHttpActionResult SumNumbers(FormDataCollection numbers) {

            int first, second;
            bool add, doubleVal;

            if (int.TryParse(numbers["first"], out first)
                && int.TryParse(numbers["second"], out second)
                && bool.TryParse(numbers["add"], out add)
                && bool.TryParse(numbers["double"], out doubleVal)) {

                int result = add ? first + second : first - second;
                return Ok(string.Format("{0}", doubleVal ? result * 2 : result));

            } else {
                return BadRequest();
            }
        }
    }
}

I have to take responsibility for converting the form data values into the types I require to do the work in the action method, which in this case means using the int.TryParse and bool.TryParse methods to convert form data values (which are expressed as string values) to int and bool types. If I receive all of the data values I need—and I can convert them to the types I need—then I perform the calculation and return the result using the Ok method, which I introduced in Chapter 11. If I don’t get the values I need, then I use the BadRequest method to send the client a 400 (Bad Request) response.

Creating Complex Types from URL-Encoded Requests

The JQueryMvcFormUrlEncodedFormatter class is derived from FormUrlEncodedMediaTypeFormatter and adds support for binding values to complex types, which is a lot more useful than working with the FormDataCollection class.

Behind the scenes, the JQueryMvcFormUrlEncodedFormatter class uses extension methods defined in the System.Web.Http.ModelBinding.FormDataCollectionExtensions class to create objects using the model binding feature that I described in Chapter 16. Unfortunately, the FormDataCollectionExtensions extension methods are written to use only the built-in media formatters and value providers, preventing the use of custom classes and limiting the range of types that can be bound from application/x-www-form-urlencoded data to classes with parameterless constructors and settable properties, arrays, lists, and key-value pairs.

Using model binders also means that the data sent by the client needs to be structured with prefixes in order to be properly processed. Listing 17-10 shows the changes I made to the view model in the bindings.js file.

Listing 17-10. Adding Prefixes to the View Model in the bindings.js File

...
var viewModel = ko.observable({
    first: 2, second: 5,
    "op.add": true, "op.double": true
});
...

If I had not prefixed add and double with op, then the media type formatter would not have assigned values to the Op and Add properties of the Numbers object it creates. Listing 17-11 shows the changes I made to the action method in the Bindings controller to use the JQueryMvcFormUrlEncodedFormatter formatter.

Listing 17-11. Changing the Action Method Parameter in the BindingsController.cs File

using System.Web.Http;
using System.Web.Http.ModelBinding;
using ExampleApp.Models;
using ExampleApp.Infrastructure;
using System.Net.Http.Formatting;

namespace ExampleApp.Controllers {
    public class BindingsController : ApiController {
        private IRepository repo;

        public BindingsController(IRepository repoArg) {
            repo = repoArg;
        }

        [HttpGet]
        [HttpPost]
        public int SumNumbers(Numbers numbers) {
            var result = numbers.Op.Add ? numbers.First + numbers.Second
                : numbers.First - numbers.Second;
            return numbers.Op.Double ? result * 2 : result;
        }
    }
}

It is this change—specifying a parameter that is a complex type but not the FormDataCollection class—that causes Web API to select the JQueryMvcFormUrlEncodedFormatter class instead of the FormUrlEncodedMediaTypeFormatter class.

Instantiating Difficult Types Using URL-Encoded Data

Although the JQueryMvcFormUrlEncodedFormatter doesn’t allow the use of custom model binders, I can use the FormUrlEncodedMediaTypeFormatter class to create a custom media type formatter that does—and that means I can instantiate classes that require special handling, such as those with constructor parameters. Listing 17-12 shows the contents of a class file called UrlNumbersFormatter.cs that I added to the Infrastructure folder and used to create a media type formatter that can instantiate the Numbers class using the constructor with parameters.

Listing 17-12. The Contents of the UrlNumbersFormatter.cs File

using System;
using System.Globalization;
using System.IO;
using System.Net.Http;
using System.Net.Http.Formatting;
using System.Threading.Tasks;
using System.Web.Http;
using System.Web.Http.Controllers;
using System.Web.Http.Metadata;
using System.Web.Http.ModelBinding;
using System.Web.Http.ValueProviders.Providers;
using ExampleApp.Models;

namespace ExampleApp.Infrastructure {
    public class UrlNumbersFormatter : FormUrlEncodedMediaTypeFormatter {

        public override bool CanWriteType(Type type) {
            return false;
        }

        public override bool CanReadType(Type type) {
            return type == typeof(Numbers);
        }

        public override async Task<object> ReadFromStreamAsync(Type type,
            Stream readStream, HttpContent content, IFormatterLogger formatterLogger) {

            FormDataCollection fd = (FormDataCollection)
                await base.ReadFromStreamAsync(typeof(FormDataCollection),
                    readStream, content, formatterLogger);

            HttpActionContext actionContext = new HttpActionContext { };

            ModelMetadata md = GlobalConfiguration.Configuration
                .Services.GetModelMetadataProvider().GetMetadataForType(null, type);

            ModelBindingContext bindingContext = new ModelBindingContext {
                ModelMetadata = md,
                ValueProvider = new NameValuePairsValueProvider(fd,
                    CultureInfo.InvariantCulture)
            };

            if (new NumbersBinder().BindModel(actionContext, bindingContext)) {
                return bindingContext.Model;
            }
            return null;
        }
    }
}

The ReadFromStreamAsync method calls the base implementation to create a FormDataCollection object, which I then pass to an instance of the NameValuePairsValueProvider class. The NameValuePairsValueProvider class implements the IValueProvider interface and allows me to take values from the body and feed them into the custom model binder I created in Chapter 16.

Many of the rest of the statements in the ReadFromStreamAsync method prepare the context objects that I need in order to use the model binder. I need HttpActionContext and ModelBindingContext objects to call the BindModel method of an IModelBinder implementation, but I need to provide only the context that the binder relies on. For my NumbersBinder class, that means I can instantiate an HttpActionContext object without needing to set any properties. For the ModelBindingContext, I assign the NameValuePairsValueProvider object to the ValueProvider property. I also have to set the ModelMetadata property because it is checked by the ModelBindingContext class when the Model property is set by the model binder class. I describe the ModelMetadata class in Chapter 18, but for the moment it is enough to know that I get the ModelMetadata instance from the services collection.

Once I have creating the context objects, I can instantiate the model binder class and call the BindModel method. The BindModel method returns true when it is able to bind an object, and when I get that result, I return the value of the BindingContext.Model property.

The reason that the built-in JQueryMvcFormUrlEncodedFormatter media type formatter doesn’t allow custom binders and value providers is because the problems that feeding data from the body to model binders can cause. For my custom model binder, there are two problems that I need to resolve, and you can see the changes that I made to the NumbersBinder class in Listing 17-13.

Listing 17-13. Adapting a Model Binder in the NumbersBinder.cs File

using System.Collections.Generic;
using System.Linq;
using System.Web.Http.Controllers;
using System.Web.Http.ModelBinding;
using System.Web.Http.ValueProviders;
using ExampleApp.Models;

namespace ExampleApp.Infrastructure {

    public class NumbersBinder : IModelBinder {

        public bool BindModel(HttpActionContext actionContext,
                ModelBindingContext bindingContext) {

            string modelName = bindingContext.ModelName;

            Dictionary<string, ValueProviderResult> data
                = new Dictionary<string, ValueProviderResult>();

            data.Add("first", GetValue(bindingContext, modelName, "first"));
            data.Add("second", GetValue(bindingContext, modelName, "second"));
            data.Add("add", GetValue(bindingContext, modelName, "op", "add"));
            data.Add("double", GetValue(bindingContext, modelName, "op", "double"));
            data.Add("accept", GetValue(bindingContext, modelName, "accept"));

            if (data.All(x => x.Key == "accept" || x.Value != null)) {
                bindingContext.Model = CreateInstance(data);
                return true;
            }
            return false;
        }

        private ValueProviderResult GetValue(ModelBindingContext context,
                params string[] names) {

            for (int i = 0; i < names.Length - 1; i++) {
                string prefix = string.Join(".",
                    names.Skip(i).Take(names.Length - (i + 1)));
                if (prefix != string.Empty &&
                        context.ValueProvider.ContainsPrefix(prefix)) {
                    return context.ValueProvider.GetValue(prefix + "." + names.Last());
                }
            }
            return context.ValueProvider.GetValue(names.Last());
        }

        private Numbers CreateInstance(Dictionary<string, ValueProviderResult> data) {
            // ...statements omitted for brevity...
        }

        private T Convert<T>(ValueProviderResult result) {
            // ...statements omitted for brevity...
        }
    }
}

I need to fix two problems. The first is in the BindModel method, when I check to see whether I have been able to obtain values for all the properties and constructor parameters I need to set. The Numbers class defines the Accept property, which I have been setting using data from the request header. Media type formatters don’t have access to the request, and there is no global property that provides access to it, unlike in the MVC framework. To get the model binder working with the media type formatter, I have to relax the check that I perform to exclude the value for the Accept value.

...
if (data.All(x => x.Key == "accept" || x.Value != null)) {
    bindingContext.Model = CreateInstance(data);
    return true;
}
...

The second problem is that binders use the parameter name, which is available through the ModelBindingContext.ModelName property. Media type formatters don’t have access to details about which parameter they are being used to bind and can’t provide the model binder with the name. To make my custom model binder work in this situation, I have added support for working with an empty string as the model name, which is the value that the binder is presented with from the ModelBindingContext that I created in the UrlNumbersFormatter class.

...
if (prefix != string.Empty && context.ValueProvider.ContainsPrefix(prefix)) {
...

Now that the model binder can be used by the media type formatter, all that remains is to register the UrlNumbersFormatter class with Web API, as shown in Listing 17-14.

Listing 17-14. Registering a Media Type Formatter in the WebApiConfig.cs File

using System.Web.Http;
using System.Web.Http.ModelBinding;
using System.Web.Http.ModelBinding.Binders;
using System.Web.Http.ValueProviders;
using ExampleApp.Infrastructure;
using ExampleApp.Models;

namespace ExampleApp {
    public static class WebApiConfig {
        public static void Register(HttpConfiguration config) {

            config.DependencyResolver = new NinjectResolver();

            config.MapHttpAttributeRoutes();

            // ...routing statements omitted for brevity...

            config.Services.Add(typeof(ValueProviderFactory),
                new HeaderValueProviderFactory());

            config.Services.Insert(typeof(ModelBinderProvider), 0,
                new SimpleModelBinderProvider(typeof(Numbers), new NumbersBinder()));

            config.Formatters.Add(new XNumbersFormatter());
            config.Formatters.Insert(0, new UrlNumbersFormatter());
        }
    }
}

Notice that I have used the Insert method to register the UrlNumbersFormatter class. Media type formatters are queried in the order in which they are placed in the HttpConfiguration.Formatters collection, and this means I must ensure that my custom formatter appears before the JQueryMvcFormUrlEncodedFormatter class if I want it to deserialize the request data.

Simplifying the Custom Media Type Formatter

The media type formatter that I created in the previous section demonstrated how you can use model binders, which is helpful if you have already invested time and effort in the code that can instantiate difficult classes. If you don’t have a model binder that you want to use, then you can read the data values directly from the FormDataCollection object. Listing 17-15 shows how I simplified the UrlNumbersFormatter class so that it gets the data values and instantiates the Numbers class directly.

Listing 17-15. Simplifying the Media Type Formatter in the UrlNumbersFormatter.cs File

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Formatting;
using System.Threading.Tasks;
using ExampleApp.Models;

namespace ExampleApp.Infrastructure {
    public class UrlNumbersFormatter : FormUrlEncodedMediaTypeFormatter {

        public override bool CanWriteType(Type type) {
            return false;
        }

        public override bool CanReadType(Type type) {
            return type == typeof(Numbers);
        }

        public override async Task<object> ReadFromStreamAsync(Type type,
            Stream readStream, HttpContent content, IFormatterLogger formatterLogger) {

            FormDataCollection fd = (FormDataCollection)
                await base.ReadFromStreamAsync(typeof(FormDataCollection),
                    readStream, content, formatterLogger);

            return new Numbers(
                GetValue<int>("First", fd, formatterLogger),
                GetValue<int>("Second", fd, formatterLogger)) {
                Op = new Operation {
                    Add = GetValue<bool>("Add", fd, formatterLogger),
                    Double = GetValue<bool>("Double", fd, formatterLogger)
                }
            };
        }

        private T GetValue<T>(string name, FormDataCollection fd,
                IFormatterLogger logger) {
            T result = default(T);
            try {
                result = (T)System.Convert.ChangeType(fd[name], typeof(T));
            } catch {
                logger.LogError(name, "Cannot Parse Value");
            }
            return result;
        }

    }
}

This class uses the same techniques I employed in the “Creating a Custom Media Type Formatter” section, except that I use the base class to read and parse the data from the request body.

Handling JSON Requests

The JsonMediaTypeFormatter class is responsible for deserializing content in requests that are encoded with application/json or text/json MIME types (which are equivalent—both MIME types are JSON). It relies on the excellent Json.Net package to handle the JSON data. One of the reasons that I like the Json.Net package so much is that I have found it will decode even the sloppiest JSON data, which makes it well-suited for web services that have to deal with a wide range of clients, including those written by third parties with a less than complete understanding of the JSON format. Listing 17-16 shows how I have changed the Ajax request sent by jQuery so that the data is encoded via JSON.

Listing 17-16. Changing the jQuery Request Encoding to JSON in the bindings.js File

var viewModel = ko.observable({
    first: 2, second: 5, op: { add: true, double: true }
});
var response = ko.observable("Ready");
var gotError = ko.observable(false);

var sendRequest = function (requestType) {
    $.ajax("/api/bindings/sumnumbers", {
        type: "POST",
        data: JSON.stringify(viewModel()),
        contentType: "application/json",
        success: function (data) {
            gotError(false);
            response("Total: " + data);
        },
        error: function (jqXHR) {
            gotError(true);
            response(jqXHR.status + " (" + jqXHR.statusText + ")");
        }
    });
};

$(document).ready(function () {
    ko.applyBindings();
});

I have altered the structure of the view model so that there is an op property that is set to an object with add and double properties. I have also used the contentType property to specify that the request contains JSON data and used the JSON.stringify method to serialize the view model object into a JSON string like this:

{"first":2,"second":5,"op":{"add":true,"double":true}}

Notice how closely the JSON representation matches the definition of the view model in the JavaScript code. The JsonMediaTypeFormatter class will be matched to the request based on the MIME type and will create an instance of the Numbers class.

Creating Complex Types

The Json.Net package that JsonMediaTypeFormatter relies on can instantiate classes with parameterless constructors and settable properties, in just the same way as the media type handler for URL-encoded data.

Json.Net provides many options for customizing the instantiation process based on the JSON data, including attributes that can be applied to the model class to help instantiation. You can get full details of both approaches—and the rest of the Json.Net features—at http://james.newtonking.com.

In this section, I am going to demonstrate how to use a different Json.Net feature: LINQ to JSON. I like working with LINQ and find it endlessly useful for wrangling different formats into usable data. Listing 17-17 shows the contents of the JsonNumbersFormatter.cs file that I added to the Infrastructure folder.

Listing 17-17. The Contents of the JsonNumbersFormatter.cs File

using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
using System.Net.Http.Formatting;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using ExampleApp.Models;
using Newtonsoft.Json.Linq;

namespace ExampleApp.Infrastructure {
    public class JsonNumbersFormatter : MediaTypeFormatter {
        long bufferSize = 256;

        public JsonNumbersFormatter() {
            SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/json"));
            SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/json"));
        }

        public override bool CanWriteType(Type type) {
            return false;
        }

        public override bool CanReadType(Type type) {
            return type == typeof(Numbers);
        }

        public async override Task<object> ReadFromStreamAsync(Type type,
            Stream readStream, HttpContent content, IFormatterLogger formatterLogger) {

            byte[] buffer = new byte[Math.Min(content.Headers.ContentLength.Value,
                bufferSize)];
            string jsonString = Encoding.Default.GetString(buffer, 0,
                await readStream.ReadAsync(buffer, 0, buffer.Length));

            JObject jData = JObject.Parse(jsonString);
            return new Numbers((int)jData["first"], (int)jData["second"]) {
                Op = new Operation {
                    Add = (bool)jData["op"]["add"],
                    Double = (bool)jData["op"]["double"]
                }
            };
        }
    }
}

I access the LINQ to JSON feature through this statement:

...
JObject jData = JObject.Parse(jsonString);
...

The result is an implementation of the IEnumerable<KeyValuePair<string, JToken>>, where the JToken class describes one property from the JSON string I read from the request body. You can use the standard LINQ query syntax or extension methods to process the JSON data, which is useful if you are processing an array of data.

It is more helpful to be able to access all of the JSON properties when instantiating a single object, and JSON to LINQ helpfully presents the data values through array-style indexers. In the listing, I used the indexers to get the four data values I require to create an instance of the Numbers class. Listing 17-18 shows the statement I added to the WebApiConfig.cs file to register the media type formatter.

Listing 17-18. Registering a Media Type Formatter in the WebApiConfig.cs File

using System.Web.Http;
using System.Web.Http.ModelBinding;
using System.Web.Http.ModelBinding.Binders;
using System.Web.Http.ValueProviders;
using ExampleApp.Infrastructure;
using ExampleApp.Models;

namespace ExampleApp {
    public static class WebApiConfig {
        public static void Register(HttpConfiguration config) {

            config.DependencyResolver = new NinjectResolver();

            // ...routing statements omitted for brevity...

            config.Services.Add(typeof(ValueProviderFactory),
                new HeaderValueProviderFactory());

            config.Services.Insert(typeof(ModelBinderProvider), 0,
                new SimpleModelBinderProvider(typeof(Numbers), new NumbersBinder()));

            config.Formatters.Add(new XNumbersFormatter());
            config.Formatters.Insert(0, new UrlNumbersFormatter());
            config.Formatters.Insert(0, new JsonNumbersFormatter());
        }
    }
}

Handling XML Requests

Dealing with XML data can be tricky because there are so many ways in which the same data can be expressed. If you have control over the clients that will consume your web service, then you should use one of the other data formats I described in this chapter. The most common need to support XML arises in a web service that has to support legacy clients, under which circumstances you will have to adapt to process whatever format—or formats—you are sent. Using the built-in XML media type serializer involves carefully formatting the data sent by the client and preparing the model class for use by the web service.

jQuery doesn’t have built-in support for generating XML data from a JavaScript object, but in Listing 17-19 you can see how I have manually formatted the data I will process in the web service.

Listing 17-19. Using jQuery to Send XML Data in the bindings.js File

var viewModel = ko.observable({
    first: 2, second: 5, op: { add: true, double: true }
});
var response = ko.observable("Ready");
var gotError = ko.observable(false);

var sendRequest = function (requestType) {
    $.ajax("/api/bindings/sumnumbers", {
        type: "POST",
        data: "<Numbers>"
                + "<First>" + viewModel().first + "</First>"
                + "<Op>"
                    + "<Add>" + viewModel().op.add + "</Add>"
                    + "<Double>" + viewModel().op.double + "</Double>"
                + "</Op>"
                + "<Second>" + viewModel().second + "</Second>"
                + "</Numbers>",
        contentType: "application/xml",
        success: function (data) {
            gotError(false);
            response("Total: " + data);
        },
        error: function (jqXHR) {
            gotError(true);
            response(jqXHR.status + " (" + jqXHR.statusText + ")");
        }
    });
};

$(document).ready(function () {
    ko.applyBindings();
});

The result of the changes in Listing 17-19 is that the body of the HTTP request will contain the following XML fragment:

<Numbers>
    <First>2</First>
    <Op>
        <Add>true</Add>
        <Double>true</Double>
    </Op>
    <Second>5</Second>
</Numbers>

I find using the built-in media type formatter to be awkward because there are some important constraints on the way that XML data has to be structured. These can be worked around by changing the way the model class is configured—which I explain shortly—but these changes just create a different rigid data structure.

The first constraint is that the name and capitalization of each attribute name much exactly match the class or property name that it corresponds to. That means the top-level element must be Numbers, for example, and not numbers, and certainly not something like myNumbersXML.

The second constraint—and the one that I find the most problematic—is that the attributes must be organized in alphabetical order. This is the reason the Second attribute follows the Op attribute—because, of course, the letter O appears before S in the alphabet. I explain how to change the order of the attributes shortly, but it is possible only to create a different enforced order and not to create a more flexible approach (for that you need a custom media type formatter such as the one I describe in the next section).

The XML serializer that the built-in media type formatter uses will instantiate only the objects that have been annotated with the DataContract attribute and will set only the properties that have been decorated with the DataMember attribute. Both attributes are defined in the System.Runtime.Serialization namespace, and you can see how I have applied them to the Numbers and Operation classes in Listing 17-20.

Listing 17-20. Applying the Data Contract Attributes in the BindingModels.cs File

using System.Runtime.Serialization;

namespace ExampleApp.Models {

    [DataContract(Namespace="")]
    public class Numbers {

        public Numbers() { /* do nothing */ }

        public Numbers(int first, int second) {
            First = first; Second = second;
        }

        [DataMember]
        public int First { get; set; }
        [DataMember]
        public int Second { get; set; }
        [DataMember]
        public Operation Op { get; set; }
        public string Accept { get; set; }
    }

    [DataContract(Namespace="")]
    public class Operation {
        [DataMember]
        public bool Add { get; set; }
        [DataMember]
        public bool Double { get; set; }
    }
}

I have set the Namespace property of the DataContract attributes to the empty string ("") so that the serializer won’t expect an xmlns attribute on the top-level element of the data that is received from the client.

The DataContract and DataMember attributes are defined in an assembly that is not added to Web API projects by default. Select Add Reference from the Visual Studio Project menu, click the Framework section, and locate and check the option for the System.Runtime.Serialization assembly, as shown in Figure 17-2.

The DataMember attribute defines properties that can be used to change the way that the XML data is processed, as described in Table 17-8. The problem with these properties, however, is that they just create a different kind of rigid data structure that the client has to adhere to, and the media type formatter won’t deserialize the request if there is a mismatch between the data from the client and the format implied by the attributes.

Creating Complex Types from XML Data

When trying to instantiate classes using XML, I avoid treating the elements and attributes as a document with namespaces and schemas. Instead, I use LINQ to mine the XML data for key-value pairs. This approach has its limitations—not least that it incurs the overhead of XML without getting any of the benefits that structured data offers—but in most web services the use of XML is a legacy holdover, and the task at hand is to support XML clients with the minimum of effort. To that end, I created a class file called XmlNumbersFormatter.cs in the Infrastructure folder and used it to create the media type formatter shown in Listing 17-21.

Listing 17-21. The Contents of the XmlNumbersFormatter.cs File

using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
using System.Net.Http.Formatting;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using System.Xml.Linq;
using ExampleApp.Models;

namespace ExampleApp.Infrastructure {
    public class XmlNumbersFormatter : MediaTypeFormatter {
        long bufferSize = 256;

        public XmlNumbersFormatter() {
            SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/xml"));
            SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/xml"));
        }

        public override bool CanWriteType(Type type) {
            return false;
        }

        public override bool CanReadType(Type type) {
            return type == typeof(Numbers);
        }

        public async override Task<object> ReadFromStreamAsync(Type type,
            Stream readStream, HttpContent content, IFormatterLogger formatterLogger) {

            byte[] buffer = new byte[Math.Min(content.Headers.ContentLength.Value,
                bufferSize)];
            XElement xmlData = XElement.Parse(Encoding.Default.GetString(buffer, 0,
                await readStream.ReadAsync(buffer, 0, buffer.Length)));

            Dictionary<string, string> items = new Dictionary<string, string>();
            GetKvps(xmlData, items);

            if (items.Count == 4) {
                return new Numbers(
                    GetValue<int>(items["first"], formatterLogger),
                    GetValue<int>(items["second"], formatterLogger)) {
                        Op = new Operation {
                            Add = GetValue<bool>(items["add"], formatterLogger),
                            Double = GetValue<bool>(items["double"], formatterLogger)
                        }
                    };
            } else {
                formatterLogger.LogError("", "Wrong Number of Items");
                return null;
            }
        }

        private void GetKvps(XElement elem, Dictionary<string, string> dict) {
            if (elem.HasElements) {
                foreach (XElement innerElem in elem.Elements()) {
                    GetKvps(innerElem, dict);
                }
            } else {
                dict.Add(elem.Name.LocalName.ToLower(), elem.Value);
            }
        }

        private T GetValue<T>(string value, IFormatterLogger logger) {
            T result = default(T);
            try {
                result = (T)System.Convert.ChangeType(value, typeof(T));
            } catch {
                logger.LogError("", "Cannot Parse Value");
            }
            return result;
        }
    }
}

You will recognize some of the code and techniques from earlier custom media type formatters in this chapter. In this case, I read the body of the request and use the XElement.Parse method to enter the world of XML to LINQ. I enumerate the XML elements and create a dictionary of key-value pairs, which I then use to instantiate the Numbers class (using the constructor that defines parameters) and set its properties. This is less elegant than treating the XML data as a stream that is handled only once, but it has the benefit of not enforcing a rigid order in which the XML elements must appear. Listing 17-22 shows how I registered the media type formatter in the WebApiConfig.cs file.

Listing 17-22. Registering the Custom Media Type Formatter in the WebApiConfig.cs File

using System.IO;
using System.Text;
using System.Web.Http;
using System.Web.Http.ModelBinding;
using System.Web.Http.ModelBinding.Binders;
using System.Web.Http.ValueProviders;
using ExampleApp.Infrastructure;
using ExampleApp.Models;

namespace ExampleApp {
    public static class WebApiConfig {
        public static void Register(HttpConfiguration config) {

            config.DependencyResolver = new NinjectResolver();

            // ...routing statements omitted for brevity...

            config.Services.Add(typeof(ValueProviderFactory),
                new HeaderValueProviderFactory());

            config.Services.Insert(typeof(ModelBinderProvider), 0,
                new SimpleModelBinderProvider(typeof(Numbers), new NumbersBinder()));

            config.Formatters.Add(new XNumbersFormatter());
            config.Formatters.Insert(0, new UrlNumbersFormatter());
            config.Formatters.Insert(0, new JsonNumbersFormatter());
            config.Formatters.Insert(0, new XmlNumbersFormatter());
        }
    }
}

I have used the Insert method once again because I need to ensure that Web API uses my custom media type formatter before the built-in ones.

Customizing the Model Binding Process

Web API delegates the entire process of binding values for parameters to an implementation of the IActionValueBinder interface, which is defined in the System.Web.Http.Controllers namespace. Listing 17-23 shows the definition of the interface.

Listing 17-23. The IActionValueBinder Interface

namespace System.Web.Http.Controllers {
    public interface IActionValueBinder {
        HttpActionBinding GetBinding(HttpActionDescriptor actionDescriptor);
    }
}

The interface defines a GetBinding method. The important thing to note about the IActionValueBinder interface is that the GetBinding method operates on action methods and is being asked to find bindings for all of the parameters defined by an action—not just a single parameter.

You can see this in the classes that the IActionValueBinder interface uses. The GetBinding method is passed an instance of the HttpActionDescriptor class, which I introduced in Chapter 9 and where I listed the four most important members, which I have repeated in Table 17-9. There are other members, but they are not useful for the purposes of parameter bindings.

The HttpActionBinding class, which is returned by the GetBinding method, is a wrapper around the HttpActionDescriptor and an array of HttpParameterBinding objects that are used to get values for the parameters defined by an action method. The HttpActionBinding class defines a constructor with the following signature:

...
public HttpActionBinding(HttpActionDescriptor actionDescriptor,
    HttpParameterBinding[] bindings) {
...

The members defined by the HttpActionBinding class are not important in this chapter—it is enough to know that the purpose of an implementation of the IActionValueBinder interface is to be able to create an HttpActionBinding object using this constructor. In the sections that follow, I’ll show you how to change the behavior of the default IActionValueBinder implementation and how to create a custom one. Table 17-10 puts changing the action value binder in context.

Changing the Behavior of the Default Action Value Binder

All of the functionality that I have described since Chapter 14—value providers, model binders, and media type formatters—is provided by the DefaultActionValueBinder class, which is the Web API default implementation of the IActionValueBinder interface.

There are no configuration options for changing the behavior of the DefaultActionValueBinder class, but it is possible to create a subclass and override the method that defines the default policy for how values are sought for parameters. As a reminder, here is the default sequence that yields an HttpParameterBinding object for a single parameter:

1. If the parameter has been decorated with a subclass of the ParameterBindingAttribute, then call the attribute’s GetBinding method.
2. Try to obtain an HttpParameterBinding object from the parameter binding rules collection.
3. For simple types, proceed as though the FromUri attribute has been applied to the parameter.
4. For complex types, proceed as though the FromBody attribute has been applied to the parameter.

This sequence is implemented in the GetParameterBinding method of the DefaultActionValueBinder class. To demonstrate how to change the sequence, I created a file called CustomActionValueBinder.cs in the Infrastructure folder and used it to define the class shown in Listing 17-24.

Listing 17-24. The Contents of the CustomActionValueBinder.cs File

using System.Web.Http;
using System.Web.Http.Controllers;
using System.Web.Http.ModelBinding;

namespace ExampleApp.Infrastructure {
    public class CustomActionValueBinder : DefaultActionValueBinder {

        protected override HttpParameterBinding GetParameterBinding(
            HttpParameterDescriptor parameter) {

            if (parameter.ParameterBinderAttribute != null) {
                return parameter.ParameterBinderAttribute.GetBinding(parameter);
            }

            HttpParameterBinding binding =
                parameter.Configuration.ParameterBindingRules.LookupBinding(parameter);
            if (binding != null) {
                return binding;
            }

            if (parameter.ParameterType.IsPrimitive
                    || parameter.ParameterType == typeof(string)) {
                return parameter.BindWithAttribute(new ModelBinderAttribute());
            }

            return new FromBodyAttribute().GetBinding(parameter);
        }

    }
}

This class follows the same sequence of the DefaultActionValueBinder class but with one important difference: for simple types, I act as though the ModelBinder attribute has been applied, rather than the FromUri attribute. The FromUri attribute excludes any value provider factory class that does not implement the IUriValueProviderFactory interface. By using the ModelBinder attribute—which I described in Chapter 15—I allow all value provider factories to participate in the binding process.

Listing 17-25 shows how I registered the CustomActionValueBinder class as the implementation of the IActionValueBinder interface that Web API should use.

Listing 17-25. Registering an Action Value Binder in the WebApiConfig.cs File

using System.IO;
using System.Text;
using System.Web.Http;
using System.Web.Http.ModelBinding;
using System.Web.Http.ModelBinding.Binders;
using System.Web.Http.ValueProviders;
using ExampleApp.Infrastructure;
using ExampleApp.Models;
using System.Web.Http.Controllers;

namespace ExampleApp {
    public static class WebApiConfig {
        public static void Register(HttpConfiguration config) {

            config.DependencyResolver = new NinjectResolver();

            // ...routing statements omitted for brevity...

            config.Services.Add(typeof(ValueProviderFactory),
                new HeaderValueProviderFactory());

            config.Services.Insert(typeof(ModelBinderProvider), 0,
                new SimpleModelBinderProvider(typeof(Numbers), new NumbersBinder()));

            config.Formatters.Add(new XNumbersFormatter());
            config.Formatters.Insert(0, new UrlNumbersFormatter());
            config.Formatters.Insert(0, new JsonNumbersFormatter());
            config.Formatters.Insert(0, new XmlNumbersFormatter());

            config.Services.Replace(typeof(IActionValueBinder),
                new CustomActionValueBinder());
        }
    }
}

I used the HttpConfiguration.Services.Replace method to replace the DefaultActionValueBinder with a CustomActionValueBinder object.

Creating a Custom Action Value Binder

You can completely replace the process used to bind parameter values by directly implementing the IActionValueBinder interface. There is little reason to do this because there is a lot of flexibility in how the DefaultActionValueBinder can be used. But, if you have a compelling need to completely change the way that binding works, then this is the technique to use. As a demonstration, Listing 17-26 shows how I updated the CustomActionValueBinder class to implement the IActionValueBinder interface, rather than derive from DefaultActionValueBinder.

Listing 17-26. Implementing the IActionValueBinder Interface in the CustomActionValueBinder.cs File

using System.Web.Http;
using System.Web.Http.Controllers;
using System.Web.Http.ModelBinding;
using System.Linq;

namespace ExampleApp.Infrastructure {
    public class CustomActionValueBinder : IActionValueBinder {

        public HttpActionBinding GetBinding(HttpActionDescriptor actionDescriptor) {
            return new HttpActionBinding(
                actionDescriptor,
                actionDescriptor.GetParameters()
                    .Select(p => GetParameterBinding(p)).ToArray()
            );
        }

        protected HttpParameterBinding GetParameterBinding(
                HttpParameterDescriptor parameter) {

            if (parameter.ParameterBinderAttribute != null) {
                return parameter.ParameterBinderAttribute.GetBinding(parameter);
            }

            HttpParameterBinding binding =
                parameter.Configuration.ParameterBindingRules.LookupBinding(parameter);
            if (binding != null) {
                return binding;
            }

            if (parameter.ParameterType.IsPrimitive
                    || parameter.ParameterType == typeof(string)) {
                return parameter.BindWithAttribute(new ModelBinderAttribute());
            }

            return new FromBodyAttribute().GetBinding(parameter);
        }
    }
}

The changes are simple because I am reproducing the behavior of the default class, and all of the complexity of the model binding process is contained in the value providers, model binders, and media type formatters that Web API includes.

Summary

In this chapter, I explained how media type formatters can be used to bind complex types from the body of a request. I showed you how deserialization works by creating and using a custom media type formatter and by using the built-in media type formatters. I explained the limitations on the classes that the built-in formatters will instantiate and demonstrated how to override this behavior to deserialize classes that require special handling. I finished this chapter by demonstrating how to replace the class that drives the parameter and model binding processes with a custom implementation. In the next chapter, I show you the features that Web API provides to ensure that the data you bind from requests is what you expected.