Umbraco-CMS/src/Umbraco.Cms.Imaging.ImageSharp2/CLAUDE.md

Umbraco.Cms.Imaging.ImageSharp2

Image processing library using ImageSharp 2.x for backwards compatibility with existing deployments. Use this package only when migrating from older Umbraco versions that depend on ImageSharp 2.x behavior.

Namespace Note: Uses Umbraco.Cms.Imaging.ImageSharp (same as v3 package) for drop-in replacement - no code changes needed when switching.

---

1. Architecture

Type: Class Library (NuGet Package) Target Framework: .NET 10.0 Purpose: ImageSharp 2.x compatibility layer

Package Versions (Pinned)

<!-- From csproj lines 7-8 -->
<PackageReference Include="SixLabors.ImageSharp" VersionOverride="[2.1.11, 3)" />
<PackageReference Include="SixLabors.ImageSharp.Web" VersionOverride="[2.0.2, 3)" />

Version constraint [2.1.11, 3) means: minimum 2.1.11, below 3.0.

Project Structure (7 source files)

Umbraco.Cms.Imaging.ImageSharp2/
├── ImageSharpComposer.cs                    # Auto-registration via IComposer
├── UmbracoBuilderExtensions.cs              # DI setup and middleware configuration
├── ConfigureImageSharpMiddlewareOptions.cs  # Middleware options (caching, size limits)
├── ConfigurePhysicalFileSystemCacheOptions.cs # File cache location
├── ImageProcessors/
│   └── CropWebProcessor.cs                  # Custom crop processor with EXIF awareness
└── Media/
    ├── ImageSharpDimensionExtractor.cs      # Extract image dimensions (EXIF-aware)
    └── ImageSharpImageUrlGenerator.cs       # Generate query string URLs

---

2. Key Differences from ImageSharp (3.x)

Feature	ImageSharp2 (this)	ImageSharp (3.x)
Package version	2.1.11 - 2.x	3.x+
HMAC signing	Not supported	Supported
WebP default	Lossy (native)	Lossless (overridden to Lossy)
Cache buster param	rnd only	rnd or v
API differences	Image.Identify(config, stream)	Image.Identify(options, stream)
Size property	image.Image.Size() method	image.Image.Size property

API Differences in Code

ImageSharpDimensionExtractor (Media/ImageSharpDimensionExtractor.cs:31):

// v2: Direct method call
IImageInfo imageInfo = Image.Identify(_configuration, stream);

// v3: Uses DecoderOptions
ImageInfo imageInfo = Image.Identify(options, stream);

CropWebProcessor (ImageProcessors/CropWebProcessor.cs:67):

// v2: Size is a method
Size size = image.Image.Size();

// v3: Size is a property
Size size = image.Image.Size;

Missing Features (vs ImageSharp 3.x)

1. No HMAC request authorization - HMACSecretKey setting is ignored
2. No v cache buster - Only rnd parameter triggers immutable headers
3. No WebP encoder override - Uses default Lossy encoding (no configuration needed)

---

3. When to Use This Package

Use ImageSharp2 when:

• Migrating from Umbraco versions that used ImageSharp 2.x
• Third-party packages have hard dependency on ImageSharp 2.x
• Need exact byte-for-byte output compatibility with existing cached images

Use ImageSharp (3.x) when:

• New installations
• Need HMAC URL signing for security
• Want latest performance improvements

---

4. Configuration

Same as ImageSharp 3.x. See /src/Umbraco.Cms.Imaging.ImageSharp/CLAUDE.md → Section 3 for full configuration details.

Key difference: HMACSecretKey setting exists but is ignored in this package (no HMAC support in v2).

---

Quick Reference

Essential Commands

# Build
dotnet build src/Umbraco.Cms.Imaging.ImageSharp2/Umbraco.Cms.Imaging.ImageSharp2.csproj

# Run tests
dotnet test tests/Umbraco.Tests.UnitTests/ --filter "FullyQualifiedName~ImageSharp"

Key Files

File	Purpose
Umbraco.Cms.Imaging.ImageSharp2.csproj	Version constraints (lines 7-8)
ConfigureImageSharpMiddlewareOptions.cs	Size limit enforcement
Media/ImageSharpImageUrlGenerator.cs	URL generation (no HMAC)

Switching Between Packages

To switch from ImageSharp2 to ImageSharp (3.x):

1. Remove Umbraco.Cms.Imaging.ImageSharp2 package reference
2. Add Umbraco.Cms.Imaging.ImageSharp package reference
3. Clear media cache folder (~/umbraco/Data/TEMP/MediaCache)
4. No code changes needed (same namespace)

Getting Help

• ImageSharp 3.x Documentation: /src/Umbraco.Cms.Imaging.ImageSharp/CLAUDE.md
• Root Documentation: /CLAUDE.md
• SixLabors ImageSharp 2.x Docs: https://docs.sixlabors.com/

---

This is a backwards-compatibility package. For new projects, use Umbraco.Cms.Imaging.ImageSharp (3.x) instead.