ImageSharp.Web

High-performance ASP.NET Core image middleware for on-the-fly processing, caching, security, and extensible delivery.

Explore the docs

ImageSharp.Web lets ASP.NET Core applications resize, transform, cache, and secure image responses from request URLs, whether you are building responsive websites, media-heavy content platforms, headless CMS front ends, ecommerce catalogs, or APIs that need to deliver optimized images at scale.

Built for web image delivery

ImageSharp.Web sits in front of your image source, parses commands from the request, processes the result with ImageSharp, caches the encoded output, and serves repeat requests cheaply after the first hit.

It runs on ASP.NET Core with .NET 8+, giving .NET teams a production-grade image pipeline inside the application stack they already own. 

dotnet add package SixLabors.ImageSharp.Web
using SixLabors.ImageSharp.Web;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddImageSharp();

WebApplication app = builder.Build();

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

app.Run();

Simple URLs, predictable output

The built-in command set covers the jobs most web applications need every day: resize, crop, auto-orient, change format, control quality, and flatten transparency.

The middleware ships with web-tuned defaults out of the box. Requests are auto-oriented unless you explicitly opt out, embedded ICC profiles are normalized to a consistent working space on decode, and JPEG, PNG, and WebP output is encoded with settings chosen for cache-backed web delivery rather than raw library defaults.

For MVC and Razor Pages applications, built-in Tag Helpers can generate command URLs in strongly typed markup and automatically append HMAC tokens when signing is enabled. Preset-only parsing can also turn public URLs into named variants instead of exposing free-form commands. 

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

Controlled public variants

Public image URLs are product APIs. ImageSharp.Web lets you decide whether clients can submit arbitrary commands, named presets, signed URLs, or server-generated Razor markup.

HMAC signing proves a URL was generated by server-side code that knows the secret, while preset-only parsing keeps the command vocabulary small enough to reason about.

  • Require HMAC tokens for command URLs and generate matching tokens with built-in authorization utilities.
  • Use preset-only parsing for fixed variants such as avatars, cards, thumbnails, and responsive breakpoints.
  • Let ImageTagHelper generate command URLs and HmacTokenTagHelper sign them in MVC or Razor Pages.
  • Keep invariant command parsing enabled when URLs must behave the same across machines and cultures.
  • Preserve the default auto-orient callback when adding custom command augmentation.
using SixLabors.ImageSharp.Web;
using SixLabors.ImageSharp.Web.Commands;

builder.Services.AddImageSharp(options =>
{
    options.HMACSecretKey = Convert.FromBase64String(
        builder.Configuration["ImageSharp:HmacKey"]!);
})
.SetRequestParser<PresetOnlyQueryCollectionRequestParser>()
.Configure<PresetOnlyQueryCollectionRequestParserOptions>(options =>
{
    // Presets expose named variants instead of arbitrary command URLs.
    options.Presets["avatar"] = "width=128&height=128&rmode=crop&format=webp";
    options.Presets["card"] = "width=640&height=360&rmode=crop&format=webp";
});

Cache and extend the pipeline

ImageSharp.Web is intentionally modular, so you can choose where source images come from, where processed output is cached, how cache keys are built, which commands exist, and which callbacks shape request behavior.

  • Use the default physical provider and cache for fast local setup, or swap in Azure Blob Storage and AWS S3 backends.
  • Keep generated variants stable with configurable cache keys, cache hashes, browser max age, and cache max age.
  • Store encoded bytes plus source metadata so stale entries can be detected when the original changes.
  • Tap into per-request callbacks for command parsing, decoder options, encoded output, processed metadata, and response headers without writing a custom processor.
  • Extend the pipeline with custom processors, command converters, request parsers, providers, caches, cache keys, and cache hashes.
  • Keep provider, parser, processor, and cache responsibilities separate so signing and caching remain predictable.
using SixLabors.ImageSharp.Web;
using SixLabors.ImageSharp.Web.Caching;
using SixLabors.ImageSharp.Web.Providers;

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