DotnetImageThumbnail 1.0.4

.NET Image Thumbnail Library

A high-performance .NET 10 library for creating image thumbnails with support for multiple image formats and advanced processing capabilities. The library provides three providers, selected at runtime via dependency injection:

• Skia (ImageProvider.Skia): Cross-platform solution with superior image quality
• Advanced Skia (ImageProvider.AdvancedSkia): Cross-platform with advanced processing (cropping, filtering, format conversion)
• GDI+ (ImageProvider.GdiPlus): Windows-native solution using System.Drawing

🚀 Features

• Multiple Implementation Options: Choose between SkiaSharp (cross-platform) or GDI+ (Windows-native) via dependency injection
• High-Quality Thumbnail Generation: Create thumbnails with variable width/height while maintaining aspect ratio
• Advanced Image Processing: Enhanced implementation with cropping, filtering, and format conversion
• Multiple Image Formats: Support for PNG, JPEG, WebP, AVIF, BMP, GIF, and ICO formats
• Intelligent File Management: Automatic thumbnail naming and cache management
• Performance Optimized: Built on industry-standard graphics libraries
• Flexible Deployment: Cross-platform with SkiaSharp or Windows-optimized with GDI+

📦 Installation

Prerequisites

• .NET 10.0 or higher
• SkiaSharp 3.119.4 (SkiaSharp providers)
• System.Drawing.Common 10.0.12 (GDI+ provider, Windows-only)
• Codenet.Drawing.Common.GdiPlus 2.0.4 (GDI+ provider)

Package Installation

Install from NuGet:

dotnet add package DotnetImageThumbnail

Build the library:

dotnet build

Register image services and choose a provider:

using dotnet_image_thumbnail.Library.Image.Configuration;

services.AddImageServices(ImageProvider.Skia);         // default, cross-platform
services.AddImageServices(ImageProvider.AdvancedSkia); // cross-platform, advanced features
services.AddImageServices(ImageProvider.GdiPlus);      // Windows-only

🖥️ Usage

The easiest way to use the library is through IImageThumbnailManager. It handles thumbnail naming, generation, and caching for you — you only provide the source image path and the dimensions you want.

using dotnet_image_thumbnail.Library.Image;
using dotnet_image_thumbnail.Library.Image.Configuration;

// Register once (e.g. in Program.cs)
builder.Services.AddImageServices(); // defaults to ImageProvider.Skia

// Inject and use
public class MyController(IImageThumbnailManager thumbnails)
{
    public string GetThumbnail(string imagePath)
    {
        // Creates the thumbnail on disk if missing (or stale) and returns a
        // URL-safe file name. Pass width OR height to preserve aspect ratio.
        return thumbnails.RetrieveThumbnailFileName(
            imagePath,
            thumbnailWidth: 300,
            thumbnailHeight: null);
    }
}

• thumbnailWidth only → fixed width, variable height (aspect ratio preserved)
• thumbnailHeight only → fixed height, variable width
• Both null → throws, since no target dimension was provided

Thumbnails are cached on disk: a thumbnail is only regenerated when the original file has been modified more recently than the thumbnail.

🏗️ Architecture

The library is built around a modular architecture with clear separation of concerns:

Core Interfaces

• IImageHelper: Basic thumbnail creation and image saving functionality

• IImageDecoder: Image format detection and conversion utilities

• IImageQuantizer: Color quantization for optimized file sizes

• IImageThumbnailManager: High-level thumbnail management with caching — the recommended entry point (see Usage)

• IEnhancedImageHelper: Advanced features including cropping, filtering, and format conversion

See Extending the Library for a guide to implementing your own versions of these interfaces and wiring them into your solution.

Choosing a Provider

SkiaSharp (ImageProvider.Skia / ImageProvider.AdvancedSkia) - Recommended for:

• Cross-platform applications (Windows, macOS, Linux)
• Applications requiring advanced image processing features
• Modern image format support (WebP, AVIF)
• High-quality image rendering with anti-aliasing

GDI+ (ImageProvider.GdiPlus) - Recommended for:

• Windows-only applications
• Integration with existing System.Drawing code
• Legacy system compatibility

📊 Implementation Comparison

🎨 Supported Image Formats

Thumbnail Naming Convention

Thumbnails are automatically named using the pattern:

Thumbnail_{OriginalName}_{Width}x{Height}.{Extension}

Example: Thumbnail_photo_300x200.jpeg

🐛 Known Issues

• Some advanced AVIF features may require additional codec support on certain platforms
• ICO format writing may have limitations with larger dimensions

📚 Dependencies

• SkiaSharp: 3.119.4 - Cross-platform 2D graphics library
• Microsoft.Extensions.DependencyInjection.Abstractions: 10.0.12 - DI service registration
• System.Drawing.Common: 10.0.12 - Windows native graphics (GDI+ provider, Windows-only)
• Codenet.Drawing.Common.GdiPlus: 2.0.4 - GDI+ color quantization (GDI+ provider)
• .NET: 10.0 - Target framework