Update documentation; make DefaultVersioningExceptionHandler virtual

README.md

@@ -6,17 +6,15 @@ There is also a [Nuget package](https://nuget.org/packages/SDammann.WebApi.Versi
 
 ## Using the library
 ### Setting up
-In your OWIN Web API configuration delegate, put the following code. The code assumes the `config` variable is of type `HttpConfiguration`.
-
-    config.Services.Replace(typeof(IHttpControllerSelector), new VersionedApiControllerSelector(config));
-
-This will ensure the library's routines will be used for selecting the correct API controller. Also make sure to register the `DefaultControllerIdentificationDetector` and `DefaultRequestControllerIdentificationDetector` class with your dependency container.
+Register the `DefaultControllerIdentificationDetector` and `DefaultRequestControllerIdentificationDetector` class with your dependency container.
 
 Next, choose a versioning scheme and register it with the library. For example, to use versioning by API route (this will use urls like `/api/v1.2/product/`) include the following in your Web API configuration delegate:
 
-    ApiVersioning.Configure()
+    ApiVersioning.Configure(config)
                  .ConfigureRequestVersionDetector<DefaultRouteKeyVersionDetector>();
 
+ The code assumes the `config` variable is of type `HttpConfiguration`. Make sure to register this class with your dependency container.
+
 ### Choosing an API versioning scheme
 Currently the library supports two API versioning schemes.
 
@@ -29,15 +27,15 @@ This will allow the API version to be chosen by your URL routing scheme. Example
 		defaults: new { id = RouteParameter.Optional }
 	);
 
-    ApiVersioning.Configure()
+    ApiVersioning.Configure(config)
                  .ConfigureRequestVersionDetector<DefaultRouteKeyVersionDetector>();
 
 #### API versions by HTTP header
 A scheme preferred by many REST purists. This allows the API version to be chosen by using the MIME type in the Accept header of the request. In order to achieve this, inherit from `AcceptHeaderRequestVersionDetector` and implement the `GetVersionFromSingleHeader` method.
 
 Next, register your implementation in the Web API configuration delegate:
 
-    ApiVersioning.Configure()
+    ApiVersioning.Configure(config)
                  .ConfigureRequestVersionDetector<YourCustomRoutingDetector>();
 
 Don't forget to set-up your custom MIME-type in [content negotiation](http://www.asp.net/web-api/overview/formats-and-model-binding/content-negotiation) so ASP.NET Web API will output the correct response format.
@@ -55,7 +53,14 @@ Request controller naming and versioning is implemented using the `IRequestContr
 
 An API version itself is abstracted away as an `ApiVersion`. This is an abstract class that allows the concept of versioning itself to be customizable. For example, the `SemVerApiVersion` uses a one to four numbers to be used for API versions. One could easily extend this to support letters, for example as designation for 'beta' and 'alpha' by inheriting from `SemVerApiVersion` and then implement `IControllerVersionDetector` and `IRequestVersionDetector` or extend the existing implementations.
 
-## Advanced
+## Advanced concepts
+### Custom exception handling
+By default the library will properly handle exceptions that occur during controller selection itself. In some cases you may want to override or modify the error messages returned to the client by this library. You may do this in two ways:
+
+    1. Implementing a global exception handler and handle any `BaseApiException` derived exception yourself, as per [ASP.NET Web API documentation](http://www.asp.net/web-api/overview/error-handling/web-api-global-error-handling). Note that the library registers it's own exception handler, but you may wish to use your own. In that case you can always delegate any exception handling to `IVersioningExceptionHandler`.
+    2. Implement a custom `IVersioningExceptionHandler`. This exception handler is called by the library when a API versioning error occurs. You can implement your own custom response here. You can also inherit or delegate to `DefaultVersioningExceptionHandler` if you can't or won't handle an exception in certain cases.
+
+### Extending the identification of a controller
 By default, a Web API controller is identified by its version and name (in the form of a `ControllerIdentification` instance). It is possible to extend or modify this behavior. This is done by inheriting from the `ControllerIdentification` class and implementing custom versions of the `IControllerIdentificationDetector` and `IRequestControllerIdentificationDetector` interfaces or extending the default implementations. 
 
 Note this is usually not necessary, but if you'd like to go beyond names and versions you can use this approach.

src/SDammann.WebApi.Versioning/ErrorHandling/VersioningExceptionHandler.cs → src/SDammann.WebApi.Versioning/ErrorHandling/DefaultVersioningExceptionHandler.cs

@@ -2,21 +2,19 @@ namespace SDammann.WebApi.Versioning.ErrorHandling {
     using System;
     using System.Net;
     using System.Net.Http;
-    using System.Web.Http;
-    using System.Web.Http.Controllers;
     using System.Web.Http.ExceptionHandling;
     using Request;
 
     /// <summary>
     /// Represents a class that can handle exceptions thrown by the versioning system
     /// </summary>
-    public sealed class VersioningExceptionHandler : IVersioningExceptionHandler {
+    public class DefaultVersioningExceptionHandler : IVersioningExceptionHandler {
         /// <summary>
         /// Handles the specified exception by rethrowing it
         /// </summary>
         /// <param name="ex"></param>
         /// <param name="context"></param>
-        public HttpResponseMessage HandleException(ExceptionContext context, BaseApiException ex) {
+        public virtual HttpResponseMessage HandleException(ExceptionContext context, BaseApiException ex) {
             HttpResponseMessage result = null;
 
             result = result ?? HandleExceptionInternal(context, ex as ApiControllerNotFoundException);

src/SDammann.WebApi.Versioning/Internal/ServicesExtensions.cs

@@ -44,7 +44,7 @@ public static IVersioningExceptionHandler GetVersionExceptionFilter(this IDepend
                 return servicesContainer.GetServiceOrThrow<IVersioningExceptionHandler>(typeof (IVersioningExceptionHandler));
             }
             catch (InvalidOperationException) {
-                return new VersioningExceptionHandler();
+                return new DefaultVersioningExceptionHandler();
             }
         }
 

src/SDammann.WebApi.Versioning/SDammann.WebApi.Versioning.csproj

@@ -87,7 +87,7 @@
     <Compile Include="ErrorHandling\BaseApiException.cs" />
     <Compile Include="ErrorHandling\ApiVersioningExceptionHandler.cs" />
     <Compile Include="ErrorHandling\IVersioningExceptionHandler.cs" />
-    <Compile Include="ErrorHandling\VersioningExceptionHandler.cs" />
+    <Compile Include="ErrorHandling\DefaultVersioningExceptionHandler.cs" />
     <Compile Include="ExceptionResources.Designer.cs">
       <AutoGen>True</AutoGen>
       <DesignTime>True</DesignTime>