CSS Resource Versioning with Microsoft ASP.NET Web Optimization

This post will demonstrate how you can easily add version tags (aka fingerprints) to file references (font, image references and so on) in your CSS style bundles when using Microsoft’s Bundling and Minification introduced in ASP.NET 4.5.

Resource versioning means that when resource files such as images and fonts are updated browsers will detect the change and retrieve the updated file from the server instead of using a locally cached older version.

With the release of ASP.NET 4.5 Microsoft added support for bundling and minifying script and stylesheet resources with the System.Web.Optimization namespace. The functionality is both easy to implement in your solution and easy to use which makes it perfect for scenarios where the requirements doesn’t call for large scale setups like using Gulp, Grunt or Cassette.

To read more about web optimization Rick Anderson has a great tutorial on the asp.net website http://www.asp.net/mvc/tutorials/mvc-4/bundling-and-minification

One thing to note though is that the support for LESS CSS relies on the dotless library that hasn’t been maintained in a long time so if you want to use LESS I recommend that you use Mads Kristensen’s excellent Web Essentials Visual Studio extension to compile the LESS files into CSS and then use the CSS files as the basis for your style bundles. This also has the added benefit of not having to add running bits to your solution to handle the LESS compilation at runtime (less moving parts means less stuff that can break).

To implement the resource versioning we need to create a bundle transform class that will locate and update all the resource references in the CSS files with a version tag based on the last write time of the resource file.

using System;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Linq;
using System.Text.RegularExpressions;
using System.Web;
using System.Web.Optimization;

namespace Common.Framework.Design.Model
{
  public class ResourceVersioning : IBundleTransform
  {
    public ResourceVersioning(String[] extensions, Boolean embedVersionTagInUrl = false)
    {
      _extensions = extensions;
      EmbedVersionTagInUrl = embedVersionTagInUrl;
    }

    public Boolean EmbedVersionTagInUrl { get; set; }

    public void Process(BundleContext context, BundleResponse response)
    {
      IEnumerable resourcePaths = ExtractResourcePaths(response);
      AddVersionTagToResourcePaths(response, resourcePaths);
    }

    private IEnumerable ExtractResourcePaths(BundleResponse response)
    {
      List paths = new List();
      const String pattern = "url\\([\"']?(.*?)[\"']?\\)";
      Regex regex = new Regex(pattern, RegexOptions.IgnoreCase);
      Match match = regex.Match(response.Content);

      while (match.Success)
      {
        String path = match.Groups[1].Value;
        String extension = path.Substring(path.LastIndexOf('.') + 1);

        if (_extensions.Contains(extension))
        {
          if (!paths.Contains(path))
          {
            paths.Add(match.Groups[1].Value);
          }
        }
        match = match.NextMatch();
      }

      return paths;
    }

    private void AddVersionTagToResourcePaths(BundleResponse response, IEnumerable paths)
    {
      foreach (String path in paths)
      {
        try
        {
          String filePath = HttpContext.Current.Server.MapPath(path);
          if (!File.Exists(filePath))
            continue;

          DateTime lastWriteTime = File.GetLastWriteTime(filePath);
          String versionTag = Math.Abs(lastWriteTime.ToString("yyyyMMddHHmmss").GetHashCode()).ToString(CultureInfo.InvariantCulture);
          String newPath;

          if (EmbedVersionTagInUrl)
          {
            Int32 lastForwardSlashPosition = path.LastIndexOf('/');
            if (lastForwardSlashPosition < 1)
              continue;

            newPath = path.Insert(lastForwardSlashPosition, "/-v" + versionTag);
          }
          else
          {
            newPath = String.Format("{0}?v={1}", path, versionTag);
          }

          response.Content = response.Content.Replace(path, newPath);
        }
        catch (Exception)
        {

        }
      }
    }

    private readonly String[] _extensions;
  }
}

First the method ExtractResourcePaths is called to extract all the resource reference paths from the CSS content. This is handled by a regex search for all occurrences of the pattern url() or url(”) and extracting the enclosed resource path. If the file extension of the located path matches one of the extensions in the extensions argument that was passed to the constructor when the transformation class was created and the path hasn’t occurred before the path is stored in a string collection.

Once all the resource paths have been extracted the AddVersionTagToResourcePaths method is called and the paths are versioned by adding a version tag based on the last write time of the resource file and the original path is then replaced with the new version tagged path in the CSS content.

How the version tag is added to the path can be controlled by the EmbedVersionTagInUrl toggle. If this is set to true the version tag will be embedded as part of the url path and if set to false (the default) the tag will be added as a querystring parameter to the path.

If you plan on embedding the version tag as part of the path you will have to use the IIS url rewrite module or some equivalent to manually remove it from the path in all incoming requests to ensure that the resource file is actually found. Mads Kristensen has written an excellent post on the topic here http://madskristensen.net/post/cache-busting-in-aspnet.

The last piece of the puzzle is to actually apply the bundle transform to your style bundle which is done when the bundle content is defined and the bundle is added to the bundle table.

String[] resourceExtensionsForVersioning = { "png", "jpg", "gif", "woff", "ttf" };

Bundle styleBundle = new StyleBundle("~/Styles/main").Include(
  "~/Design/Css/stylesheet1.css",
  "~/Design/Css/stylesheet2.css",
  "~/Design/Css/stylesheet3.css",
  "~/Design/Css/stylesheet.....css"
  );

styleBundle.Transforms.Add(new ResourceVersioning(resourceExtensionsForVersioning));
BundleTable.Bundles.Add(styleBundle);

Happy resource versioning everybody :o)