Overview

As I mentioned in Tracing in ASP.NET Web API the framework code looks in the HttpConfiguration to see if an ITraceWriter service has been registered.  If so, Web API code calls it to describe each operation it performs.  A custom ITraceWriter can listen to those traces and do whatever it wants with them, such as writing them to a file or a database.  The preview package described here is such a custom ITraceWriter, and it sends those traces to System.Diagnostics.Trace.

System.Diagnostics.Trace has been a part of .Net for quite awhile and is often used by both application and framework developers to debug and diagnose code.  By making your Web API application write to it using this preview package, you can take advantage of existing mechanisms to capture and analyze these traces.

Installing the ASP.NET Web API Tracing preview package

To get ASP.NET Web API itself, you can either install Visual Studio 2012 and .NET 4.5 or you can download Web API for Visual Studio 2010.  Web API is an open-source project, so you can also get the source code from the Open Source home on codeplex.

Once you have it installed, you can create a new ASP.NET Web API application using File | New | Project… | Web | ASP.NET MVC 4 Web Application.

Next install the Microsoft.AspNet.WebApi.Tracing pre-release Nuget package as described at Microsoft ASP.NET Web API Tracing.  At this point, you will have an application that looks like this:

Enabling and configuring the System.Diagnostics Trace Writer

Installing Microsoft.AspNet.WebApi.Tracing makes these changes to your project:

1. Updates packages.config and adds a reference to your project to System.Web.Http.Tracing.dll
2. Installs the file App_Start\TraceConfig.cs

Before you can use this trace writer, you must enable it by manually adding a line of code to App_Start\WebApiConfig.cs to invoke TraceConfig.Register().  The ReadMe.txt that appears after installation describes this, but here is a screenshot showing the line after I have added it:

At this point, tracing is enabled and you can run your app.  But first let’s look at the code that was added to your app to see how we can configure it.

Configuring the trace writer

Installing the preview package creates the file App_Start\TraceConfig.cs in your project.  This code registers the SystemDiagnosticsTraceWriter class in the configuration and is where you go to configure tracing.

By default, it is configured for:

• MinimumLevel = TraceLevel.Info: will trace all Info, Warn, Error and Fatal traces
• IsVerbose = false: traces only minimal information in each trace

Feel free to change these as you like.  For example, setting MinimumLevel to TraceLevel.Warn will write only Warn, Error and Fatal traces.  Setting IsVerbose to true will include more information in each trace.

Debugging with the Output window

To see this tracing in action, start the app under the debugger (F5) and open the Output window in Visual Studio.  In the screen shot below, I have used Fiddler to issue a GET request to https://localhost:64758/api/values to access the ValuesController created by the default MVC 4 project template.

The output window contains the Web API traces of all the operations performed in the handling of that request.  Each trace describes the operation that was performed as well as any errors that were encountered.  In this case, it was a successful request, and we can see everything Web API did to service that single request.

If I change the SystemDiagnosticsTraceWriter.IsVerbose to true and re-run the app, I see more detailed trace information as shown in the next screen shot.

In this case, each trace record contains additional information, including the timestamp (UTC) and the GUID for the request.  It also shows 2 traces for each activity; the “Kind=Begin” trace occurs prior to starting an activity.  The “Kind=End” trace occurs when the activity completes.  This pair of events is handy during debugging because you can know what activity was executing at the point an error occurred, even if you don’t have a stack trace.

The verbose form of tracing is more appropriate when writing to a store or for later analysis because it contains enough information to correlate all traces to a specific request.

The non-verbose form is often better for interactive debugging where less is more.

Debugging with Intellitrace

Visual Studio also has an Intellitrace feature that is handy for debugging.  It registers a TraceListener with System.Diagnostics.Trace, meaning anything your app traces via the Microsoft.AspNet.WebApi.Tracing package will be seen by Intellitrace too.

In the next screen shot, I have run the app, issued an illegal HTTP request, and opened the Intellitrace window.  I have also used Tools | Options | Intellitrace to enable the Tracing category.  Notice that each trace written by Web API appears in Intellitrace.  Each trace has also caused Intellitrace to capture the stack for later analysis.  You don’t have to set a breakpoint.  You can just run the app for the entire request and then come back later to examine what the stack looked like at each step.

In this example, I noticed a Warning level trace and clicked on it.  Intellitrace shows the stack as it appeared at the time that trace was received.  Moreover, it analyzed the stack and recognized my user code was involved in this call.  It then opened my source code and took me to the line of code where the trace occurred.  In this case, you can see a validation check I had added to my ValuesController.Get() method.  I chose to write a warning to the ITraceWriter myself so that my own traces were correlated with the Web API framework traces.

Quite a lot of information from a single click, wasn’t it?

You can learn more about using Intellitrace here.  It can be pretty useful for debugging, and oddly is not widely known or used.

Perhaps more importantly in this context, it also demonstrates that writing to System.Diagnostics.Trace lights-up existing tooling that register TraceListeners with System.Diagnostics.Trace.

One example of such a TraceListener is the Windows Azure Diagnostics package, also known as WAD.  If you deploy your MVC4 Web API application on Azure and configure the DiagnosticMonitor, anything written to System.Diagnostics.Trace will be stored in cloud table storage (WADLogsTable).

In other words, by installing this Microsoft.AspNet.WebApi.Tracing preview package and configuring WAD’s DiagnosticManager, you have enabled your Web API application to write its traces to persistent table storage in the cloud.

If future articles, I’ll describe how you can use this, but if you want a sneak preview look at Windows Azure Diagnostics.

In our example scenario, we’ll expose these concepts:

• A “Store” class holds multiple “Products”
• A store repository manages multiple stores
• A store controller exposes a Web API to the store repository
• Each store has a unique URL

We need UrlHelper in this scenario because we want to expose a unique URL for each store, allowing clients to do basic create/read/update/delete operations on a single store.  We won’t know each store’s address at compile time because they will be created dynamically.

Getting started

The following sample code was built using Visual Studio 2010 and the latest bits of WebApi built each night which you can get here. Or if you prefer, you can use VS 2012 RC and get VS 2012 RC bits here.

We’ll start using File New Project | Web | Mvc4 | WebApi to create a new MVC 4 ASP.Net Web Api project, and they we’ll add to it.

Creating the routes to reach the stores

In this app we need to expose a unique URL for each separate store.   The easiest way to do this is to assign a unique ID to each store when it is created and to use that as part of the route information in the store.

When we created the default WebApi project above, the template automatically setup this route for us:

   1: public static class WebApiConfig

   2: {

   3:     public static void Register(HttpConfiguration config)

   4:     {

   5:         config.Routes.MapHttpRoute(

   6:             name: "DefaultApi",

   7:             routeTemplate: "api/{controller}/{id}",

   8:             defaults: new { id = RouteParameter.Optional }

   9:         );

  10:     }

  11: }

That route is exactly what we need, so we’ll leave it unchanged.  It effectively says the canonical route will for this WebApi will be:

1. The constant “api”, followed by,
2. The name of the ApiController, optionally followed by,
3. The unique ID of a store

An example of such a URL is https://localhost:20480/Store/5 which will invoke a method on a StoreController with the ID == 5

Creating the models

Let’s create some very simple models in our project’s Models folder:

   1: public class Store

   2: {

   3:     public string Id { get; set; }

   4:     public string Url { get; set; }

   5:     public List<string> Products { get; set; }

   6: }

   1: public interface IStoreRepository

   2: {

   3:     Store CreateStore();

   4:     IEnumerable<Store> GetStores();

   5:     Store GetStore(string id);

   6:     bool DeleteStore(Store store);

   7:     void AddProduct(Store store, string product);

   8:     void RemoveProduct(Store store, string product);

   9: }

Creating the StoreController

Now let’s create the StoreController itself by using “Add New Item | Controller” in the Controllers folder.  For now, we’ll just expose the basic methods to create a new store and to retrieve the list of all stores.

   1: public class StoreController : ApiController

   2: {

   3:     public IStoreRepository Repository { get; set; }

   4:  

   5:     [HttpPost]

   6:     public Store CreateStore()

   7:     {

   8:         Store store = Repository.CreateStore();

   9:         store.Url = Url.Link("DefaultApi", new { controller = "Store", id = store.Id });

  10:         return store;

  11:     }

  12:  

  13:     [HttpGet]

  14:     public IEnumerable<Store> GetStores()

  15:     {

  16:         return Repository.GetStores().ToArray();

  17:     }

  18: }

Already we can see how to use UrlHelper in this line.  Every ApiController instance is given a UrlHelper instance available through the “Url” property.  The StoreController uses it to create the unique URL for the new store.  The meaning of that line of code is:

• Url.Link – the UrlHelper method to create a URL
• “DefaultApi” – the name of the route.  This matches the value passed to MapHttpRoute in WebConfig.cs above
• new { controller = “Store”, id = store.Id } – the set of “route values” to use to compose the URL

If you’re not already familiar with MVC routes, the route values may look a little strange to you.  It is just a way to use C#’s anonymous types to compose a set of name/value pairs.  The Link() method supports an overload that accepts an IDictionary<string, object> if you prefer.   This is the normal pattern to pass values to the MVC routing layer and is not unique to WebApi.

In this case, the call to the Link() method effectively says “Using the route called ‘DefaultApi’ create a URL that will invoke the StoreController and pass the store’s ID to it.”

If the store’s ID had been 99, the resulting URL would have been something like https://localhost:20480/Store/99

Note: How the StoreController gets the IStoreRepository instance is not important to this sample.  Refer to this blog for an example of how to use Dependency Injection to provide it at runtime. Not shown in this example is an implementation of IStoreRepository that simply keeps Store instances in memory.

Run the app

At this point, we have all we need to run the app.  Start it with F5, observe the normal MVC Home page, and then use Fiddler to issue a request to create a new store.  This POST request will invoke the StoreController.CreateStore() method.  The response is the new Store object represented in Json.   The Url field (https://localhost:20480/Store/3) shows the value returned from UrlHelper.Link().

Add the store-specific methods to StoreController

So now we have a controller that can manufacture new Store objects and return a unique URL for each one.   Let’s complete this example by extending StoreController to contain the methods to operate on those individual stores:

   1: public class StoreController : ApiController

   2: {

   3:     // GET api/Store/id -- returns the Store from its Id

   4:     [HttpGet]

   5:     public Store GetStore(string id)

   6:     {

   7:         return EnsureStoreFromId(id);

   8:     }

   9:  

  10:     // DELETE api/Store/id -- deletes the store identified by Id

  11:     [HttpDelete]

  12:     public void DeleteStore(string id)

  13:     {

  14:         Store store = EnsureStoreFromId(id);

  15:         bool existed = Repository.DeleteStore(store);

  16:         if (!existed)

  17:         {

  18:             throw new HttpResponseException(HttpStatusCode.NotFound);

  19:         }

  20:     }

  21:  

  22:     // PUT api/Store/id?product=Xyz -- adds product Xyz to store identified by Id

  23:     [HttpPut]

  24:     public void AddProduct(string id, string product)

  25:     {

  26:         Store store = EnsureStoreFromId(id);

  27:         Repository.AddProduct(store, product);

  28:     }

  29:  

  30:     // DELETE api/Store/id?product=Xyz -- removes product Xyz to store identified by Id

  31:     [HttpDelete]

  32:     public void RemoveProduct(string id, string product)

  33:     {

  34:         Store store = EnsureStoreFromId(id);

  35:         Repository.RemoveProduct(store, product);

  36:     }

  37:  

  38:     private Store EnsureStoreFromId(string id)

  39:     {

  40:         Store store = Repository.GetStore(id);

  41:         if (store == null)

  42:         {

  43:             throw new HttpResponseException(HttpStatusCode.NotFound);

  44:         }

  45:  

  46:         return store;

  47:     }

  48: }

Each of these new StoreController methods accept a string ID – which is the unique Store ID created by the repository.  So when a request such as GET https://localhost:20480/Store/3 is sent, the existing route information tells WebApi to invoke StoreController.GetStore() and to model-bind the string ID parameter from the route information contained in the URL.

Let’s run the app again to create a new store and add a new product:

First, we issue a PUT https://localhost:20480/api/Store/3?product=Bicycle to add a Bicycle to store #3:

And then we issue a GET to https://localhost:20480/api/Store/3 to examine the contents of store #3:

Using the MVC UrlHelper to reach ApiControllers

MVC 4 exposes 2 kinds of controllers – the conventional MVC Controller and the new WebApi ApiController.  The MVC controllers are normally used for the presentation level and usually have corresponding ���views” to display their respective “models”.  In contrast, the ApiController is used for the “web api” part of the application, and generally exposes actions to bind to the Http GET, PUT, POST, DELETE (etc) methods.

An MVC 4 app can have a mix of either of these controller types.  In fact, it is not unusual for the MVC controllers to be aware of one or more web api’s and to want to render URL links to them.

In the example above, we showed an ApiController creating a URL to reach a specific action on an ApiController.  To do this, it used a UrlHelper instance available directly from the executing ApiController.

MVC Controllers have a similar concept – the Controller instance contains a Url property that returns a UrlHelper instance.  In this case, this UrlHelper is a different class than the WebApi one because it already existed before WebApi.  But they are very similar in concept and functionality.

Let’s modify our app so that the MVC HomeController can render URL links to the StoreController:

   1: public class HomeController : Controller

   2: {

   3:     public ActionResult Index()

   4:     {

   5:         return View(InMemoryStoreRepository.Instance);

   6:     }

   7:  

   8:     public ActionResult CreateStore()

   9:     {

  10:         Store store = InMemoryStoreRepository.Instance.CreateStore();

  11:  

  12:         string storeLink = Url.HttpRouteUrl("DefaultApi", new { controller = "Store", id = store.Id });

  13:         store.Url = new Uri(Request.Url, storeLink).AbsoluteUri.ToString();

  14:  

  15:         return this.RedirectToAction("Index", "Home");

  16:     }

  17: }

The highlighted lines above do exactly what we did before in the StoreController – create a new store and then create a URL that will direct a request to the StoreController to operate on that store.   It looks slightly different because the MVC UrlHelper already existed before WebApi, and backwards compatibility was important.

The HttpRouteUrl() method was added to the existing MVC UrlHelper to deal with ApiController routes.  The example above effectively says “I want a URL to an ApiController using the route named ‘DefaultApi’ to invoke the StoreController, with the given ID”.

Summary

As you saw in this example, the UrlHelper class exists to help compose URL’s using the application’s routing information.  There are 2 version of UrlHelper – the existing MVC version and the new WebApi version.  Both are available from their respective controller instance, and both can be used to create URL’s.

In WebApi, we define the basic verbs of our API in a class derived from ApiController.  When an Http request is received, WebApi uses the request URL and the application’s routing tables to map the request to a specific public method in a specific ApiController class.  All parameters for that method are satisfied using normal model binding.  Those parameter values typically come from the URL or from the request body, but model binding allows them to come from almost anywhere.

But what do we do when the ApiController class itself requires parameters to be instantiated?   ApiController’s are instantiated by WebApi per request, so we can’t very well create it once and reuse it.  Moreover, there may be many running concurrently in response to multiple requests, and clearly they must not share state.  So we need a way to tell WebApi how to instantiate that ApiController using custom constructor parameters for each request.

This post shows how we do this using Autofac.

In this example, we’ll start with Phil Haack’s original TDD and Dependency Injection with ASP.NET MVC and then translate it to use Web API and Autofac

Getting Started

The following sample code was built using Visual Studio 2010 and the latest bits of WebApi built each night.   Henrik F. Nielsen  describes how to get the nightly AspNetWebStack bits.  Or if you prefer, you can use VS 2012 RC and get the nightly AspWebStack VS 2012 RC bits.

In either case, we’ll start by creating a new MVC 4 Web Application using File New Project.

And we’ll have the basic WebApi project, ready to run.  You can F5 at this point and see a default Home page.  You can also use Fiddler to issue requests to the ValuesController to try it out.

Notice the sample ValuesController created by the template. It shows what a simple ApiController looks like, but  is too simple for our needs because it can be instantiated without any parameters.

Creating the BlogController and repository

So let’s just write our new controller demonstrating what we want, and we’ll worry about wiring it up later.

In this scenario we want to expose a simple BlogController that stores references to blog posts in a separate repository.  Let’s start with an interface to the repository, which we will declare in the Models folder:

   1: namespace Autofac.Sample.Models

   2: {

   3:     public interface IPostRepository

   4:     {

   5:         void Add(Post post);

   6:         IList<Post> ListRecentPosts(int retrievalCount);

   7:     }

   8: }

The Post is just a data class to represent items in the repository:

   1: public class Post

   2: {

   3:     public string Author { get; set; }

   4:     public DateTime Date { get; set; }

   5:     public string Url { get; set; }

   6: }

And then let’s create the stub of our BlogController in the Controllers folder.  We click on the Controllers folder, and ask to Add New Controller.

which will give us this empty controller:

   1: namespace Autofac.Sample.Controllers

   2: {

   3:     public class BlogController : ApiController

   4:     {

   5:     }

   6: }

Let’s fill in the methods to allow us to POST new blog posts and GET existing posts:

   1: public class BlogController : ApiController

   2: {

   3:     private IPostRepository _repository;

   4:     public BlogController(IPostRepository repository)

   5:     {

   6:         _repository = repository;

   7:     }

   8:  

   9:     [HttpGet]

  10:     public IEnumerable<Post> Recent(int retrievalCount)

  11:     {

  12:         return _repository.ListRecentPosts(retrievalCount);

  13:     }

  14:  

  15:     [HttpPost]

  16:     public void Add(Post post)

  17:     {

  18:         _repository.Add(post);

  19:     }

  20: }

I’ve used [HttpGet] and [HttpPost] here to be explicit about the Http methods allowed and because I chose non-conventional names for the controller methods.  As mentioned before, the method parameters will be satisfied by model binding.  The Recent() method will get its retrievalCount from the URL, and the Add() method will get its Post from the request body.

But notice the important difference here – BlogController’s constructor requires an IPostRepository instance.   This means the default WebApi controller activation logic will need help to instantiate it

Unit testing the BlogController

Before we worry about how to wire this up, let’s write some unit tests to verify our BlogController works properly.  We’ll use https://nuget.org/packages/xunit for our unit testing framework and  https://nuget.org/packages/Moq as our mocking framework.

   1: public class BlogControllerTest

   2: {

   3:     private readonly Post _samplePost = new Post(){

   4:       Author = "Phil Haack",

   5:       Date = new DateTime(2007, 12, 7),

   6:       Url = "https://haacked.com/archive/2007/12/07/tdd-and-dependency-injection-with-asp.net-mvc.aspx"};

   7:  

   8:     [Fact]

   9:     public void Recent_Calls_Repository_ListRecentPosts()

  10:     {

  11:         // Arrange

  12:         List<Post> expectedPosts = new List<Post>() { _samplePost };

  13:         int retrievalCount = expectedPosts.Count;

  14:  

  15:         Mock<IPostRepository> repositoryMock = 

  16:            new Mock<IPostRepository>();

  17:         repositoryMock.Setup(

  18:            (m) => m.ListRecentPosts(retrievalCount))

  19:               .Returns(expectedPosts);

  20:         BlogController blogController = 

  21:            new BlogController(repositoryMock.Object);

  22:  

  23:         // Act

  24:         IEnumerable<Post> actualPosts = 

  25:           blogController.Recent(retrievalCount);

  26:  

  27:         // Assert

  28:         Assert.Equal(expectedPosts, actualPosts);

  29:     }

  30:  

  31:     [Fact]

  32:     public void Add_Calls_Repository_Add()

  33:     {

  34:         // Arrange

  35:         Post createdPost = null;

  36:  

  37:         Mock<IPostRepository> repositoryMock = 

  38:           new Mock<IPostRepository>();

  39:         repositoryMock.Setup(

  40:           (m) => m.Add(_samplePost))

  41:           .Callback<Post>(p => { createdPost = p; });

  42:  

  43:         BlogController blogController = 

  44:           new BlogController(repositoryMock.Object);

  45:  

  46:         // Act

  47:         blogController.Add(_samplePost);

  48:  

  49:         // Assert

  50:         Assert.Equal(_samplePost, createdPost);

  51:     }

  52: }

These two tests verify the BlogController’s Add() and Recent() methods interact correctly with the mock IPostRepository, and they are enough for what we’re trying to demonstrate here.  They show that we can simply instantiate the BlogController as we would any other object and that we can provide an IPostRepository of our choosing from the outside.

This is pretty convenient.  And it demonstrates one of the benefits of dependency injection – isolation.  We did not need to mock up an elaborate support infrastructure to instantiate our BlogController.  And the BlogController did not require other special knowledge of how to get its IPostRepository.

(Yes, I can hear the observations that current ApiControllers often do require more elaborate infrastructure to be unit tested due to additional context they typically require, such as the HttpRequestMessage, HttpConfiguration, etc.  But in this specific case, we have all we need to mock this controller’s behavior).

After we test and debug BlogController for a few cycles and decide it is working properly, we want to add it to a running application.

Installing Autofac

The DI framework we use in this article is https://nuget.org/packages/Autofac.  Because it is a Nuget package, it is simple to add to our application.  We do this by using Tools | Library Package Manager | Package Manager Console to bring up an interactive command window and enter “install-package autofac”, like this:

That’s it.  Autofac is now installed into our app, and we can start using it.

Integrating Autofac

We could start wiring up Autofac manually but Alex Meyer-Gleaves has already done a nice integration of Autofac and WebApi at https://alexmg.com/author/Alex-Meyer-Gleaves.aspx .

If you are using the RC bits of WebApi, just install his Nuget package from https://nuget.org/packages/Autofac.WebApi and follow the instructions.

But because I am using newer WebApi bits and also want to show how the plumbing works, I chose to use copies of the sample code Alex showed in his blog post.  In this case, I extracted from https://alexmg.com/author/Alex-Meyer-Gleaves.aspx two classes: AutofacWebApiDependencyResolver and AutofacWebApiDependencyScope.  I created an Autofac folder and added these 2 classes verbatim from Alex’s post.  That way, when I eventually take a dependency on a version of Alex’s package using shipping bits, I can just remove these classes from my app.

Wiring up the Autofac DependencyResolver

At this point, all the moving parts are in place, and all that’s left is telling WebApi to use them.   This is done by registering an IDependencyResolver with WebApi.  The in’s and out’s of IDependencyResolver are described in greater detail in Brad Wilson’s post.  Because Alex’s AutofacWebApiDependencyResolver implements IDependencyResolver, all we need to do is instantiate it and wire it into the HttpConfiguration.   The normal place to alter the HttpConfiguration is in the App_Start\WebApiConfig class provided by the project template. 

Here is all the code we need to add to complete the wiring up of Autofac.  We’ll investigate each step separately.

   1: public static void Register(HttpConfiguration config)

   2: {

   3:     config.Routes.MapHttpRoute(

   4:         name: "DefaultApi",

   5:         routeTemplate: "api/{controller}/{id}",

   6:         defaults: new { id = RouteParameter.Optional }

   7:     );

   8:  

   9:     var builder = new ContainerBuilder();

  10:  

  11:     builder.RegisterInstance<IPostRepository>(new InMemoryPostRepository());

  12:  

  13:     builder.RegisterAssemblyTypes(

  14:         Assembly.GetExecutingAssembly())

  15:             .Where(t => 

  16:               !t.IsAbstract && typeof(ApiController).IsAssignableFrom(t))

  17:             .InstancePerMatchingLifetimeScope(

  18:                AutofacWebApiDependencyResolver.ApiRequestTag);

  19:  

  20:     var container = builder.Build();

  21:  

  22:     var resolver = new AutofacWebApiDependencyResolver(container);

  23:     config.DependencyResolver = resolver;

  24: }

At this point we’re done!  We could use F5 and start running this app.  But I think it’s worthwhile to look at these steps in more detail.

The first step was already created for us by the default WebApi template, so we leave it alone.  It sets up the basic route information to be allow our ApiControllers to be called.

   1: config.Routes.MapHttpRoute(

   2:     name: "DefaultApi",

   3:     routeTemplate: "api/{controller}/{id}",

   4:     defaults: new { id = RouteParameter.Optional });

The next steps do the following:

1. Create a new Autofac container builder
2. Scan the current assembly for all ApiController types and register them with the container builder with a per-request lifetime
3. Ask the container builder to create the DI container

   1: var builder = new ContainerBuilder();

   2:  

   3: builder.RegisterAssemblyTypes(

   4:     Assembly.GetExecutingAssembly())

   5:         .Where(t => 

   6:            !t.IsAbstract && typeof(ApiController).IsAssignableFrom(t))

   7:         .InstancePerMatchingLifetimeScope(

   8:            AutofacWebApiDependencyResolver.ApiRequestTag);

   9:  

  10: var container = builder.Build();

Alex’s Autofac.WebApi Nuget package actually does the assembly scanning for you, but because this example does not use his bits, I do it here manually.

The next step wraps Alex’s IDependencyResolver around that container and registers it with WebApi:

   1: var resolver = new AutofacWebApiDependencyResolver(container);

   2: config.DependencyResolver = resolver;

And finally, here is the critical step that provides our IPostRepository implementation:

   1: builder.RegisterInstance<IPostRepository>(new InMemoryPostRepository());

In this case, we created an IPostRepository implementation to keep posts in memory.  We would use a database or blob store in a real application.

How it works

In a nutshell, it works because the Autofac DI container knows which constructors are available for BlogController, and it knows which constructor parameters can be satisfied using other instances in the DI container.

If you’re curious about the detailed steps, here they are:

1. An Http request is received by WebApi.  Say it is something like a POST to https://localhost:43347/api/blog
2. WebApi uses route information to understand the request is directed to the BlogController
3. The WebApi IHttpControllerActivator extension point is called to create an instance of BlogController
4. The default controller activator asks the registered IDependencyResolver for a new IDependencyScope (think of it as the per-request DI container).  In this case, it calls AutofacWebApiDependencyResolver.BeginScope().
5. The default controller activator then asks the IDependencyScope for an instance of type BlogController
6. Autofac has analyzed the BlogController and understood it has a constructor that accepts an IPostRepository
7. Autofac also recognizes an IPostRepository instance is available from the DI container
8. Autofac invokes the BlogController(IPostRepository) constructor, passing it the IPostRepository instance from the container.
9. WebApi carries on with the controller instance to invoke the appropriate BlogController method – in this case the Add() method.
10. When WebApi is done servicing the request, it disposes the IDependencyScope, thereby telling the per-request DI container it can dispose its instances.  This is how the BlogController instance is disposed.

Incidentally, the default ValuesController is also instantiated the same way.  But because it has only a parameterless constructor, that is the one used.

If you wanted to add new ApiControllers to this app that accept an IPostRepository, they would just work.  If you wanted to add new ApiControllers requiring other kinds of constructor parameters, you would just need to put instances of those parameters into the DI container as we did with the “RegisterInstance” method above.

Try it out

We can try out our new BlogController in action using Fiddler.  Use F5 to launch the app, wait for the Home screen to appear, and use Fiddler to POST a request like the one shown below.  This will invoke BlogController.Add() to add the post to our in-memory repository.

We can then turn around and issue a GET which will call BlogController.Recent() to extract the most recent posts.

Summary

In this article, we’ve explored how add an Autofac-based IDependencyResolver to WebApi for the express purpose of being able to create an ApiController with custom constructor parameters.  But obviously there are many ways you can use DI to build a loosely-coupled (and testable!) application.   Hopefully this article gives you some ideas where to start.

In addition to the Autofac DI container used here (https://nuget.org/packages/Autofac.WebApi) there are other DI containers available, including:

https://nuget.org/packages/Ninject.Web.WebApi

https://nuget.org/packages/Unity.WebAPI

Overview

Tracing in this context means a notification mechanism that allows framework and application code to say things like “Object X is now performing operation Y” or “Object X encountered exception Z when performing operation Y.”

Tracing in Web API is done via the ITraceWriter interface described below. Both framework and application code can trace through ITraceWriter, allowing framework and user traces to be written to the same destination and to be correlated against the same Http request.

Each trace notification is captured in a TraceRecord instance created by the ITraceWriter implementation. Code asking to trace is responsible for filling in the details of that TraceRecord.

Every trace notification must specify the Http request, a category (string) and a trace level (enum).

The Http request is required so that all traces can correlate to the single request that caused that code to run.

The category is an arbitrary string that has meaning to the developer or to the framework. A typical trace category is “System.Web.Http.ModelBinding.” The category has no particular meaning to the WebApi product – it is merely captured in the TraceRecord. We’ll see below how ITraceWriter implementations can make decisions based on this category.

The trace level is one of the TraceLevel enum values. It also has no particular meaning to the WebApi product, but may have meaning to the ITraceWriter implementation. Like category, this value is simply captured in the TraceRecord.

All attempts to trace are conditional, subject to the ITraceWriter implementation. For example, code may say “I want to trace some information at level Info, category ‘MyCategory’”. The ITraceWriter implementation may decide that level and/or category are not currently enabled, and that trace attempt will be ignored.

What is available “in the box”

The Web API framework exposes the public ITraceWriter interface and an internal tracing layer I’ll talk about shortly.

However, Web API does not provide any ITraceWriter implementations in the box. Our intent is that the user community will develop ITraceWriter implementations that bridge to other products, such as ETW, System.Diagnostics, NLog, Log4Net, Elmah, etc.

How to enable tracing in your app

Tracing is off by default in Web API. To enable it, you must register some ITraceWriter implementation as a service.  The presence of an ITraceWriter service is what activates WebApi framework code to trace to it..

In a self-hosted environment, registering a trace writer would look like this:

   1: HttpSelfHostConfiguration config = new HttpSelfHostConfiguration(myUri);

   2: config.Services.Replace(typeof(ITraceWriter), new MyTraceWriter());

   3: HttpServer server = new HttpSelfHostServer(config);

In a web-hosted environment, it would look like this (in Global.asax.cs):

   1: protected void Application_Start()

   2: {    

   3:     HttpConfiguration config = GlobalConfiguration.Configuration;

   4:     config.Services.Replace(typeof(ITraceWriter), new MyTraceWriter());

   5: }

Creating an ITraceWriter implementation

The ITraceWriter interface

The only public API a trace writer must implement is ITraceWriter.

   1: public interface ITraceWriter

   2: {    

   3:     void Trace(HttpRequestMessage request, 

   4:                string category,

   5:                TraceLevel level, 

   6:                Action<TraceRecord> traceAction);

   7: }

The ITraceWriter contract

The ITraceWriter API has only a single method Trace().  Its parameters are:

• request – the HttpRequestMessage with which to associate the trace information.
• category – a user defined string specifying the category to associate with this trace.  The WebApi framework uses category names that match its namespaces, but developers can use whatever category names make sense to them.   Using a dotted name (“MyApplication.DataModel.Management”) generally integrates best with existing logging tools.
• level – an enumeration specifying the severity level of the trace (see below).
• traceAction – an Action callback that accepts a TraceRecord  (see below).   This action is provided by the caller and will be invoked only when the trace writer implementation decides it is configured to capture traces at the specified category and level.

The decision when to call traceAction for more details is entirely up to the trace writer implementation.  Existing logging mechanisms generally support category hierarchies and may choose to match some prefix of the given category.  Also they may to filter the severity level, such as all traces at level Warn and above.   WebApi does not provide any way to configure trace writers regarding their current category or level.

The Trace() method is responsible to do these things:

• Determine whether tracing is enabled for the given category and level..
• If not enabled, return immediately without calling the caller’s traceAction
• If enabled:

- Allocate a new TraceRecord (which may be a derived type for that trace writer)

- Invoke the caller’s traceAction, passing the new TraceRecord to allow the caller to fill in the details

- Do something with that completed TraceRecord

The reason the Trace() method looks the way it does is to address the following problems inherent in tracing:

• Performance -- beginning trace users are often tempted to fetch resources eagerly and to format strings before discovering their trace will be ignored. This is a guaranteed performance killer.  The Trace() method uses a callback pattern to encourage the user code to evaluate its trace information lazily only when it will be used.
• Exception protection – the code asking to trace may encounter an exception creating its information. For example, it might use a String.Format() with an incorrect number of parameters. Few applications think to protect all their traces with try/catch or to unit test all their tracing statements, effectively leaving latent fatal exceptions in their app. The Trace() pattern allows the ITraceWriter implementation to use its own try/catch to protect the application and to report a problem in the user’s tracing code as it chooses.
• Creation and lifespan of TraceRecord – some tracing products ask callers to create the equivalent of a TraceRecord before calling the tracing layer. That has 2 problems – it means the record class itself cannot be subclassed, and the lifespan of that record is ambiguous. What happens if I change a field in that record after I ask to trace it? Am I required to dispose it?  Because the Trace() method is responsible for creating the TraceRecord, we achieve these benefits:

- The trace writer can avoid creating a TraceRecord unless it knows it will use it.

- The trace writer can avoid calling the user’s traceAction unless it knows it will use its information

- The trace writer can create derived TraceRecord types that contain additional implementation-specific information.

- The caller sees the TraceRecord only inside its traceAction callback and is therefore discouraged from holding onto it.

- The disposal of the TraceRecord, if required by the trace writer, is under the trace writer’s control.

 

The TraceLevel enumeration

All traces are associated with a severity level.  The interpretation of what these levels mean is entirely up to the trace writer implementation.   WebApi does not interpret them in any way.  This enumeration maps to values commonly used by diagnostic and logging tools, and the values are ordered the way these tools generally use them (example: “if (level >= TraceLevel.Warn)…”).

   1: public enum TraceLevel

   2: {

   3:     Off = 0,

   4:     Debug = 1,

   5:     Info = 2,

   6:     Warn = 3,

   7:     Error = 4,

   8:     Fatal = 5

   9: }

The WebApi product code currently traces normal activity at Info level.  Situations that may cause a downstream failure, such as a model binding error, trace at the Warn level.  All exceptions caught by the product tracing code traces at the Error level.

A simple ITraceWriter implementation

Here is possibly the world’s simplest ITraceWriter implementation that writes to the console.   Even though it is simple, it demonstrates how a trace writer should behave.  In this case, the contract is to write every trace request to the console.

   1: class SimpleConsoleTraceWriter : ITraceWriter

   2: {

   3:     public void Trace(HttpRequestMessage request, string category, 

   4:                       TraceLevel level, Action<TraceRecord> traceAction)

   5:     {

   6:         TraceRecord traceRecord = new TraceRecord(request, category, level);

   7:         traceAction(traceRecord);

   8:         ShowTrace(traceRecord);

   9:     }

  10:  

  11:     private void ShowTrace(TraceRecord traceRecord)

  12:     {

  13:         Console.WriteLine(

  14:             String.Format(

  15:                 "{0} {1}: Category={2}, Level={3} {4} {5} {6} {7}",

  16:                 traceRecord.Request.Method.ToString(), 

  17:                 traceRecord.Request.RequestUri.ToString(), 

  18:                 traceRecord.Category,

  19:                 traceRecord.Level,

  20:                 traceRecord.Kind,

  21:                 traceRecord.Operator,

  22:                 traceRecord.Operation,

  23:                 traceRecord.Exception != null

  24:                     ? traceRecord.Exception.GetBaseException().Message

  25:                     : !string.IsNullOrEmpty(traceRecord.Message)

  26:                         ? traceRecord.Message

  27:                         : string.Empty

  28:             ));

  29:     }

  30: }

Adding this SimpleConsoleTraceWriter to HttpConfiguration.Services will cause all user and framework traces to be displayed on the console.  I’ve found that even as simple a trace writer as this is valuable in understanding the Web API framework itself.   It reveals the execution flow through the framework, including error paths.  This kind of tracer is also useful for debugging your application, because you see exactly where in the execution flow things go awry.

Here is a sample of what this trace writer displays for a single request:

What information gets traced

The unit of tracing is the TraceRecord created by the ITraceWriter.Trace() method.

Some of the properties are pre-initialized by the constructor, but when ITraceWriter.Trace() calls the caller’s traceAction the caller is responsible for filling in all the other properties it wishes to trace.   It is permitted to leave some properties not set, and trace writer implementations must tolerate this.

Here is the current definition of TraceRecord:

 1: public class TraceRecord

 2: {

 3:     public TraceRecord(HttpRequestMessage request, 

 4:                        string category, TraceLevel level)

 5:     {

 6:         Timestamp = DateTime.UtcNow;

 7:         Request = request;

 8:         RequestId = request != null ? request.GetCorrelationId() : Guid.Empty;

 9:         Category = category;

 10:         Level = level;

 11:     }

 12:  

 13:     public string Category { get; set; }

 14:     public Exception Exception { get; set; }

 15:     public TraceKind Kind { get; set; }

 16:     public TraceLevel Level { get; set; }

 17:     public string Message { get; set; }

 18:     public string Operation { get; set; }

 19:     public string Operator { get; set; }

 20:     public Dictionary<object, object> Properties {get; }

 21:     public HttpRequestMessage Request { get; private set; }

 22:     public Guid RequestId { get; private set; }

 23:     public HttpStatusCode Status { get; set; }

 24:     public DateTime Timestamp { get; private set; }

 25: }

What the framework traces

The framework traces most of the main services registered in the HttpConfiguration.Services.  It also traces the execution flow of objects returned from any of these services’ methods.  For example, the registered IContentNegotiator is traced.   And if its Negotiate method returns a MediaTypeFormatter, then that formatter’s methods will also be traced.  You can see that in action in the console output above.

The framework tracing code always traces both a Begin and an End trace (TraceKind.Begin and TraceKind.End) bracketing the start and finish of each operation. In the example above, there is a Begin trace for DefaultContentNegotiator.Negotiate(), showing when the framework entered that code. And there is also an End trace showing when DefaultContentNegotiator.Negotiate(), completed, either successfully or not. If completion is unsuccessful, the exception associated with failure is written into the TraceRecord.

The framework code traces the public and protected entry points of each service, regardless whether that service is a default provided by Web API or is user code that replaced the default service.   In this way, user code replacing a default service will also be traced.  The user does not need to add extra tracing logic to make that happen.   The framework traces only the public and protected entry points visible to it through the API of that service at compile time.  It is unable to trace additional public or protected methods on user-defined types.

How to trace from user code

This piece of code demonstrates how a trace is done at the lowest level, namely interacting directly with the ITraceWriter API:

 1: ITraceWriter writer = Configuration.Services.GetTraceWriter();

 2: if (writer != null)

 3:     writer.Trace(

 4:         Request, "MyCategory", TraceLevel.Debug,

 5:         (traceRecord) => 

 6:         { traceRecord.Message = 

 7:             String.Format("Inside MyMethod with param = {0}", value); } );

Notice that the ITraceWriter is retrieved from the list of services in the configuration.  It might be null if none was registered.

If it is not null, the caller asks to trace with an HttpRequestMessage, a category, and a trace level.

Possibly the most important point to observe here is that the caller also passes in an Action<TraceRecord> delegate.  This action will be called by the ITraceWriter if and only if it requires more information.  The code performing the trace is required to fill-in the given TraceRecord with whatever it wants traced.     In this example, the tracing code only wanted to add a message.  If the category or level are not being currently being traced by the ITraceWriter implementation, that Action delegate will not be called.

Both framework code and user code trace the same way.

Friendlier trace methods

The example above looks complicated because it represents the lowest level interaction possible with ITraceWriter.

But to make things easier, there are many friendlier extension methods for ITraceWriter.  For example, this code would do exactly the same thing as the code above:

 1: ITraceWriter writer = Configuration.Services.GetTraceWriter();

 2: if (writer != null)

 3:     writer.Debug(Request, "MyCategory",

 4:                  "Inside MyMethod with param = {0}", value);

The friendlier methods hide the details of the Action callback, but they evaluate the other parameters only if tracing is really enabled.   In this case, the invisible String.Format() would execute only if tracing was enabled for that category and level.

The full list of extension methods will be shown by Intellisense for ITraceWriter.

Tracing to an existing logging product

ITraceWriter is just an abstraction layer that can be used as a bridge to other 3rd party products.   The most common scenario will probably be a logging product.

For example, if you like using NLog in your applications, you would build or obtain an NLog-specific ITraceWriter.

We expect the user community to develop industrial-strength ITraceWriter implementations for popular logging products, but I'll contribute more samples in future posts.

By using a custom ITraceWriter that writes to a logging product like this, both your application code and Web API framework code will send their traces to it..

Controlling what is traced

Determining which categories and levels are currently enabled is the responsibility of the ITraceWriter implementation. The Web API framework has no concept of trace configuration or determining which categories and levels are enabled.

The intent of this approach is to rely on the ITraceWriter implementation’s own mechanisms to configure what gets traced and where.

For example, if you use an NLog-specific ITraceWriter, you should configure tracing through NLog configuration mechanisms.

Analyzing what is traced

This also is the responsibility of the ITraceWriter implementation. The Web API framework has no concept of storing traces or analyzing them,

To use the example above, if you are using an NLog-specific ITraceWriter, the trace “store” is configurable, and it will be done using NLog’s configuration options.

To analyze what is traced, you use whatever tools you normally use to analyze that store.

Tracing to ITraceWriter versus writing directly to the logging product

So suppose you have an NLog ITraceWriter that allows framework and user code to trace to NLog. Should you continue to log directly to NLog or should you call ITraceWriter.Trace()?

That is your choice, and both approaches will work. But here are some considerations when making that choice:

• Writing directly to your logger:

               Advantages:

                   - Your app may already do this

                   - You can use special features of your logger during tracing

               Disadvantages:

                   - Your app is tightly coupled to that logger implementation

                   - Your traces will not be correlated to their specific Http request unless you do it explicitly

                   - A hard dependency on a specific logger may make it difficult to integrate with community code or to contribute to it

• Writing to your logger through ITraceWriter:

                Advantages:

                     - Your app is not tightly coupled to any logger implementation.

                     - Everything traced by your code or the framework  is correlated to the same Http request

                     - Using or contributing to community code will be easier with this abstraction layer

                Disadvantages:

                     - You might need to convert app code already writing to that logger

                     - The TraceRecord might not be able to contain everything you want logged

Other uses of ITraceWriter

ITraceWriter is just an abstraction layer.  Though the most common use will be to bridge to some logging product, it can be used for different purposes.

Here are some I’ve considered or tried:

• Quick and dirty performance monitoring – because the framework traces both Begin and End for each operation, an analysis tool can measure average execution times of every framework or user operation.  A performance trace writer could expose its own ApiController allowing some dashboard UI to watch performance dynamically.
• An error reporting tool – an ITraceWriter could be written to send an email whenever a Fatal trace record was written or to integrate with existing error reporting mechanisms.
• Quick and dirty analytics – an ITraceWriter could capture basic usage information, such as which endpoints are being used, average response time, the frequency of errors, etc.  Again, it could expose its own ApiController to allow some dashboard to monitor that.
• Just-in-time tracing – you could write a “rolling” trace writer that wraps another ITraceWriter.  It could keep a small rolling buffer of traces but not forward them to the inner trace writer until some event occurred, such as an Error trace.   In this way, you could run for days without capturing a single trace, but when that special error occurs, your inner trace writer could record the traces immediately before and after the error,   This can be useful tracking down stress issues or hard-to-reproduce scenarios.
• A learning/debugging tool – even a simple console ITraceWriter can be useful when learning the Web API execution sequence or in debugging an app (e.g. “Why is my action’s parameter not properly model bound?” or “Why am I getting back Json instead of my custom media type?” or “When is an exception filter called?”)
• Testing – spy or mock ITraceWriter test doubles can be useful to assert your trace statements are correct or to inject faults or delays into the running app,  An ITraceWriter that unconditionally invokes the Action<TraceRecord> callback is also a great way to flush out any buggy trace statements that throw.

Tracing to multiple trace writers

As you can see by the examples, tracing code expects only a single ITraceWriter in HttpConfiguration.Services.   But what if you want more than one?

Consider this scenario:

• The developers write application code that traces to ITraceWriter
• At deployment time, the team decides they want framework and application traces to go a persistent store they can view remotely.
• The team also decides they want errors to be reported to Elmah
• The test team decides to use ITraceWriter to inject faults and delays when the app is used in a test environment

The easiest way to approach this is to create a single aggregating ITraceWriter that discovers the presence of these multiple writers and delegates the IsEnabled() and Trace() calls to them.

Web API does not provide an aggregating ITraceWriter, but writing one should not be difficult.

How framework tracing works behind the scenes

I mentioned above that the Web API framework will trace to whatever ITraceWriter is found in HttpConfiguration.Services. What I didn’t mention was the slightly unusual approach we took to implement this. When no ITraceWriter is found, no tracing occurs from the framework for this simple reason -- the core Web API framework contains no code aware of tracing!

Most framework implementations I have seen sprinkle tracing statements throughout their code. These are usually bracketed with “are you enabled?” tests to avoid a performance penalty. I think of this as the “trace from the inside out” approach. It’s fairly straight forward but suffers these drawbacks:

• It might not trace what the developer wants to see
• Any user-written extensions must also remember to trace or there is no record of their execution
• There is almost always at least some overhead even when tracing is disabled
• Such framework code is often tightly coupled to a specific tracing framework
• It may not be possible for user code to write to that tracing framework
• It is usually not possible to redirect the framework traces to an alternate tracing framework

Web API took a different approach that I call “trace from the outside in.” It works this way: if Web API determines during startup that an ITraceWriter is registered, it wraps a trace-aware object around services registered in the HttpConfiguration.Services and then replaces the original service with this trace-aware wrapper.

These trace-aware wrappers override the public and protected entry points of their respective wrapped service so that they can trace the Begin, then invoke the wrapped service, and then trace the End. They also wrap a try/catch around the wrapped-object’s method to trace error paths.

This approach has these benefits:

• If you don’t want tracing, you don’t pay for it
• All framework services trace using the same Begin/End pattern
• User-written code replacing framework code will trace automatically
• The user can redirect where framework code traces
• This approach establishes that the primary extensibility points in Web API are factored into small enough polymorphic chunks that they can be overridden and observed.

The framework tracing code is internal, so you cannot override it to change the way it traces. However you can replace the entire tracing layer altogether by replacing the ITraceManager in the HttpConfiguration.Services. But that is a subject for another post.

Conclusions

This post was an overview of how tracing works in Web API, and I hope you have a sense of how to use it to trace from your code and to capture what the framework is tracing.

In future posts I’ll explore some ITraceWriter implementations and offer some samples.