SharpPixel.AspNetCore.ImageResizer 2.1.0

SharpPixel.AspNetCore.ImageResizer 🚀

A high-performance, asynchronous, and DoS-protected image resizing middleware for ASP.NET Core built on top of SkiaSharp v3. It intercepts static image requests on-the-fly, processes them based on query parameters, and caches the result for maximum efficiency.

🌟 Features

• High Performance: Powered by SkiaSharp v3 for lightning-fast, native image manipulation.
• DoS Protection: Enforces safety ceilings on dimensions to prevent server resource exhaustion.
• Smart Two-Layer Cache: Combines fast IMemoryCache with a persistent Disk Cache to offload CPU and RAM.
• Throttled Midnight Cleaner: An automated background worker (HostedService) that wakes up at a user-defined hour (e.g., 3 AM) to clean expired files without locking your disk or affecting active users.
• Custom Pad Color: Seamlessly fill empty spaces in pad mode using standard HEX codes (e.g., bg=ff0000).
• Next-Gen Formats: Convert legacy images to modern WebP on-the-fly to boost your SEO and load speed.

📦 Installation

Install the package via NuGet CLI:

dotnet add package SharpPixel.AspNetCore.ImageResizer

Or via the Package Manager Console:

Install-Package SharpPixel.AspNetCore.ImageResizer

🚀 Quick Start & Integration

1. Configure your Program.cs To activate the image resizing capabilities, register the service and place the middleware in your request pipeline. Note: The middleware must be placed before UseStaticFiles.

using Mind.AspNetCore.ImageResizer;

var builder = WebApplication.CreateBuilder(args);

// Register services with production-ready configurations
builder.Services.AddImageResizer(options =>
{
    options.MaxDimension = 3000;                          // Safety ceiling for width/height (DoS Protection)
    options.CacheDuration = TimeSpan.FromDays(7);         // Server-side cache lifetime
    options.CacheControlHeader = "public, max-age=604800"; // Browser-side cache header (7 Days)
    options.CacheFolderName = "_imagecache";              // Directory name inside wwwroot/ContentRoot
    
    // Smart Background Midnight Cleaner Settings
    options.EnableBackgroundCleanup = true;               // Enable automated disk cleanup
    options.ExecutionHour = 3;                            // Wake up precisely at 3:00 AM
    options.UseUtcTime = true;                            // Use UTC time instead of Server Local Time
    options.CleanupBatchSize = 50;                        // Process files in small safe chunks
    options.CleanupThrottleDelayMs = 100;                 // Rest for 100ms after each batch to prevent Disk I/O spikes
});

var app = builder.Build();

// CRITICAL: Intercept image requests before the static files handler serves them
app.UseImageResizer();

app.UseStaticFiles();

app.MapGet("/", () => "Image Resizer Middleware is active and optimized! ⚡");

app.Run();

Image Resizing Modes & Query Parameters Once the middleware is active, you can dynamically transform any image located inside your wwwroot folder simply by appending query parameters (w, h, mode, quality, format) to its URL.

Here are the visual modes supported by the package:

1. Resize by Width Only (w) Maintains the original aspect ratio automatically while scaling the width down to 300px.

<img src="/images/scenery.jpg?w=300" alt="Resized Width" />

2. Smart Center Crop (mode=crop)Resizes the image and crops it perfectly into a $400 \times 400$ square from the center, discarding any overflowing edges. Excellent for user avatars!

<img src="/images/avatar.jpg?w=400&h=400&mode=crop" alt="Center Cropped" />

3. Padded Fit with Custom Background (mode=pad & bg)

<img src="/images/product.jpg?w=800&h=600&mode=pad&bg=e0e0e0" alt="Padded Product" />

4. Format Conversion & Quality Compression (format & quality) Converts the output format on-the-fly to a next-gen format like WebP and drops the compression quality to 60% for extreme web performance optimization.

<img src="/images/banner.png?w=1000&quality=60&format=webp" alt="Optimized WebP" />

Query Reference Table

Configuration Options

⭐ Support the Project

If you find this package useful, please consider giving it a Star on GitHub! It helps the project grow and motivates further development.