ImageProcessingModule

The ImageProcessingModule class provides methods to perform various manipulation functions on a given image based on querystring parameters. The HttpModule is asynchronous and optimized for performance so that your website does not slow down under heavy load.

Remote Files

ImageProcessor.Web allows you to configure remote image requests from a whitelist of urls. These commands are set in the security.config file under the path \config\imageprocessor\ within your solution. The more precise the url, the more restrictive the whitelist.

Remote requests are given in the following format:

<!-- Recommended syntax as of version 4.2 Note the lack of protocol -->
/remote.axd/your-external-image?width=300

<!-- Legacy syntax -->
/remote.axd?http://your-external-image?width=300
    

Caching

ImageProcessor.Web comes with caching as standard. Any processed image are asynchronously cached both in the browser and on the server for a length of your choosing. The server cache intelligently stores millions of images and silently updates itself should the original image change or the cache expire.

Cached files, by default, are stored in nested folders based on an SHA-1 representation of the full url with a small number of images in each folder. This allows for the storage of millions of images whilst ensuring that the OS does not suffer from any slowdown due to file indexing.

The caching mechanism saves massive amounts of processing power and bandwidth that help to keep your website snappy.

Events

ImageProcessingModule.ValidatingRequest

On initial examination of an image request the ImageProcessingModule will raise an ValidatingRequest event. This allows the developer to add their own instructions to the ImageProcessingModule without requiring them to be present in the request URL. This is useful for adding extra security measures to image requests or for changing the background colour of image formats that do not support alpha transparency.

This event passes the following parameters:

sender

The instance of ImageProcessingModule raising the event.

eventargs

The ValidatingRequestEventArgs containing the following information.

Context

The current HttpContext.

Querystring

The querystring part of the current request.

Example Code

ImageProcessingModule.ValidatingRequest += (sender, args) =>
{
    if (!string.IsNullOrWhiteSpace(args.QueryString))
    {
        // Don't support alpha whatsoever
        var queryCollection = HttpUtility.ParseQueryString(args.QueryString);
        if (queryCollection.AllKeys.Contains("alpha"))
        {
            args.Cancel = true;
            return;
        }

        // If there's a crop parameter, force it to always just be a specific value
        if (queryCollection.AllKeys.Contains("crop"))
        {
            queryCollection["crop"] = "10,10,10,10";
            
            // This performs the reverse of ParseQueryString since the result of ParseQueryString
            // is actually an instance of System.Web.HttpValueCollection
            args.QueryString = queryCollection.ToString();
        }
    }
};
    

ImageProcessingModule.OnProcessQuerystring

On initial examination of an image request the ImageProcessingModule will raise an OnProcessQuerystring event. This allows the developer to add their own instructions to the ImageProcessingModule without requiring them to be present in the request URL. This is useful for adding security watermarks to images or for changing the background colour of image formats that do not support alpha transparency.

This event passes the following parameters:

sender

The instance of ImageProcessingModule raising the event.

eventargs

The ProcessQuerystringEventArgs containing the following information.

RawUrl

The raw URL of the current request.

Querystring

The querystring part of the current request.

Example Code

ImageProcessingModule.OnProcessQuerystring += (sender, args) =>
{
    if (!args.RawUrl.Contains("watermark"))
    {
        return args.Querystring += "watermark=protected&color=fff&fontsize=36&fontopacity=70textshadow=true&fontfamily=arial";
    }

    return args.Querystring;
};
    

ImageProcessingModule.OnPostProcessing

On processing of a new or updated, uncached image the ImageProcessingModule will raise an awaitable OnPostProcessing event.

This passes the following parameters:

sender

The instance of ImageProcessingModule raising the event.

eventargs

The PostProcessingEventArgs containing the following information.

CachedImagePath

The absolute path to the newly cached image.

Example Code

// Synchronous example.
ImageProcessingModule.OnPostProcessing += (sender, args) => Debug.WriteLine(args.CachedImagePath);

// Asynchronous example
ImageProcessingModule.OnPostProcessing += this.WritePath;
private async void WritePath(object sender, PostProcessingEventArgs e)
{
    // This is just for demo purposes. You would not normally use Task.Run in ASP.NET
    await Task.Run(() => Debug.WriteLine(e.CachedImagePath));
}