Self-hosted image processing middleware for ASP.NET Core. Resize, crop and convert images from the URL, cached on disk, configured in appsettings.json.
<img src="/images/hero.jpg?width=1920&height=600&rmode=crop&format=auto" />- Any ASP.NET Core app: Blazor (Server, Web App, hosted WASM), MVC, Razor Pages, minimal APIs.
- Compatible URLs: the same query syntax as ImageSharp.Web and Umbraco, so existing URLs keep working.
- Formats: JPEG, PNG, WebP, AVIF and GIF (TIFF opt-in), with automatic AVIF/WebP for browsers that support them.
- Fast: powered by libvips. See performance.
- Open: MIT licensed, .NET 8 and 10, Windows, Linux and macOS (x64 and ARM64).
Every GitHub release has the NuGet package attached. Until it is on nuget.org:
mkdir packages # put Bildverk.<version>.nupkg from the release here
dotnet nuget add source ./packages --name local
dotnet add package Bildverkbuilder.Services.AddBildverk(); // reads the "Bildverk" section of appsettings.json
var app = builder.Build();
app.UseBildverk(); // before UseStaticFiles / MapStaticAssets
app.UseStaticFiles();Images in wwwroot can now be requested with commands. Requests without commands are served unchanged by static files.
<img src="/images/team.jpg?width=400&height=400&rmode=crop&rxy=0.5,0.3" alt="Team" />| Command | Values | |
|---|---|---|
width, height |
pixels | Limited by Limits:MaxWidth/MaxHeight |
rmode |
max (default), crop, pad, boxpad, min, stretch |
See below |
ranchor |
center, top, bottom, left, right, topleft, topright, bottomleft, bottomright |
Where to crop or pad |
rxy |
0.5,0.3 |
Focal point for crop (0–1); overrides ranchor |
quality |
1–100 |
JPEG, WebP, AVIF. Default Defaults:Quality |
format |
jpg, png, webp, avif, gif, tiff, auto |
auto = best format the browser accepts |
bgcolor |
fff, ff0000, ff000080, white, transparent |
Fill for padding and transparency |
rmode |
Result |
|---|---|
max |
Fits inside the box, keeps the aspect ratio |
crop |
Fills the box, cuts off what overflows |
pad |
Fits inside the box, fills the rest with bgcolor |
boxpad |
Like pad, but never upscales |
min |
Shortest side reaches the box, never upscales |
stretch |
Exactly the box, aspect ratio ignored |
EXIF orientation is applied and metadata (GPS, camera, author) is removed from every output. Unknown parameters are ignored.
Responsive images. Restrict sizes to your breakpoints, so a page can't create endless variants:
"Bildverk": { "Limits": { "AllowedWidths": [320, 640, 960, 1280, 1920] } }<img src="/img/a.jpg?width=960"
srcset="/img/a.jpg?width=320 320w, /img/a.jpg?width=640 640w, /img/a.jpg?width=960 960w, /img/a.jpg?width=1920 1920w"
sizes="(max-width: 960px) 100vw, 960px" />Requested widths snap up to the nearest allowed one.
AVIF/WebP automatically. Use format=auto per image, or turn it on for everything:
"Bildverk": { "Formats": { "AutoByDefault": true } }The browser's Accept header decides the format: AVIF, then WebP, then the original format. Responses carry Vary: Accept, so CDNs cache each format separately. AutoForPlainRequests also converts URLs without a query (/img/a.jpg). GIFs are never converted automatically, because that would drop animation.
Signed URLs. Only URLs your server generated get processed:
"Bildverk": { "Security": { "HmacKey": "<at least 32 random characters>" } }@inject Bildverk.Security.IBildverkUrlSigner Signer
<img src="@Signer.Sign("/images/hero.jpg?width=800&height=400&rmode=crop")" />Unsigned or modified URLs get 403. Originals without commands are still served.
Store the cache elsewhere:
"Bildverk": { "Cache": { "Path": "D:/imagecache", "MaxSizeMB": 50000 } }All keys are optional; these are the defaults. Settings apply without a restart, except those marked restart. Any key can also come from environment variables, for example Bildverk__Cache__Path=/var/cache/images.
- A request with commands is normalized: parameters are sorted, clamped and given defaults, and unknown ones are dropped. Equivalent URLs therefore share one cached file.
- If the cached file exists and the original hasn't changed since, it is served (with
ETagand304 Not Modified). - Otherwise the image is processed once, even if many requests for it arrive at the same time, then cached and served.
The cache keeps itself within MaxAge and MaxSizeMB. Changing an original makes the next request reprocess it.
Multiple servers: put a CDN in front, or point Cache:Path at shared storage. ETags are identical on every server.
Register your own implementation before or after AddBildverk():
| Interface | Default | Replace to |
|---|---|---|
IImageSource |
FileSystemImageSource |
Read originals from blob storage, a database, … |
IImageCache |
FileSystemImageCache |
Cache somewhere other than the local disk |
IImageProcessor |
VipsImageProcessor |
Use a different imaging library |
- Restrict variants: set
Security:HmacKeyorLimits:AllowedWidths, so visitors can't create endless size variants. Bildverk warns at startup when neither is set. - Size the cache: set
Cache:MaxSizeMBto fit your disk. - Formats: remove input formats you don't serve from
Limits:AllowedInputFormats. - User uploads: if visitors can upload images, lower
Limits:MaxSourcePixels/MaxSourceBytesto what you expect. Each image being processed holds its file in memory. - More than one server: put a CDN or shared storage in front.
What Bildverk protects against, and how, is described in docs/security.md.
- Animated GIF and WebP output only the first frame.
- There is no built-in blob-storage cache yet. Use
IImageCache, a CDN, or a shared disk.
dotnet test --project tests/Bildverk.Tests
dotnet run --project samples/Bildverk.Sample --launch-profile http # http://localhost:5026See CHANGELOG.md for changes, and SECURITY.md for reporting vulnerabilities.
MIT. Bildverk uses NetVips (MIT) and its bundled libvips build (LGPL-3.0, shipped as a separate replaceable library, so it is fine for commercial and closed-source apps). See docs/security.md.