jeroenhildering.com

Identity Propagation with .NET Core 2

Jeroen — Mon, 23 Jul 2018 20:35:54 GMT

Enterprises continue to move from big monoliths to a microservice oriented architecture. Of course, this has lots of advantages over having one or more big monoliths in terms of scalability, maintainability and so forth. When moving to a microservice oriented architecture, one obstacle to overcome is identity authentication and authorization.

Most of the time, the propagation of the end user security context tends to stop at the API gateway layer, and a more generic security mechanism such as a service account, with basic authentication for example, steps in to secure traffic between microservices. In that case there is no way of telling if an end user is allowed to access a specific resource. This also introduces the risk of resources getting exposed due to service accounts which might have super-user privileges. So, a better solution would be to propagate the end user security context to every microservice that is being called during the lifetime of the request.

Securing each step

Typically, in such an architecture you would have one or multiple identity providers which can issue tokens to end users. Usually this is done using OpenID Connect, OAuth or JSON Web Tokens. Either way, these tokens are usually put in the Authorization header of the request. When the request is received by the first microservice, it would check if this token is a valid token at the identity provider and otherwise throw a HTTP 401/403 if not.

When that microservice has to make a request to another microservice to fetch additional data to construct the resource, the token has to be propagated to that other microservice as well. Most of the time the token is fetched from the authorization header at controller level and passed on to the method making the call to the next microservice. However, this makes the code completely dependent on passing tokens which you most likely don't want. To overcome this problem I've made a DelegatingHandler which can be used by any instance of HttpClient:

public class AuthorizationHeaderHandler : DelegatingHandler  
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public AuthorizationHeaderHandler(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    protected override Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        if (_httpContextAccessor.HttpContext.Request.Headers.TryGetValue(HeaderNames.Authorization, out var authHeader))
        {
            request.Headers.Authorization = AuthenticationHeaderValue.Parse(authHeader);
        }

        return base.SendAsync(request, cancellationToken);
    }
}

The AuthorizationHeaderHandler will propagate the incoming token to request that is made using the HttpClient that implements this handler. To get that token we have to access the current HttpContext. Because we can't access HttpContext in .NET Core outside a controller, there is a helper class called HttpContextAccessor which we can use to access the current HttpContext. The AuthorizationHeaderHandler uses this helper class to get the authorization token from the current request headers and put it on the outgoing request just before it is send.

Now to add this delegating handler to any HttpClient, using the new HttpClientFactory that is available as of .NET Core 2, can be done in like so:

services.AddHttpContextAccessor();  
services.TryAddTransient();  
services.AddHttpClient("AuthorizedClient")  
    .AddHttpMessageHandler();

For this example i've used a named HttpClient. The AuthorizationHeaderHandler has to be added as Transient dependency in order for it to be available to the HttpClientFactory. Note that there is an extension method available to add the HttpContextAccessor dependency.

When making a request to another microservice, for example:

public class Foo  
{
    private readonly IHttpClientFactory _httpClientFactory;

    public Foo(IHttpClientFactory httpClientFactory)
    {
        _httpClientFactory = httpClientFactory;
    }

    public async Task Bar()
    {
        var client = _httpClientFactory.CreateClient("AuthorizedClient");

        return await client.GetStringAsync("http://somemicroserviceurl");
    }
}

The authorization header is automatically set on every request that is made using the HttpClient from the HttpClientFactory. This way the end user security context can be propagated in a clean way instead of passing tokens everywhere and making your code dependent on it.

Check out the full source code at GitHub.

Debugging decompiled .NET sources

Jeroen — Wed, 11 Oct 2017 19:47:22 GMT

Recently I decided to purchase the N2 Elite as I'm unable to get all the amiibo's out there to use with my Nintendo Switch to get extra's in some of the games I own. The N2 Elite comes with a tool called 'USB Manager Application'. As I hook up the RFID reader and fire up the application, all seems to be in working order. But when i try to load some dump files, the images seem to be broken or not found as I get a big questionmark where the image should be. Everything else works fine but the images don't. The more I load, the more questionmarks I get. It's starting to irritate me.

Maybe I can figure out the problem, so I take a closer look at the application and it's assemblies. As it turns out, they are .NET assemblies so I could possibly decompile and debug them.

Prerequisites

dotPeek
Visual Studio
A source that can be decompiled

Step 1: Decompiling the assemblies

Decompiling an assembly works best on assemblies that aren't obfuscated by any tool. As it turns out, they weren't when I tried to load them into dotPeek.

Now where to begin? I start looking around in the executable assembly, which seems to be a windows forms application, and I find a method called ShowN2EliteBanks. As I look at the decompiled source, this function most likely has something to do with showing the images that are missing. I would like to put a breakpoint at the beginning of the function and see what goes on there on runtime.

Step 2: Fire up the symbol server

As I do not possess the source code, I can't simply run the application using Visual Studio, set a breakpoint and start debugging. This is where the dotPeek symbol server comes in handy. What the symbol server in dotPeek actually does is provide symbol files for the assemblies we decompiled in the previous step. The symbol files can obviously be used for debugging purposes. The dotPeek symbol server runs on http://localhost:33417 by default. I doublecheck the settings and fire up the symbol server.

Step 2: Configure Visual Studio

To use the symbols provided by the dotPeek symbol server in Visual Studio, we need to add it. Fire up Visual Studio, navigate to Tools -> Options -> Debugging -> Symbols and add the dotPeek symbol server.

Now, we want to debug code that is not ours. This is disabled by default within Visual Studio. To enable this feature, navigate to Tools -> Options -> Debugging -> General and untick Enable Just My Code.

Step 3: Attach the debugger

Because we can't run any source code, I start up the application and hook up the Visual Studio debugger to the running process.

Step 4: Creating a breakpoint

But now what? How am I supposed to set a breakpoint when I don't have any source code available? You can add a New Function Breakpoint by pressing crtl + b or by navigating to Debug -> New Breakpoint -> New Function Breakpoint. I put in the name of the function I found in Step 1 and click OK.

Step 5: Live debugging

I push some buttons in the application hoping it will trigger the function, and suddenly BOOM.

The breakpoint was hit! Now I'm able to do some debugging as I normally would.

Recap

The problem turned out to be an instance of ResourceManager that was null in the libamiibo assembly supplied with the application. After some further investigation, I found libamiibo to be open source. So I cloned the repository from github, recompiled the source code, updated the assemblies and fixed the problem.

Mapping exceptions to HTTP responses with .NET Core

Jeroen — Thu, 24 Nov 2016 09:28:39 GMT

Handling exceptions and returning the appropriate response to the application consuming your API or the user browsing your web application, is considered a best practice when developing software. Handling exceptions with .NET Core is as easy as pie. You can read all about it here. However, there are still a few downsides:

All types of exceptions are redirected to the same controller action and thus result in the same response.
All types of exceptions result in a HTTP 500 Internal Server Error.
Cross referencing logged exceptions with reported ones is still a pain.

What to do if you are building a JSON REST API? Always return the same kind of response with the same HTTP status code? Doesn't sound like a good idea, giving the consuming application a proper response with an error code and a message describing the error is probably a better solution. So what if we could map an exception to a HTTP response?

Going down the road of middleware

To be able todo this, I figured I could create some middleware that I can hook up to my pipeline to handle it like so:

app.UseResponseExceptionHandler(options =>  
{
    options.Map(HttpStatusCode.BadRequest);
    options.Map(HttpStatusCode.NotFound, 
        "The requested resource was not found.");
    options.Map(HttpStatusCode.NotAcceptable, 
        new CustomResponse { Error = "Custom error" });
});

The middleware has three ways of mapping exceptions to HTTP responses:

1. HTTP status code only

When only mapping a HTTP status code to an exception, the exception message is used in the response:

HTTP/1.1 400 Bad Request  
Content-Type: application/json

{"message":"Value cannot be null. Parameter name: param"}

2. HTTP status code with an error message.

When mapping a HTTP status code with an error message, the given error message will be used in the response:

HTTP/1.1 404 Not Found  
Content-Type: application/json

{"message":"The requested resource was not found."}

3. HTTP status code with an object.

When mapping a HTTP status code with an object, the specified object will be serialized and put in the response:

HTTP/1.1 406 Not Acceptable  
Content-Type: application/json

{"error":"Custom error"}

Unhandled exceptions

But what about exceptions we don't map? Exceptions that are not mapped will be treated as what you can call 'unhandled'. Because they are not expected to occur, a random error code is generated, logged and put in the response for easy cross referencing:

HTTP/1.1 500 Internal Server Error  
Content-Type: application/json

{
    "errorCode":"ERR_40A7DD58",
    "message":"An unhandled exception has occurred, please check the log for details."
}

The error code is default prefixed with ERR_, but is overridable through the options parameter as well as the default error message:

app.UseResponseExceptionHandler(options =>  
{
    options.ErrorCodePrefix = "ERROR_";
    options.DefaultErrorMessage = "Unknown exception, please contact the System Administrator";
});

The JSON serializer settings can also be modified by using the options parameter.

Putting it all together

To prevent your code from turning into spaghetti code, you should consider moving away from exceptions and program in a more functional way by implementing Result and Maybe objects to avoid having to throw exceptions yourself. However, exceptions like an ArgumentNullException will most likely keep existing somewhere in your code. Logging error codes and outputting them makes tracking bugs and providing feedback to end users a lot faster, resulting in better code and making users more happy. In those cases, this middleware might come in handy.

Check out the full source at GitHub.

Continuous Delivery (CD) for .NET applications using Jenkins

Jeroen — Mon, 25 Apr 2016 09:13:00 GMT

The key to delivering software more rapidly and more frequently is having a continuous delivery process which makes deploying your application as easy as pushing a button. When it's easy to deploy your application, bugfixes and new features end up in production way faster and in a more agile way than the old fashion way of manually creating a package and handing it over to someone from the ops team who would then deploy it to the requested environment.

Delivering software the old fashion way is often prone to human error and takes a lot more time forcing developers to create bigger releases with a larger number of features and bugfixes which in turn also takes more time. This is obviously bad for business because end-users will have to wait much longer to be able to enjoy new releases, and in the meantime they could be getting frustrated by potential bugs which aren't going to be resolved very quickly.

One-click deploy

The main goal is to be able to deploy our application by the click of a button. To do that, we're going to be using Jenkins and add a deployment process to our previous CI job to deploy our application to Microsoft Azure.

Prerequisites

Follow my previous blogpost to create a continuous integration job using Jenkins.
Create a Microsoft Azure Account.
Create a new Azure App Service in the Azure portal.
Create a shared network location or setup an Artifact Repository to store the build artifact.
Install the Promoted Builds plugin for Jenkins.

We're going to use the Promoted Builds plugin to create a build artifact of our application and deploy it to Azure via Web Deploy. Because the Azure App Service we've created already supports Web Deploy, there is no need to install it. In this case Azure is our production environment. I recommend also having a development, test and acceptance environment to be able to test and preview your application before it gets deployed to production.

Artifact repositories

Because we're creating a build artifact, it is wise to store that artifact in a binary repository or on a shared location. This way you're not only able to keep track of all your releases, but also to rollback a previous version. There are a few good repositories out there such as Archiva, Artifactory, Nexus and Package Drone. Here is a good comparison chart for you to decide which repository suits you best.

Step 1: Create a promotion process

Navigate using your favorite browser to the Jenkins job you've created and tick the Promote builds when... checkbox. The following section appears:
In this case we're going to create the process of deploying our application to a production environment so the name of this process is going to be Production. Tick the Only when manually approved checkbox because we don't want to trigger the process automatically.

Typically you can tick the Promote immediately once the build is complete checkbox for a development promotion process. This means that when a build is succeeded and all unit tests pass, a build artifact is created immediately and is then deployed to the development environment.

If you have multiple promotion processes, i recommend ticking the When the following upstream promotions are promoted checkbox and fill in the previous promotion process name (e.g. Acceptance) that has to be successfully executed before being able to approve the next promotion process. This way you will force your application being deployed to other environments first such as development, test and acceptance before reaching production. An example would be Development > Test > Acceptance > Production.

Step 2: Create a build artifact

To create a build artifact click the Add action button in the Actions region of your promotion process and select Build a Visual Studio project or solution using MSBuild:
This step is almost equal to our build step which we created in our CI process, but now we're going to create a web deploy package in stead of compiling the solution. To create that package, we have to add a few command line arguments:

/T:Clean;Build;Package to create a Web Deploy package.
/p:Configuration=Release to use the release configuration.
/p:OutputPath="obj\Release" to put the artifact in the obj\Release folder of the current project.
/p:PrecompileBeforePublish=true to precompile our application.

Step 3: Store the build artifact

Next we have to store our build artifact we've just created. In this case we will keep it simple and just copy it to a shared network location. Click the Add action button again and select Execute Windows batch command:
Because we're just copying the artifact to another location, i've created a xcopy command that copies the build artifact to a specified network location and create a folder with the Jenkins build number.

Step 4: Deploy the build artifact

To be able to deploy to Azure via Web Deploy you first have to download the Publish Profile of your Azure App Service. Go to the Azure Portal, navigate to your App Service and click the Get Publish Profile button. You should get something like this:

We are going to use the Web Deploy profile in our next action. Because there is no MSDeploy plugin for Jenkins click Add action and select Execute Windows batch command:
This is a pretty large command using the MSDeploy executable, so let's go over the command line arguments:

-verb:sync to update our web application.
-source:package="YourProject\obj\Release\_PublishedWebsites\YourProject_Package\YourProject.zip" to use the build artifact for deployment.
-dest:auto,computerName='https://yourproject.scm.azurewebsites.net:443/msdeploy.axd?site=yourproject',UserName='$YourProject',Password='someRandomPassword',AuthType='Basic',includeAcls='false' to set the destination for our deployment using the data from the downloaded Publish Profile. includeAcls is set to false because we don't want to deploy file ownership information.
-setParam:name='IIS Web Application Name',value='yourproject' to override the web application name with the one specified in the Azure App Service.
-disableLink:AppPoolExtension to disable setting the AppPool because it is already set by Azure.
-disableLink:ContentExtension to disable deploying the contents of optionally configured virtual directories.
-disableLink:CertificateExtension to disable deploying optionally included certificates.

That's it for the production process. Once a build is completed and successfully passed the configured unit tests, the only thing you have to do to deploy your application is go to your build in Jenkins, click the Promotion Status button in the left option pane and click the Approve button of the promotion process you want to execute.

Rollback

But what about rollback? A similar promotion process can be created. Instead of creating and copying a build artifact, we are only going to deploy an archived artifact.

Click the button Add another promotion process and call it Rollback production. Again tick the Only when manually approved checkbox. But now we are going to add a parameter to our process by clicking the button Add Parameter and selecting String Parameter:
Because we want to rollback a specific release, we're going to use the Jenkins build number to select an artifact from the shared network location. Again click Add action and select Execute Windows batch command:
Copy the MSDeploy command from Step 4 and change the -source parameter to point to the artifact from the shared network location in stead of the one created in the obj folder: -source:package="\\neworklocation\Production\#%BuildVersion%\YourProject.zip". As you can see, the BuildVersion parameter is used in the path to point to the artifact created from that specific build. You can pass the parameter when approving your promotion process at the Promotion Status screen.

Thoughts

Instead of deploying to Azure, you could also deploy to a local server or even to a docker or windows container using an orchestration tool such as Microsoft Azure Service Fabric or Pivotal Cloud Foundry.

As i mentioned earlier, create several promotion processes for your environments. Be sure to archive artifacts if needed, as archiving development releases is not really necessary. Make promotion processes dependent on each other to ensure your application is always being deployed though your entire DTAP street before reaching production.

Continuous Integration (CI) for .NET applications using Jenkins

Jeroen — Thu, 07 Apr 2016 12:07:40 GMT

Having a Continuous Integration (CI) and Continuous Delivery (CD) process during the various stages of development helps to reduce risks, catch bugs more quickly and rapidly deploy software to various environments. These benefits result in developers being able to implement business requirements and user needs more quickly and turning the process of releasing software into a business advantage.

Tools

There are many tools out there to accommodate CI and CD for your application such as TeamCity, Jenkins, GitLab CI, Bamboo, Team Foundation Server, etc. In this case we're going to setup CI (and later on CD) using Jenkins and Atlassian Bitbucket.

Jenkins is an upcoming populair open source Continuous Integration and Continuous Delivery tool that provides you to automate builds and deployments for various programming languages. There is an extensive plugin library available that allows you to use and configure tools like MSBuild and MSTest in your job with ease.

Automate IT

To actually create and setup a job, a few prerequisites are required:

Prerequisites

Setup a VM or physical server running Windows.
Install Jenkins.
Install Visual Studio or Microsoft Build Tools.
Install Git for Windows (or any other code repository client tools).
Create a Bitbucket (or any other code repository) account and create a repository for your code.
Install the MSBuild plugin for Jenkins.
Install the MSTest plugin for Jenkins.
Install the Git plugin for Jenkins.

To compile and test your .NET application using Jenkins, MSBuild and MSTest are obviously required. I recommend installing Visual Studio which contains all the necessary tools to compile, test and measure your application rather then installing the trimmed down Microsoft Build Tools, especially if you are using the Microsoft Fakes framework in your unit tests. Installing Visual Studio Ultimate or higher next to Jenkins would be the best approach to cover that scenario so you are able to run those unit tests using Jenkins.

Configuring plugins

The installed plugins must be configured in order to use them. Go to the Configure System section in Jenkins and fill in the paths to the executables for the Git, MSBuild and MSTest plugins.

Step 1: Create a new job

To create a new job in Jenkins, navigate to the Jenkins web interface using your favorite browser and click on the New item button. This navigates to the screen below:
Fill in your project name, select Freestyle project and click OK. The Freestyle project job type consists of all the necessary elements such as SCM integration, build scripts and optional steps required for our project.

Step 2: Connect your repository

The next step is to connect your repository so Jenkins knows where to find and pull your code. Scroll down to the section Source Code Management and select Git:
Fill in your repository URL and create a user within Jenkins that has at least read access to the configured repository. In this case we will be pulling and monitoring the master branch for changes.

Now, Jenkins is not pulling code automagical, first a build trigger must be created. Bitbucket offers integration with Jenkins via webhooks or repository hooks. A hook can be made to trigger a job when SCM changes occur. I would recommend configuring a hook over polling manually to reduce the number of jobs running on Jenkins. If you want to manually poll your repository, just check the Poll SCM or Build periodically checkbox in the Build Triggers section.

Step 3: Add a build step

To actually compile your project or solution that Jenkins pulled from your repository, a build step must be created. Scroll down to the Build section, select Add build step and choose Build a Visual Studio project or solution using MSBuild. The following step is created:
Select the version of MSBuild you want to use, in this case we will use the Default one. And enter the path to the solution or project file that has to be compiled using MSBuild. In our case we are compiling YourProject.sln. The solution file is in the root of the working directory, so no additional path prefixing is required.

Step 4: Run unit tests

The last thing to do is to create a build step to run your unit tests after your code has been successfully compiled. To do this, select Add build step again and choose Run unit tests with MSTest:
Select the version of MSTest you want to use, again in our case we will use the Default one. And enter the paths to the dlls containing your unit tests.

Next step

And there you have it, a fully automated Jenkins job that pulls code from the repository when a SCM change occures, compiles it and runs unit tests. Ofcourse these are the minimal steps required to create a Continuous Integration job for your project, many other options can be configured such as pushing notifications to Slack, parameterizing builds, creating reports, etc.

The next step is to configure Continuous Delivery (CD) using Jenkins, check out my next blog post to do so.

Web API versioning

Jeroen — Fri, 26 Feb 2016 10:21:54 GMT

Let's start by saying all API's exposed to the public or to third parties should implement some kind of versioning. Why? API's tend to evolve as the world moves on, so when making changes we don't want to break stuff using our api every time we do so.

Well then, if we need versioning, what is "the right way" of implementing it? Short answer: there is none. Long answer: there are various ways of doing so, but every single one has downsides.

Most common ways of API versioning

There are lots of ways to implement versioning, below are the most common ones.

Host name versioning

In this case the version number is put in the host name:

GET https://v1.awesomeapi.com/foo/bar HTTP/1.1
Host: v1.awesomeapi.com
Accept: application/json

This can be tricky in debug mode if you are accessing raw IP addresses such as 127.0.0.1 or using IIS express to debug your application. But, this method of versioning can be usefull if you want to route incomming requests to different servers as you can create DNS records for different versions of your API.

URL versioning

This is basically putting the version number somewhere in the url:

GET https://awesomeapi.com/v1/foo/bar HTTP/1.1
Host: awesomeapi.com
Accept: application/json

If we concur that the URL should represent the resource, then that would mean every time the data is changed the api version should be changed as well. Changing the data of your resource should not affect the API version.

Query string parameter versioning

The version is put in the querystring like so:

GET https://awesomeapi.com/foo/bar?version=1 HTTP/1.1
Host: awesomeapi.com
Accept: application/json

Query string parameter versioning has pretty much the same issues as URL versioning, but also the risk of someone not specifying it. What happens if someone doesn't? The API might throw an exception or use some kind of default version you wouldn't expect.

Accept header versioning

Accept header versioning is usually done by either adding a parameter:

GET https://awesomeapi.com/foo/bar HTTP/1.1
Host: awesomeapi.com
Accept: application/json; version=1

Or by specifying a custom vendor media type:

GET /foo/bar HTTP/1.1
Host: awesomeapi.com
Accept: application/vnd.producer.product-v1+json

Accept header versioning with a parameter is generally considered as best practice, although some clients may not understand this format.

Using custom media types seems logical because you describe how you'd like the data. But, if you have a lot of entities this approach might cause a lot of kludge which can result in a lot of maintenance overtime. If you consider using custom media types, be sure to include detailed documentation about them so everyone knows how they work and what they represent.

Custom header versioning

And then there is versioning using a custom header:

GET https://awesomeapi.com/foo/bar HTTP/1.1
Host: awesomeapi.com
Accept: application/json
X-Api-Version: 1

Using a custom header is not really a semantic way of describing the resource. The HTTP spec tells us to use the accept header to describe how to present the resource the way we want it to, why reproduce this with a custom header?

Then again on using headers, it could be difficult for certain clients to set them. Imagine a JavaScript client making a JsonP call, in this case it is likely to be a real pain to set a custom header value.

One route constraint to rule them all!

Because we can't really agree on one specific type of versioning to be the best way for all clients out there, i've created a HttpRouteConstraint that supports all of the above with the exception of host name versioning. The full code is available on GitHub, the link is found at the end of this article.

By using route contraints, we can be in control of where requests are being routed to. To be able to do that, we have to create a class that implements IHttpRouteConstraint.

public class VersionConstraint : IHttpRouteConstraint  
{
    private readonly string[] _allowedVersions;

    public VersionConstraint( string allowedVersions )
    {
        _allowedVersions = !string.IsNullOrWhiteSpace( allowedVersions ) ? 
            allowedVersions.Split( new[] { ',' }, StringSplitOptions.RemoveEmptyEntries ).Select( x => x.Trim() ).ToArray();
    }

    public bool Match( HttpRequestMessage request, IHttpRoute route, string parameterName, IDictionary values, HttpRouteDirection routeDirection )
    {
        if( routeDirection != HttpRouteDirection.UriResolution ) return true;

        // Do some matching versions overhere
    }
}

The version constraint takes an allowedVersions parameter to specify which api versions should be allowed to use. Now for URL versioning, the default route should be something like this:

// Allow version to be part of the url  
config.Routes.MapHttpRoute(  
    name: "VersionedApi",
    routeTemplate: "api/{version}/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional },
    constraints: new { version = new VersionConstraint("1,2") }
);

Where the version parameter is used in the route constraint we just made. Matching the version from the URL is fairly easy by adding this to the match method:

public bool Match( HttpRequestMessage request, IHttpRoute route, string parameterName, IDictionary values, HttpRouteDirection routeDirection )  
{
    if( routeDirection != HttpRouteDirection.UriResolution ) return true;

    if( !values.ContainsKey( parameterName ) ) return false;

    return allowedVersions.Contains( values[parameterName].ToLower().TrimStart( 'v' ), StringComparer.InvariantCultureIgnoreCase );
}

To get the version from a query string parameter, a little more code is required. So i've created the following function:

private static string GetVersionFromQueryString( HttpRequestMessage request, string key )  
{
    // Get version parameter value from querystring
    return request.GetQueryNameValuePairs().Any( x => x.Key.Equals( key ) ) ? 
        request.GetQueryNameValuePairs().First( x => x.Key.Equals( key, StringComparison.InvariantCultureIgnoreCase ) ).Value : 
        null;
}

And added it to the match function:

public bool Match( HttpRequestMessage request, IHttpRoute route, string parameterName, IDictionary values, HttpRouteDirection routeDirection )  
{
    if( routeDirection != HttpRouteDirection.UriResolution ) return true;

    var version = values.ContainsKey( parameterName ) ? 
        (string) values[parameterName].ToLower().TrimStart( 'v' ) :
        GetVersionFromQueryString( request, "version" );

    return allowedVersions.Contains( version, StringComparer.InvariantCultureIgnoreCase );
}

The method checks if a query string parameter version exists, and returns the value if so. You,ve probably noticed i've made the match function prefer URL versioning over query string versioning. I will be doing the same with the other implementations as well.

Now for parsing the accept header for accept header versioning, the following function is used:

private static string GetVersionFromAcceptHeader( HttpRequestMessage request, string paramName )  
{
    if ( !request.Headers.Accept.Any() ) return null;

    foreach ( var acceptHeader in request.Headers.Accept )
    {
        // Support for application/json; [paramName]=[VERSION]
        if ( acceptHeader.Parameters.Any( x => x.Name.Equals( paramName, StringComparison.InvariantCultureIgnoreCase ) ) )
            return acceptHeader.Parameters.First( x => x.Name.Equals( paramName, StringComparison.InvariantCultureIgnoreCase ) ).Value;
        // Support for application/vnd.yourvendorname-v[VERSION]+json
        if ( !string.IsNullOrEmpty( acceptHeader.MediaType ) && 
              Regex.IsMatch( acceptHeader.MediaType, @"application\/vnd\..*-v([\d]+(\.\d+)*)\+(json|xml)" ) )
            return Regex.Match( acceptHeader.MediaType, @"(?<=-v)[\d]+(\.\d+)*" ).value;="" }="" return="" null;="" <="" code="">

The function will match application/json; version=1 as well as application/vnd.awesomeapi-v1+json. Again added it to the match method:

public bool Match( HttpRequestMessage request, IHttpRoute route, string parameterName, IDictionary values, HttpRouteDirection routeDirection )  
{
    if( routeDirection != HttpRouteDirection.UriResolution ) return true;

    var version = values.ContainsKey( parameterName ) ? 
        (string) values[parameterName].ToLower().TrimStart( 'v' ) :
        GetVersionFromQueryString( request, "version" ) ??
        GetVersionFromAcceptHeader( request, "version" );

    return allowedVersions.Contains( version, StringComparer.InvariantCultureIgnoreCase );
}

Last but not least, the custom header versioning uses the following function:

private static string GetVersionFromCustomHeader( HttpRequestMessage request, string name )  
{
    // Get version from custom header
    IEnumerable keys;
    return !request.Headers.TryGetValues( name, out keys ) ? null : keys.First();
}

Added to the match method:

public bool Match( HttpRequestMessage request, IHttpRoute route, string parameterName, IDictionary values, HttpRouteDirection routeDirection )  
{
    if( routeDirection != HttpRouteDirection.UriResolution ) return true;

    var version = values.ContainsKey( parameterName ) ? 
        (string) values[parameterName].ToLower().TrimStart( 'v' ) :
        GetVersionFromQueryString( request, "version" ) ??
        GetVersionFromAcceptHeader( request, "version" ) ??
        GetVersionFromCustomHeader( request, "X-Api-Version" );

    return allowedVersions.Contains( version, StringComparer.InvariantCultureIgnoreCase );
}

There you have it, one route contstraint that supports the four most common implementations of versioning. But wait! What about a default version? If no version is supplied you probably would want to force a default version upon your client. One way of doing this is, is by creating an AppSetting with de default version in your web.config and using that value in our VersionedRouteConstraint:

I would recommend using the lowest version of your API available as the default version. This version is the only version guaranteed not to break when changes are pushed.

Now to use the AppSetting in our RouteConstraint, i've created a private property that gets the value from the config and defaults to 1 if no setting is found:

private static string DefaultVersion  
{
    get
    {
        var defaultVersion = ConfigurationManager.AppSettings["DefaultApiVersion"];
        return !string.IsNullOrWhiteSpace( defaultVersion ) ? defaultVersion : "1";
    }
}

Added to the match method:

public bool Match( HttpRequestMessage request, IHttpRoute route, string parameterName, IDictionary values, HttpRouteDirection routeDirection )  
{
    if( routeDirection != HttpRouteDirection.UriResolution ) return true;

    var version = values.ContainsKey( parameterName ) ? 
        (string) values[parameterName].ToLower().TrimStart( 'v' ) :
        GetVersionFromQueryString( request, "version" ) ??
        GetVersionFromAcceptHeader( request, "version" ) ??
        GetVersionFromCustomHeader( request, "X-Api-Version" ) ??
        DefaultVersion;

    return allowedVersions.Contains( version, StringComparer.InvariantCultureIgnoreCase );
}

Now that all that is done, what if we want to route a specific version to a specific controller action. We can't, because we don't have a RouteFactoryAttribute that uses our newly made route constraint. So we have to make one:

public class VersionedRoute : RouteFactoryAttribute  
{
    private readonly string _allowedVersions;

    public VersionedRoute( string template, string allowedVersions ) : base( template )
    {
        _allowedVersions = allowedVersions;
    }

    public override IDictionary Constraints
    {
        get
        {
            var constraints = new HttpRouteValueDictionary {{"version", new VersionConstraint( _allowedVersions )}};
            return constraints;
        }
    }
}

Now we can do awesome stuff like this to route the request using the version constraint:

[VersionedRoute( "api/product/{id}", "v1" )]  
public Product Get( int id ) {  
    // Return some product for API v1
}

There is one but, when using custom media types with accept header versioning. When your API supports multiple formatters, we must make them aware of our custom media types so the appropriate formatter is used to serialize the response.

To make sure JSON is outputted when using the accept header application/vnd.webapiversioning-v1+json and XML is outputted when using application/vnd.webapiversioning-v1+xml using the default formatters, the media types must be added to the corresponding formatters in the Global.asax:

GlobalConfiguration.Configuration.Formatters.JsonFormatter.SupportedMediaTypes.Add(  
    new MediaTypeHeaderValue( "application/vnd.webapiversioning-v1+json" ) );
GlobalConfiguration.Configuration.Formatters.XmlFormatter.SupportedMediaTypes.Add(  
    new MediaTypeHeaderValue( "application/vnd.webapiversioning-v1+xml" ) );

GlobalConfiguration.Configuration.Formatters.JsonFormatter.SupportedMediaTypes.Add(  
    new MediaTypeHeaderValue( "application/vnd.webapiversioning-v2+json" ) );
GlobalConfiguration.Configuration.Formatters.XmlFormatter.SupportedMediaTypes.Add(  
    new MediaTypeHeaderValue( "application/vnd.webapiversioning-v2+xml" ) );

Remember that you have to do this for every version your API supports. However, these media types are not typed and do not really describe the represented resource. To be able to create typed formatters, i've extended JsonMediaTypeFormatter and XmlMediaTypeFormatter:

public class TypedXmlMediaTypeFormatter : XmlMediaTypeFormatter  
{
    private readonly Type _resourceType;

    public TypedXmlMediaTypeFormatter( Type resourceType, MediaTypeHeaderValue mediaType )
    {
        _resourceType = resourceType;
        SupportedMediaTypes.Clear();
        SupportedMediaTypes.Add( mediaType );
    }

    public override bool CanReadType( Type type )
    {
        return _resourceType == type || _resourceType == type.GetEnumerableType();
    }

    public override bool CanWriteType( Type type )
    {
        return _resourceType == type || _resourceType == type.GetEnumerableType();
    }
}

public class TypedJsonMediaTypeFormatter : JsonMediaTypeFormatter  
{
    private readonly Type _resourceType;

    public TypedJsonMediaTypeFormatter( Type resourceType, MediaTypeHeaderValue mediaType )
    {
        _resourceType = resourceType;
        SupportedMediaTypes.Clear();
        SupportedMediaTypes.Add( mediaType );
    }

    public override bool CanReadType( Type type )
    {
        return _resourceType == type || _resourceType == type.GetEnumerableType();
    }

    public override bool CanWriteType( Type type )
    {
        return _resourceType == type || _resourceType == type.GetEnumerableType();
    }
}

And then you are able to created typed formatters like this in the Global.asax:

// Add typed formatters  
GlobalConfiguration.Configuration.Formatters.Add(  
    new TypedJsonMediaTypeFormatter( typeof( Product ),
        new MediaTypeHeaderValue( "application/vnd.vendor.product-v1.0+json" ) ) );
GlobalConfiguration.Configuration.Formatters.Add(  
    new TypedJsonMediaTypeFormatter( typeof( ProductV2 ),
        new MediaTypeHeaderValue( "application/vnd.vendor.product-v2.0+json" ) ) );

GlobalConfiguration.Configuration.Formatters.Add(  
    new TypedXmlMediaTypeFormatter( typeof( Product ),
        new MediaTypeHeaderValue( "application/vnd.vendor.product-v1.0+xml" ) ) );
GlobalConfiguration.Configuration.Formatters.Add(  
    new TypedXmlMediaTypeFormatter( typeof( ProductV2 ),
        new MediaTypeHeaderValue( "application/vnd.vendor.product-v2.0+xml" ) ) );

Conclusion

If you have the luxury of being in control over the API and the client consuming it, you can choose one type of versioning that suits best for both ends. If you are not, you probably want to pick two or three variants to widely support all clients out there.

Check out the full source at GitHub.

ASP.Net MVC Flag Enumeration Model Binder

Jeroen — Fri, 28 Mar 2014 17:10:00 GMT

A while ago I ran into a problem trying to model bind a flag enumeration property where of course multiple values can be selected, so what you would like to have is a checkbox list to choose from. Apparently there is no such thing in ASP.Net MVC like a html helper method CheckBoxListFor available to use. But there is a nuget package you can download called MvcCheckBoxList, this plugin is based on an IEnumerable from which it creates a checkbox list to let the user choose from. Unfortunatly no good for binding a flag enumeration property, so I’ve created my own custom html helper and flag enumeration model binder.

To create a checkbox list from an enumeration with a html helper we have to create a new static class with a static method that returns a MvcHtmlString. In my case I’ve created a method CheckBoxListForEnum that can also be sorted alphabetically for user friendlyness:

public static class HtmlHelpers  
{
    public static MvcHtmlString CheckBoxListForEnum( this HtmlHelper html, 
        Expression> expression, object htmlAttributes = null, bool sortAlphabetically = true )
    {
        var fieldName = ExpressionHelper.GetExpressionText( expression );
        var fullBindingName = html.ViewContext.ViewData.TemplateInfo.GetFullHtmlFieldName( fieldName );
        var fieldId = TagBuilder.CreateSanitizedId( fullBindingName );

        var metadata = ModelMetadata.FromLambdaExpression( expression, html.ViewData );
        var value = metadata.Model;

        // Get all enum values
        IEnumerable values = Enum.GetValues( typeof( TValue ) ).Cast();

        // Sort them alphabetically by enum name
        if ( sortAlphabetically )
            values = values.OrderBy( i => i.ToString() );

        // Create checkbox list
        var sb = new StringBuilder();
        foreach ( var item in values )
        {
            TagBuilder builder = new TagBuilder( "input" );
            long targetValue = Convert.ToInt64( item );
            long flagValue = Convert.ToInt64( value );

            if ( ( targetValue & flagValue ) == targetValue )
                builder.MergeAttribute( "checked", "checked" );

            builder.MergeAttribute( "type", "checkbox" );
            builder.MergeAttribute( "value", item.ToString() );
            builder.MergeAttribute( "name", fieldId );

            // Add optional html attributes
            if ( htmlAttributes != null )
                builder.MergeAttributes( new RouteValueDictionary( htmlAttributes ) );

            builder.InnerHtml = item.ToString();

            sb.Append( builder.ToString( TagRenderMode.Normal ) );

            // Seperate checkboxes by new line
            sb.Append( "
" );
        }

        return new MvcHtmlString( sb.ToString() );
    }
}

This method enables you to do awesome stuff like this:

@Html.CheckBoxListForEnum( m => m.EnumProperty )  
@Html.CheckBoxListForEnum( m => m.EnumProperty, new { @disabled = true } )
@Html.CheckBoxListForEnum( m => m.EnumProperty, new { @class = "checkbox" }, sortAlphabetically = false )

which neatly creates a checkbox list based on the enum of the property from your viewmodel.

Now that our checkbox list is created we also have correctly bind the selected values to our viewmodel when posting the data to the server. To do that we have to create a custom model binder that extends the mvc DefaultModelBinder class and override the GetPropertyValue method:

public class CustomModelBinder : DefaultModelBinder  
{
    protected override object GetPropertyValue( ControllerContext controllerContext, 
        ModelBindingContext bindingContext, PropertyDescriptor propertyDescriptor, IModelBinder propertyBinder )
    {
        var propertyType = propertyDescriptor.PropertyType;

        // Check if the property type is an enum with the flag attribute
        if ( propertyType.IsEnum && propertyType.GetCustomAttributes().Any() )
        {
            var providerValue = bindingContext.ValueProvider.GetValue( bindingContext.ModelName );
            if ( providerValue != null )
            {
                var value = providerValue.RawValue;
                if ( value != null )
                {
                    // In case it is a checkbox list/dropdownlist/radio button list
                    if ( value is string[] )
                    {
                        // Create flag value from posted values
                        var flagValue = ( ( string[] )value ).Aggregate( 0, ( current, v ) => current | ( int )Enum.Parse( propertyType, v ) );

                        return Enum.ToObject( propertyType, flagValue );
                    }
                    // In case it is a single value
                    if ( value.GetType().IsEnum )
                    {
                        return Enum.ToObject( propertyType, value );
                    }
                }
            }
        }
        return base.GetPropertyValue( controllerContext, bindingContext, propertyDescriptor, propertyBinder );
    }
}

Our method filters all flag enumeration typed properties and returns a flag value created from the selected checkbox values. The only thing left to do is tell our application to use our modelbinder instead of the default modelbinder, this is done in Global.asax:

protected void Application_Start()  
{
    AreaRegistration.RegisterAllAreas();

    WebApiConfig.Register( GlobalConfiguration.Configuration );
    FilterConfig.RegisterGlobalFilters( GlobalFilters.Filters );
    RouteConfig.RegisterRoutes( RouteTable.Routes );
    BundleConfig.RegisterBundles( BundleTable.Bundles );

    // Register custom flag enum model binder
    ModelBinders.Binders.DefaultBinder = new CustomModelBinder();
}

Now I hear you thinking that those enumaration string values aren’t really user friendly. A way to solve this is to create a strongly typed resource file, put all your enumeration in there and replace builder.InnerHtml = item.ToString(); by this line: builder.InnerHtml = !string.IsNullOrEmpty( StrongResource.ResourceManager.GetString( item.ToString() ) ) ? StrongResource.ResourceManager.GetString( item.ToString() ) : item.ToString();

This renders the checkbox list with strings from the strongly typed resource instead of those ToString values.

Check out the full source code at GitHub.

Replacing WCF DataContractJsonSerializer with Newtonsoft JsonSerializer

Jeroen — Fri, 21 Mar 2014 16:50:00 GMT

Have you ever had the need to customize json serialization and deserialization of your WCF rest endpoint? I have, in particular to replace the WCF datetime format by generalized time format. By default, most json serializers serialize datetime objects to a generalized time format, this could lead to problems if you are creating a WCF rest endpoint which only supports input of microsofts datetime implementation like this \/Date(1293034567877)\/. A way to solve this problem is to replace the behavior of your rest endpoint by a custom one that uses newtonsofts json serializer instead.

To do this we have to create a message formatter class by implementing IDispatchMessageFormatter:

public class NewtonsoftJsonDispatchFormatter : IDispatchMessageFormatter  
{
    public void DeserializeRequest( Message message, object[] parameters ) { ... }
    public Message SerializeReply( MessageVersion messageVersion, object[] parameters, object result ) { ... }
}

This class will be using newtonsofts json serializer to serialize and deserialize messages. Next we have to create a behavior class that extends WebHttpBehavior:

public class NewtonsoftJsonBehavior : WebHttpBehavior  
{
    protected override IDispatchMessageFormatter GetRequestDispatchFormatter( OperationDescription operationDescription, ServiceEndpoint endpoint )
    {
        return new NewtonsoftJsonDispatchFormatter( operationDescription, true );
    }

    protected override IDispatchMessageFormatter GetReplyDispatchFormatter( OperationDescription operationDescription, ServiceEndpoint endpoint )
    {
        return new NewtonsoftJsonDispatchFormatter( operationDescription, false );
    }
}

The only thing left to do is tell the WCF endpoint to use this new behavior. One way to do that is using your web.config to connect the new behavior to your endpoint. In order to do that we have to create a behavior extension class by extending the BehaviorExtensionElement class:

public class NewtonsoftJsonBehaviorExtension : BehaviorExtensionElement  
{
    public override Type BehaviorType
    {
        get { return typeof( NewtonsoftJsonBehavior ); }
    }

    protected override object CreateBehavior()
    {
        return new NewtonsoftJsonBehavior();
    }
}

And create a content type mapper:

public class NewtonsoftJsonContentTypeMapper : WebContentTypeMapper  
{
    public override WebContentFormat GetMessageFormatForContentType( string contentType )
    {
        return WebContentFormat.Raw;
    }
}

Now when configuring your binding you can simply setup an extension like this:

Setup your enpoint behavior like this:

Configure a webHttpBinding to use our custom contentTypeMapper:

And finally setting up our endpoint like this:

Your WCF rest endpoint is now using your own message formatter to serialize and deserialize messages! There are some other cool features when using newtonsofts json serializer. For example if your service method has a byte[] parameter, you can just post a Base64 encoded string and it will be automatically deserialized to a byte[] on the server.

Check out the full source at GitHub.