S3Reader2 plugin

Compatible with AWSSDK 2.0+

Allows images located on Amazon S3 to be processed and resized as if they were located locally on the disk.

Example URLs

  • http://localhost/s3/bucket-name/filename.jpg?width=100
  • http://localhost/s3/bucket-name/folder/filename.jpg?width=100

See Samples/S3ReaderSample/ in the download for a sample project.


  • Fast - no unnecessary http requests
  • Offers mode for checking for newer files on a configured interval (useful when combined with disk caching)
  • Works great with the DiskCache and CloudFront caching plugins
  • Has an optional ssl mode
  • Can be configured to access private bucket files with an access key


  1. Either Install-Package ImageResizer.Plugins.S3Reader2 or add a reference to ImageResizer.Plugins.S3Reader2.dll.
  2. Add <add name="S3Reader2" prefix="~/s3" region="us-east-1" buckets="my-bucket-1,my-bucket-2,my-bucket-3" /> inside <plugins></plugins> in Web.config.

Region IDs

The default region is 'us-east-1', which works for buckets in both 'us-east-1' and 'us-west-1', but not 'us-west-2' or any other buckets. Use multiple installations of S3Reader2 with different prefixes if you need to support multiple regions.

    "us-east-1", "US East (Virginia)"
    "us-west-1", "US West (N. California)"
    "us-west-2", "US West (Oregon)"
    "eu-west-1", "EU West (Ireland)"
    "ap-northeast-1", "Asia Pacific (Tokyo)"
    "ap-southeast-1", "Asia Pacific (Singapore)"
    "ap-southeast-2", "Asia Pacific (Sydney)"
    "sa-east-1", "South America (Sao Paulo)"
    "us-gov-west-1", "US GovCloud West (Oregon)"

Notes on bucket naming

When creating a bucket, you should avoid certain characters to ensure that DNS works properly. While Amazon will let you create buckets that violate some of these rules, you may have trouble accessing them using the subdomain syntax or over HTTPS. Make sure every bucket is also a valid DNS address. Read more.

  • Bucket names should not contain upper case letters
  • Bucket names should not contain underscores (_)
  • Bucket names should not end with a dash
  • Bucket names should be between 3 and 63 characters long
  • Bucket names cannot contain dashes next to periods (e.g., "my-.bucket.com" and "my.-bucket" are invalid)
  • Bucket names cannot contain periods - Amazon states this is not supported for SSL-secured access, due to DNS complications. Your mileage may vary.


You must specify a comma-delimited list of permitted bucket names that can be accessed.

If you want to access non-public bucket items, you will need to specify an access ID and key.

  • buckets (required) - Comma-delimited list of permitted bucket names that can be accessed.
  • region - Set to the region containing your buckets.
  • useSsl - Defaults to false. Set to true to transfer the image data over an encrypted connection. Decreases performance.
  • accessKeyId, secretAccessKey - Use these if you need to access non-public files in your amazon buckets.
  • bool .CheckForModifiedFiles (XML: checkForModifiedFiles="false") - Causes the modified date of the source file to be retreived. If the modified date has changed, the image will be re-downloaded and re-processed. Affects performance, as it causes a roundtrip to occur even when an image is cached. Metadata caching can minimize the request count.
  • bool .LazyExistenceCheck (XML: lazyExistenceCheck="true") - If false (the default), does not check for the existence of a file until .Open() is called. Reduces network roundtrips.
  • bool .CacheMetadata (XML: cacheMetadata="true") - Enables metadata caching to minimize roundtrips (defaults to true).
  • IMetadataCache .MetadataCache - The metadata cache to use. Defaults to StandardMetadataCache, which caches metadata for up to an hour after it was last accessed or used (sliding expiration).
  • bool .ExposeAsVpp (XML: vpp="true") - Exposes the blobs via a VirtualPathProvider, so that they can be served (when unmodified) by StaticFileHandler. Otherwise, unmodified blobs may be inaccessible.
  • string .VirtualFilesystemPrefix (XML: `prefix="~/vpp") - The virtual subfolder within which the blobs will be accessible.
  • bool .RequireImageExtension (XML: requireImageExtension="true") - If false, the blob provider will cause non-image requests to be processed by ImageResizer. Always use a file extension if possible, as otherwise the wrong content-type may served by IIS. If true, prefix may NOT overlap with any other routes or locations, as ImageResizer will be intercepting all requests within the specified virtual path.
  • bool .UntrustedData (XML: untrustedData="false") - If true, all images will be re-encoded before being served to the client. Invalid or malicious images will fail with an error if they cannot be read as images. This should prevent malicious files from being served to the client.
  • bool .CacheUnmodifiedFiles (XML: cacheUnmodifiedFiles="false" ) - If true, unmodified requests will be cached by ImageResizer (if DiskCache is installed). This can be useful if unmodified files are relatively small and the backend storage is latent.

This plugin inherits most of its functionality from BlobProviderBase, which you can use to create your own provider.

This plugin (S3Reader2 plugin) is part of the Performance Edition

Where is the plugins section?

The <plugins> section is located in Web.config, and is nested inside the <resizer> element, which is nested inside <configuration>. For examples, see this sample Web.config file.

Where can I find the dll?

We prefer that you install via NuGet, but you can also find the plugin DLL files in the /dlls/release folder of your download.

How do I typically install a plugin via Web.Config?

  1. In Visual Studio, right click on your project and choose "Add reference". Browse to the plugin DLL and click "OK".
  2. In the <plugins> section of Web.config, insert <add name="PluginName" />
  3. Look at the plugin documentation to see what configuration options (if any) are available.

How do I typically install a plugin via code?