Table of Contents

Getting Started

ImageSharp.Web is easiest to understand as a request pipeline: match a source image, parse commands, process with ImageSharp, cache the result, then serve the cached bytes on later requests. This page shows the smallest setup first and then explains what the default registration gives you.

Minimal ASP.NET Core Setup

using SixLabors.ImageSharp.Web;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddImageSharp();

WebApplication app = builder.Build();

app.UseImageSharp();
app.UseStaticFiles();

app.Run();

app.UseImageSharp() must appear before app.UseStaticFiles(). If static files run first, requests such as /images/photo.jpg or /images/photo.jpg?width=400 will be served directly from disk and ImageSharp.Web will never see them.

Treat the middleware order as part of the image contract for your application. Anything registered before ImageSharp.Web can short-circuit the request before image processing happens. Anything registered after it will normally see the processed response only when ImageSharp.Web chooses not to handle the request.

What the Default Registration Includes

AddImageSharp() wires up the core middleware services plus a sensible default pipeline:

With that setup in place, requests like these are processed automatically:

/images/photo.jpg?width=400
/images/photo.jpg?width=400&height=250&rmode=crop
/images/logo.png?bgcolor=white&format=jpg&quality=85

That default configuration is intentionally opinionated for web output. Processed JPEGs use quality 75 with progressive, interleaved YCbCrRatio420 encoding, processed PNGs use BestCompression with adaptive filtering, and processed WebP output uses quality 75 with BestQuality encoding method.

The default command path is opinionated too: ImageSharp.Web transparently adds autoorient=true unless the request already contains an autoorient value. That means processed output is EXIF-normalized by default, which is especially important for WebP delivery where browser orientation support is inconsistent.

When you keep the default middleware configuration and do not return custom DecoderOptions from OnBeforeLoadAsync, the middleware also decodes with ColorProfileHandling.Convert. That normalizes embedded ICC profiles for web-oriented re-encoding instead of blindly carrying source color encodings through the pipeline.

If you later replace ImageSharpMiddlewareOptions.Configuration, you also replace those encoder defaults. If you replace OnParseCommandsAsync, you replace the default auto-orientation injection unless you explicitly preserve it. See Configuration and Pipeline for both patterns.

A Useful Default Mental Model

With the default PhysicalFileSystemProvider, the provider itself still uses ProcessingBehavior.CommandOnly, but the default middleware callback inserts autoorient=true when no autoorient command is present. In practice that means:

  • /images/photo.jpg is intercepted, auto-oriented, cached, and served by ImageSharp.Web.
  • /images/photo.jpg?width=400 is also intercepted and processed by ImageSharp.Web.

That default favors display correctness over passthrough behavior, especially for formats such as WebP where browser EXIF-orientation support is unreliable.

If you want passthrough behavior that only processes URLs that already contain commands, you must replace OnParseCommandsAsync or otherwise bypass the middleware for those paths. ProcessingBehavior.CommandOnly by itself is not enough while the default auto-orientation callback is active.

Configure the Physical Provider and Cache

If your source images or cache should live somewhere other than the default web root locations, configure the provider and cache options explicitly:

using SixLabors.ImageSharp.Web;
using SixLabors.ImageSharp.Web.Caching;
using SixLabors.ImageSharp.Web.Providers;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddImageSharp(options =>
{
    options.BrowserMaxAge = TimeSpan.FromDays(7);
    options.CacheMaxAge = TimeSpan.FromDays(30);
})
.Configure<PhysicalFileSystemProviderOptions>(options =>
{
    options.ProviderRootPath = "assets";
})
.Configure<PhysicalFileSystemCacheOptions>(options =>
{
    options.CacheRootPath = "cache";
    options.CacheFolder = "imagesharp";
    options.CacheFolderDepth = 8;
});

Relative paths are resolved against the application content root. If your app does not define a web root, set both ProviderRootPath and CacheRootPath explicitly.

Keep source storage and cache storage conceptually separate. The provider root is where original images come from. The cache root is disposable derived output and can usually be cleared, rebuilt, or moved to cheaper storage without losing source assets. In clustered deployments, choose cache storage that matches your invalidation and sharing requirements.

Next Steps

Practical Guidance

  • Put UseImageSharp() before middleware that would otherwise serve source image files directly.
  • Keep source storage separate from derived cache storage.
  • Configure provider and cache roots explicitly when the app has no web root or runs in a container.
  • Read the security page before exposing free-form transformation URLs publicly.
Edit this page