Image Resizer Documentation

This is regarding a deprecated version. Visit the V3 website for the latest documentation.
Installation is quick and simple, provided you follow the steps carefully. 99% of problems users encounter are due to skipping a step. 1) Copy and paste ImageResizer.dll and ImageResizer.pdb into the /bin directory of your app. Alternatively, you can copy the inner ImageResizer folder (which contains .cs files) into /App_Code. This second approach allows modification of CustomFolders.cs and Watermark.cs. 2) Copy and paste the settings at the bottom of the page into web.config to configure the module. 3) Users of 2.1+, you're done! You can now resize images using the "image.jpg.ashx?width=500" syntax. For versions prior to 2.1, or for users wanting the cleaner "image.jpg?width=500" syntax, some additional IIS configuration is needed. Upgrading? Read the v1.0-v1.2, v1.2 to v2.0v2.0-v2.1, or v2.1b-v2.6 upgrade notes instead.


You will need to insert the following settings into web.config in the designated places.
    <add name="ImageResizer" type="fbs.ImageResizer.InterceptModule"/>
  <validation validateIntegratedModeConfiguration="false"/>
    <add name="ImageResizer" type="fbs.ImageResizer.InterceptModule"/>
Last, some app settings for the resizer. You can use the following safely with v2.1 and up. Full configuration reference and notes for other versions can be found in the next section.
    <add key="ImageDiskCacheDir" value="imagecache" />
    <add key="MaxCachedImages" value="30000" />
    <add key="ImageResizerMaxWidth" value="1680" />
    <add key="ImageResizerMaxHeight" value="1680" />
    <add key="ImageResizerClientCacheMinutes" value="1440" />
    <add key="AllowURLRewriting" value="true" />
    <add key ="ResizeExtension" value=".ashx"/>

Complete reference

 <!-- The directory to store cached version of images. Relative to the application root.
If you want the cache outside the application, use a
Virtual Folder in IIS to point the physical location elsewhere. -->
<add key="ImageDiskCacheDir" value="imagecache"/>

<!-- How many files to keep in the cache. The 10% least recently used files
will be deleted when this limit is reached. Don't set this lower than the
number of images on your site. 2x the image count is a good default. 
If you are getting "Access Denied" messages, this is the cuplrit - you need to 
increase it -->
<add key="MaxCachedImages" value="30000" />

<!-- The following settings are optional: -->

<!-- The maximum size to permit images to be resized to. -->
<add key="ImageResizerMaxWidth" value="1680" />
<add key="ImageResizerMaxHeight" value="1680" />

<!-- Takes effect in version 1.2+. The default (for all versions) 
is 1440 minutes (24 hours). Set to 0 to disable *client* caching 
(304 "Not Modified" responses will still be returned if nothing has changed). 
Client caching is not related to disk caching. -->
<add key="ImageResizerClientCacheMinutes" value="1440" />

<!-- This enables /resize(x,y,f)/image.jpg notation in v1.2+. Enabling this
will make URL authorization ineffective on image files. 
Changed to AllowURLRewriting in 2.0-->
<add key="AllowFolderResizeNotation" value="true" />

<!-- This enables /resize(x,y,f)/image.jpg notation and other CustomFolders.cs
rewriting (other than querystring-only changes) in v2.0. Enabling this
will make URL authorization ineffective on image files on versions prior to 2.1b.-->
<add key="AllowURLRewriting" value="true" />

<!-- Enable only for debugging! (v2.0a+ only) 
Prevents use of cached files - Required for seeing results 
when changing the resizing algorithms.
Causes terrible performance - don't leave enabled.-->
<add key="DiskCacheAlwaysInvalid" value="false"/>

<!-- (v2.0b+ only) Prevents the cache cleanup routine from running. If you want to
manually purge the image cache yourself, and aren't worried about running out
of disk space via a DOS attack, you can disable this. Not advised. -->
<add key="DisableCacheCleanup" value="false"/>

<!-- (v2.1+ only) Disabling custom quantization allows the resizer to function in low trust
environments where managed pointer access and data type marshaling is prohibited.
However, PNGs and BMPs can only be output in 32-bit mode, and GIFs will use the default
halftone pallete. Enable this if JPGs and PNGs work, but GIFs don't, and using colors=255
on PNGs causes them to break also.
Causes much lower quality GIFs to be generated.
Version 2.1+.
<add key ="DisableCustomQuantization" value="false"/>

<!-- (v2.1b+ only) This allows images to be resized without any
IIS configuration whatsoever (AllowURLRewriting must be true, however).
Just set this value to ".axd", ".ashx", ".aspx", or any extension
already registered in IIS, and add the same extension to your image URLs
when you are resizing them. Doesn't conflict with other pages/files with 
that extension, unless you name them .jpeg.ashx., etc.
When configured properly in IIS, any extension should work, but ".ashx" 
seems to be configured right on the largest number of servers.
Ex. /images/media/flower.jpg -> /images/media/flower.jpg.axd?width=x&height=y  
<add key ="ResizeExtension" value=".ashx"/>

<!-- v2.6+ Disables the additional URL authorization checks 
performed by the resizer after URL rewriting. -->
<add key="DisableImageURLAuthorization" value="false"/>
<!-- v2.2+ Enables use of registired VirtualPathProviders.
Inherently stops modified date checking.
(i.e, cached files are never updated, unless the VirtualFile
implements IVirtualFileWithModifiedDatae). -->
<add key="ImageResizerUseVirtualPathProvider" value ="false"/>
<!-- v2.5+ Only executes the virtual path provider if the physical file doesn't exist -->
<add key="ImageResizerUseVirtualPathProviderAsFallback" value ="false"/>

<!-- v2.3+ When set to a non-empty value, divides the cache into the
specified number of subfolders. MUST be a power of two, or it will get 
rounded up to the next power of two, which might be VERY different from 
the configured value. Values above 8096 are not suggested for best NTFS performance. 
Suggested value is (MaxCachedImages / 7500).  Remember to delete the imagecache
folder every time you change this value - otherwise lots of orphaned files will be there.
<add key="ImageCacheSubfolders" value="8"/>

Published on

About Nathanael

Nathanael Jones is a software engineer, father, consultant, and computer linguist with unreasonably high expectations of inanimate objects. He refines .NET, ruby, and javascript libraries full-time at Imazen, but can often be found on stack overflow or participating in W3C community groups.


If you develop websites, and those websites have images, ImageResizer can make your life much eaiser. Find out more at


I run Imazen, a tiny software company that specializes in web-based image processing and other difficult engineering problems. I spend most of my time writing image-processing code in C#, web apps in Ruby, and documentation in Markdown. Check out some of my current projects.

More articles