How to customize parameter binding

Web API provides some great out of box experience with parameter binding. It also provides some powerful extensibility points to allow you customize that binding process. For example, you can bind multiple parameters from uri. However, it can only bind one parameter from request content by default. If you try to mark multiple parameters with [FromBody] attribute, you will get an error. The other good example is sometimes people might want to bind a parameter from some other source instead of request. There are also occasions where some parameter might come from either request uri or request body. For all those situations,  a custom parameter binding will be your friend.

Scenario 1: How to bind a parameter not coming from request

Say you have a controller that will take an IPrincipal as an parameter. The IPrincipal is not coming from request. So your action looks like the following.

Code Snippet

12.        [HttpGet]
13.         public HttpResponseMessage BindPrincipal(IPrincipal principal)
14.         {
15.             return Request.CreateResponse(System.Net.HttpStatusCode.Accepted,
16.                 String.Format("BindPrincipal with Principal name {0}.", principal.Identity.Name));
17.         }

 Here is your custom parameter binding to bind a custom principal to the IPrincipal parameter. 

Code Snippet

9.     /// <summary>
10.     /// A Custom HttpParameterBinding to bind a complex type, e.g. IPrincipal, which is not coming from request
11.     /// </summary>
12.     public class PrincipalParameterBinding : HttpParameterBinding
13.     {
14.         public PrincipalParameterBinding(HttpParameterDescriptor desc)
15.             : base(desc)
16.         {
17.         }
18.  
19.         public override Task ExecuteBindingAsync(ModelMetadataProvider metadataProvider, HttpActionContext actionContext, CancellationToken cancellationToken)
20.         {
21.             // Set the binding result here
22.             SetValue(actionContext, new GenericPrincipal(new GenericIdentity("MyIdentity"), new string[]{"myrole"}));
23.  
24.             // now, we can return a completed task with no result
25.             TaskCompletionSource<AsyncVoid> tcs = new TaskCompletionSource<AsyncVoid>();
26.             tcs.SetResult(default(AsyncVoid));
27.             return tcs.Task;
28.         }
29.  
30.         private struct AsyncVoid
31.         {
32.         }
33.     }

 

Scenario 2:  How to bind a complex type either from body or from uri

 Sometimes, server might need to handle different type of requests. Some requests have information stored in the request Uri, and others have them stored in the request body. Here is how you can write one action to handle both types of requests. Your action code might look like the following:

Code Snippet

19.         [HttpGet]
20.         [HttpPost]
21.         public HttpResponseMessage BindCustomComplexTypeFromUriOrBody(TestItem item)
22.         {
23.             return Request.CreateResponse(System.Net.HttpStatusCode.Accepted,
24.                 String.Format("BindCustomComplexTypeFromUriOrBody returns item.Name = {0}.", item.Name));
25.         }

 Your custom parameter binding can delegate the work to either FromUri or FromBody.

Code Snippet

9. /// <summary>
10. /// A Custom HttpParameterBinding to bind a complex type either from request body or uri
11. /// </summary>
12. public class FromUriOrBodyParameterBinding : HttpParameterBinding
13. {
14.     HttpParameterBinding _defaultUriBinding;
15.     HttpParameterBinding _defaultFormatterBinding;
16.  
17.     public FromUriOrBodyParameterBinding(HttpParameterDescriptor desc)
18.         : base(desc)
19.     {
20.         _defaultUriBinding = new FromUriAttribute().GetBinding(desc);
21.         _defaultFormatterBinding = new FromBodyAttribute().GetBinding(desc);
22.     }
23.  
24.     public override Task ExecuteBindingAsync(ModelMetadataProvider metadataProvider, HttpActionContext actionContext, CancellationToken cancellationToken)
25.     {
26.         if (actionContext.Request.Content != null && actionContext.Request.Content.Headers.ContentLength > 0)
27.         {
28.             // we have something from the body, try that first
29.             return _defaultFormatterBinding.ExecuteBindingAsync(metadataProvider, actionContext, cancellationToken);
30.         }
31.         else
32.         {
33.             // we need to read things from uri
34.             return _defaultUriBinding.ExecuteBindingAsync(metadataProvider, actionContext, cancellationToken);
35.         }
36.     }
37.  
38. }

 

Scenario 3: How to bind a parameter with a different property Name

Due to various reasons, the request sometimes contains a different name for a property than the actual property name defined on the server. How do we get those mapped correctly? For example, here is the type definition that its property is named "Name" on the server, but the client wants to send it  using "$Name" instead.

Code Snippet

5. public class TestItemRenameProperty
6. {
7.     [DataMember(Name = "$Name")]
8.     public string Name { get; set; }
9. }

Here is how the action could look like.

Code Snippet

27. [HttpGet]
28. public HttpResponseMessage BindCustomComplexTypeFromUriWithRenamedProperty(TestItemRenameProperty item)
29. {
30.     return Request.CreateResponse(System.Net.HttpStatusCode.Accepted,
31.         String.Format("BindCustomComplexTypeFromUriWithRenamedProperty item.Name = {0}.", item.Name));
32. }

Scenario 4: How to bind multiple parameters form a request body

This might be the most common case where you want to use custom parameter bindings. Out of box, one could only bind one parameter from request body. It forces user who want to bind multiple objects having to write a wrapper class to wrap all those parameters. Fortunately, you can also write a custom parameter binding to solve that problem elegantly. Here is how your action might look like, and your first name and last name are coming from request body.  

Code Snippet

34. [HttpPost]
35. public HttpResponseMessage PostMultipleParametersFromBody(string firstname, string lastname)
36. {
37.     return Request.CreateResponse(System.Net.HttpStatusCode.Accepted,
38.         String.Format("BindCustomCoPostMultipleParametersFromBodymplexType FristName = {0}, LastName = {1}.", firstname, lastname));
39. }

Now let us write a parameter binding to map those values from request body to firstname and lastname parameters.

Code Snippet

11. /// <summary>
12. /// A Custom HttpParameterBinding to bind multiple parameters from request body
13. /// </summary>
14. public class MultipleParameterFromBodyParameterBinding : HttpParameterBinding
15. {
16.     private const string MultipleBodyParameters = "MultipleBodyParameters";
17.  
18.     public MultipleParameterFromBodyParameterBinding(HttpParameterDescriptor descriptor)
19.         : base(descriptor)
20.     {
21.     }
22.  
23.     public override Task ExecuteBindingAsync(ModelMetadataProvider metadataProvider, HttpActionContext actionContext, CancellationToken cancellationToken)
24.     {
25.         NameValueCollection col = TryReadBody(actionContext.Request);
26.  
27.         if (col == null)
28.         {
29.             throw new HttpResponseException(System.Net.HttpStatusCode.BadRequest);
30.         }
31.  
32.         // Set the binding result here
33.         SetValue(actionContext, col[Descriptor.ParameterName]);
34.  
35.         // now, we can return a completed task with no result
36.         TaskCompletionSource<AsyncVoid> tcs = new TaskCompletionSource<AsyncVoid>();
37.         tcs.SetResult(default(AsyncVoid));
38.         return tcs.Task;
39.     }
40.  
41.     NameValueCollection TryReadBody(HttpRequestMessage request)
42.     {
43.         object result = null;
44.         if (!request.Properties.TryGetValue(MultipleBodyParameters, out result))
45.         {
46.             // parsing the string like firstname=Hongmei&lastname=Ge
47.             NameValueCollection collection = new NameValueCollection();
48.             result = request.Content.ReadAsFormDataAsync().Result;
49.             request.Properties.Add(MultipleBodyParameters, result);
50.         }
51.  
52.         return result as NameValueCollection;
53.     }
54.  
55.     private struct AsyncVoid
56.     {
57.     }
58. }

 

Final step: How to register a custom parameter binding

Now we have all those wonderful custom Parameter Bindings, how do you tell Web API that you want to use them instead of those default ones? Here is how you can do it. 

Code Snippet

29.             // Register an action to create custom ParameterBinding
30.             config.ParameterBindingRules.Insert(0, GetCustomParameterBinding);

 

Code Snippet

102.      public static HttpParameterBinding GetCustomParameterBinding(HttpParameterDescriptor descriptor)
103.      {
104.          if (descriptor.ParameterType == typeof(IPrincipal))
105.          {
106.              return new PrincipalParameterBinding(descriptor);
107.          }
108.          else if ( descriptor.ParameterType == typeof(TestItem))
109.          {
110.              return new FromUriOrBodyParameterBinding(descriptor);
111.          }
112.          else if (descriptor.ParameterType == typeof(TestItemRenameProperty))
113.          {
114.              return new CustomModelBinderWithPropertyName(descriptor);
115.          }
116.          else if ( descriptor.ParameterType == typeof(string) )
117.          {
118.              return new MultipleParameterFromBodyParameterBinding(descriptor);
119.          }
120.          
121.          // any other types, let the default parameter binding handle
122.          return null;
123.      }

 

To summarize, custom parameter binding is a powerful extensibility point which allows users to take full control of the parameter binding process. To learn more details, you can download the sample code from our aspnet codeplex site at https://aspnet.codeplex.com/SourceControl/changeset/66590b705e5b.

Happy coding with ASPNET Web API!

Comments

• Anonymous
  April 09, 2013
  "Scenario 3: How to bind a parameter with a different property Name" doesn't work!

• Anonymous
  August 04, 2015
  Thanks great post just what I needed and the only one I could find on how to implement your own binding using HttpParameterBinding. Your PrincipalParameterBinding example can now be simplified to return Task.FromResult(0);