Gestire il formato WebP in C#

In questo articolo useremo ImageSharp, che ha il vantaggio di non avere dipendenze native: lo stesso pacchetto NuGet funziona su Windows, Linux e macOS, su x64 e ARM64, senza librerie di sistema da installare nell'immagine Docker.

C# di Gabriele Romanato

Per anni, nel mondo .NET, elaborare immagini ha significato usare System.Drawing, un wrapper attorno a GDI+ pensato per le applicazioni desktop Windows. Oggi quella strada è chiusa per le applicazioni server: Microsoft supporta System.Drawing.Common solo su Windows, e comunque non ha mai offerto WebP. Le applicazioni ASP.NET Core moderne, che girano tipicamente in container Linux, usano librerie dedicate. Le più diffuse sono tre: ImageSharp di Six Labors, scritta interamente in C# gestito; SkiaSharp, il binding .NET del motore grafico Skia di Google; Magick.NET, il binding di ImageMagick.

In questo articolo useremo ImageSharp, che ha il vantaggio di non avere dipendenze native: lo stesso pacchetto NuGet funziona su Windows, Linux e macOS, su x64 e ARM64, senza librerie di sistema da installare nell'immagine Docker. Costruiremo un parser dell'intestazione con BinaryPrimitives, vedremo codifica e decodifica con tutte le opzioni dell'encoder, l'orientamento EXIF e la privacy dei metadati, le animazioni, i caricamenti sicuri, un endpoint ASP.NET Core che negozia il formato e una conversione parallela con Parallel.ForEachAsync.

Installare ImageSharp

ImageSharp richiede .NET 8 o successivo. Il pacchetto si aggiunge come qualunque dipendenza NuGet:

dotnet new web -n WebpToolkit
cd WebpToolkit
dotnet add package SixLabors.ImageSharp
<!-- WebpToolkit.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="SixLabors.ImageSharp" Version="4.1.3" />
  </ItemGroup>
</Project>

Usiamo il modello web perché il progetto ospiterà anche un endpoint ASP.NET Core; le classi di elaborazione non dipendono dal web e possono essere spostate in una libreria a parte. Il codice di questo articolo usa solo API presenti sia nel ramo 3.1 sia nel ramo 4 della libreria. Due avvertenze prima di proseguire. La prima riguarda la licenza: ImageSharp è distribuita con la Six Labors Split License, che consente l'uso gratuito ai progetti open source e alle organizzazioni sotto una soglia di fatturato annuo, mentre negli altri casi richiede una licenza commerciale; i termini esatti vanno verificati prima di adottarla. La seconda riguarda la sicurezza: le versioni di ImageSharp precedenti alla 3.1.4 erano vulnerabili a file costruiti per provocare allocazioni di memoria eccessive (CVE-2024-32035). Essendo una libreria gestita, ImageSharp non condivide il codice di libwebp e non è stata toccata dalla vulnerabilità CVE-2023-4863 del 2023, ma come ogni decoder va mantenuta aggiornata.

La struttura di un file WebP

Un file WebP è un contenitore RIFF: i quattro byte RIFF, la dimensione del resto del file come intero a 32 bit little-endian, i quattro byte WEBP e una sequenza di chunk, ciascuno con un identificatore di quattro caratteri, una dimensione e il contenuto. Il primo chunk identifica la variante del file:

  • VP8 , con lo spazio finale: compressione con perdita senza alfa. Le dimensioni si trovano su 14 bit dopo il codice di sincronizzazione 9d 01 2a.
  • VP8L: compressione senza perdita. Dopo il byte 0x2f, 28 bit contengono larghezza e altezza meno uno, e il bit successivo segnala l'uso dell'alfa.
  • VP8X: formato esteso, per alfa con perdita, profili ICC, EXIF, XMP e animazioni. Un byte di flag è seguito dalle dimensioni della tela su 24 bit, meno uno.

Un parser dell'intestazione con Span

In C# moderno il parsing binario si scrive con ReadOnlySpan<byte> e la classe BinaryPrimitives, che legge interi in un ordine dei byte esplicito senza allocazioni e senza codice unsafe. Il risultato è un record struct, un tipo valore immutabile con uguaglianza strutturale.

// WebpInfo.cs
using System.Buffers.Binary;

namespace WebpToolkit;

public enum WebpFormat { Lossy, Lossless, Extended }

public readonly record struct WebpInfo(
    WebpFormat Format, int Width, int Height,
    bool Alpha = false, bool Animated = false,
    bool Icc = false, bool Exif = false, bool Xmp = false)
{
    private const byte FlagIcc = 0x20;
    private const byte FlagAlpha = 0x10;
    private const byte FlagExif = 0x08;
    private const byte FlagXmp = 0x04;
    private const byte FlagAnimation = 0x02;

    public const int HeaderSize = 30;

    public static WebpInfo? Parse(ReadOnlySpan<byte> data)
    {
        if (data.Length < HeaderSize || !data[..4].SequenceEqual("RIFF"u8) || !data[8..12].SequenceEqual("WEBP"u8))
        {
            return null;
        }

        ReadOnlySpan<byte> fourcc = data[12..16];

        if (fourcc.SequenceEqual("VP8 "u8))
        {
            // Codice di sincronizzazione del fotogramma chiave VP8
            if (data[23] != 0x9d || data[24] != 0x01 || data[25] != 0x2a)
            {
                return null;
            }
            int width = BinaryPrimitives.ReadUInt16LittleEndian(data[26..]) & 0x3fff;
            int height = BinaryPrimitives.ReadUInt16LittleEndian(data[28..]) & 0x3fff;
            return new WebpInfo(WebpFormat.Lossy, width, height);
        }

        if (fourcc.SequenceEqual("VP8L"u8))
        {
            if (data[20] != 0x2f)
            {
                return null;
            }
            uint bits = BinaryPrimitives.ReadUInt32LittleEndian(data[21..]);
            return new WebpInfo(WebpFormat.Lossless,
                (int)(bits & 0x3fff) + 1,
                (int)((bits >> 14) & 0x3fff) + 1,
                Alpha: ((bits >> 28) & 1) == 1);
        }

        if (fourcc.SequenceEqual("VP8X"u8))
        {
            byte flags = data[20];
            return new WebpInfo(WebpFormat.Extended,
                UInt24(data[24..]) + 1,
                UInt24(data[27..]) + 1,
                Alpha: (flags & FlagAlpha) != 0,
                Animated: (flags & FlagAnimation) != 0,
                Icc: (flags & FlagIcc) != 0,
                Exif: (flags & FlagExif) != 0,
                Xmp: (flags & FlagXmp) != 0);
        }

        return null;
    }

    public static async Task<WebpInfo?> ReadAsync(Stream stream, CancellationToken cancellationToken = default)
    {
        byte[] header = new byte[HeaderSize];
        int read = await stream.ReadAtLeastAsync(header, HeaderSize, throwOnEndOfStream: false, cancellationToken);
        return Parse(header.AsSpan(0, read));
    }

    private static int UInt24(ReadOnlySpan<byte> b) => b[0] | b[1] << 8 | b[2] << 16;
}

I letterali con il suffisso u8, introdotti in C# 11, producono un ReadOnlySpan<byte> con la codifica UTF-8 della stringa direttamente nel binario, senza allocazioni a runtime: il confronto con SequenceEqual è quindi efficiente quanto un confronto di memoria. ReadAtLeastAsync, disponibile da .NET 7, risolve il problema classico delle letture parziali da uno stream di rete, garantendo di leggere almeno il numero di byte richiesto, a meno che lo stream finisca prima.

Codificare

In ImageSharp ogni formato ha un encoder, un oggetto di configurazione leggero con proprietà init. Le proprietà più importanti di WebpEncoder sono:

  • FileFormat: WebpFileFormatType.Lossy o WebpFileFormatType.Lossless; se non è impostato, l'encoder usa la modalità con perdita;
  • Quality, da 0 a 100 (predefinito 75): la qualità visiva in modalità con perdita, lo sforzo di compressione in quella senza perdita;
  • Method: il compromesso tra velocità e dimensione, dall'enumerazione WebpEncodingMethod, da Level0 a Level6, con gli alias Fastest, Default e BestQuality;
  • UseAlphaCompression: comprime il canale alfa nella modalità con perdita;
  • NearLossless e NearLosslessQuality: la preelaborazione che altera leggermente i pixel per migliorare la compressione senza perdita;
  • EntropyPasses, SpatialNoiseShaping e FilterStrength: regolazioni avanzate dell'encoder con perdita.
// WebpCodec.cs
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats.Webp;
using SixLabors.ImageSharp.PixelFormats;

namespace WebpToolkit;

public static class WebpCodec
{
    // Profilo per le fotografie
    public static readonly WebpEncoder Photo = new()
    {
        FileFormat = WebpFileFormatType.Lossy,
        Quality = 80,
        Method = WebpEncodingMethod.Level4,
        UseAlphaCompression = true,
    };

    // Profilo per loghi, icone e schermate
    public static readonly WebpEncoder Graphic = new()
    {
        FileFormat = WebpFileFormatType.Lossless,
        Quality = 100,
        Method = WebpEncodingMethod.BestQuality,
    };

    // Compressione senza perdita con preelaborazione: un buon compromesso per le grafiche complesse
    public static readonly WebpEncoder NearLossless = new()
    {
        FileFormat = WebpFileFormatType.Lossless,
        NearLossless = true,
        NearLosslessQuality = 60,
        Method = WebpEncodingMethod.Level5,
    };

    public static WebpEncoder For(Image image) => IsFlatGraphic(image) ? Graphic : Photo;

    // Scrive su un file temporaneo e lo sposta: nessun lettore vede un file incompleto
    public static async Task<long> SaveAsync(Image image, string path, WebpEncoder encoder, CancellationToken ct = default)
    {
        string temporary = $"{path}.{Guid.NewGuid():N}.tmp";
        try
        {
            await image.SaveAsync(temporary, encoder, ct);
            File.Move(temporary, path, overwrite: true);
        }
        finally
        {
            File.Delete(temporary);
        }
        return new FileInfo(path).Length;
    }

    // Stima su un campione di pixel: le grafiche piatte hanno pochi colori distinti
    public static bool IsFlatGraphic(Image image, int maxColors = 256)
    {
        using Image<Rgba32> sample = image.CloneAs<Rgba32>();
        int step = Math.Max(1, Math.Min(sample.Width, sample.Height) / 128);
        var colors = new HashSet<uint>();
        bool flat = true;

        sample.ProcessPixelRows(accessor =>
        {
            for (int y = 0; y < accessor.Height && flat; y += step)
            {
                Span<Rgba32> row = accessor.GetRowSpan(y);
                for (int x = 0; x < row.Length; x += step)
                {
                    colors.Add(row[x].PackedValue);
                    if (colors.Count > maxColors)
                    {
                        flat = false;
                        break;
                    }
                }
            }
        });
        return flat;
    }
}

File.Delete nel blocco finally non solleva eccezioni se il file non esiste, quindi dopo uno spostamento riuscito non fa nulla, mentre in caso di errore rimuove il temporaneo. ProcessPixelRows è il modo raccomandato per accedere ai pixel in ImageSharp: espone ogni riga come Span<Rgba32>, senza copie, e tiene conto del fatto che la memoria di un'immagine grande può essere suddivisa in più blocchi non contigui. Il CloneAs<Rgba32>() garantisce un formato di pixel noto qualunque sia quello della sorgente.

Decodificare e orientare

ImageSharp riconosce il formato dal contenuto e lo decodifica con Image.LoadAsync. Prima di decodificare, però, conviene interrogare l'intestazione con Image.IdentifyAsync, che restituisce dimensioni, formato e metadati senza allocare i pixel. L'orientamento EXIF, che le fotocamere usano per indicare la rotazione dello scatto, si applica con il processore AutoOrient().

// ImageLoader.cs
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats;
using SixLabors.ImageSharp.Processing;

namespace WebpToolkit;

public sealed class InvalidUploadException(string message) : Exception(message);

public static class ImageLoader
{
    public const long MaxPixels = 40_000_000;
    public const int MaxFrames = 300;
    private static readonly HashSet<string> AllowedFormats = ["JPEG", "PNG", "WEBP", "GIF"];

    public static async Task<Image> LoadAsync(Stream stream, bool keepAnimation = false, CancellationToken ct = default)
    {
        if (!stream.CanSeek)
        {
            // Identify e Load leggono entrambi lo stream: serve poter tornare all'inizio
            var buffer = new MemoryStream();
            await stream.CopyToAsync(buffer, ct);
            buffer.Position = 0;
            stream = buffer;
        }

        ImageInfo info;
        try
        {
            info = await Image.IdentifyAsync(stream, ct);
        }
        catch (Exception e) when (e is UnknownImageFormatException or InvalidImageContentException)
        {
            throw new InvalidUploadException("Immagine non riconosciuta");
        }

        string format = info.Metadata.DecodedImageFormat?.Name.ToUpperInvariant() ?? "";
        if (!AllowedFormats.Contains(format))
        {
            throw new InvalidUploadException($"Formato non ammesso: {format}");
        }
        if ((long)info.Width * info.Height > MaxPixels)
        {
            throw new InvalidUploadException($"Dimensioni eccessive: {info.Width}x{info.Height}");
        }

        stream.Position = 0;
        var options = new DecoderOptions
        {
            // Per le immagini statiche basta il primo fotogramma
            MaxFrames = keepAnimation ? MaxFrames : 1,
        };

        Image image;
        try
        {
            image = await Image.LoadAsync(options, stream, ct);
        }
        catch (InvalidImageContentException)
        {
            throw new InvalidUploadException("Immagine danneggiata");
        }

        // Ruota i pixel secondo il tag EXIF Orientation e lo azzera
        image.Mutate(x => x.AutoOrient());
        return image;
    }
}

Il filtro sulle eccezioni con when permette di catturare solo quelle che indicano un input non valido, lasciando propagare tutto il resto, per esempio un errore di I/O. La costruzione primaria della classe InvalidUploadException e l'espressione di collezione per l'HashSet sono costrutti di C# 12. Il limite MaxFrames è una difesa importante con le animazioni: un file con migliaia di fotogrammi verrebbe altrimenti decodificato per intero.

Metadati e privacy

Le foto scattate con uno smartphone contengono nei dati EXIF le coordinate GPS, il modello del dispositivo e l'ora dello scatto. ImageSharp, per impostazione predefinita, conserva i metadati quando salva: è il comportamento giusto per un software di fotoritocco, ma non per un sito che pubblica immagini caricate dagli utenti. Il profilo colore ICC, invece, va conservato, perché senza di esso le foto in spazi colore ampi come Display P3 appaiono con colori spenti.

// Privacy.cs
using SixLabors.ImageSharp;

namespace WebpToolkit;

public static class Privacy
{
    // Rimuove EXIF e XMP, conserva il profilo colore
    public static void StripPersonalMetadata(Image image)
    {
        image.Metadata.ExifProfile = null;
        image.Metadata.XmpProfile = null;
        image.Metadata.IptcProfile = null;
        foreach (ImageFrame frame in image.Frames)
        {
            frame.Metadata.ExifProfile = null;
            frame.Metadata.XmpProfile = null;
        }
    }

    public static string Describe(Image image) =>
        $"{image.Width}x{image.Height}, fotogrammi: {image.Frames.Count}, " +
        $"EXIF: {image.Metadata.ExifProfile is not null}, ICC: {image.Metadata.IccProfile is not null}";
}

L'ordine delle operazioni conta: AutoOrient() va applicato prima di rimuovere l'EXIF, perché legge proprio da lì la rotazione da applicare. Nel nostro ImageLoader l'orientamento avviene già in fase di caricamento, quindi la pulizia può seguire senza rischi. Se invece si volesse eliminare ogni metadato, profilo colore compreso, basterebbe impostare SkipMetadata = true sull'encoder.

Varianti responsive

Generare le larghezze per l'attributo srcset richiede un ridimensionamento di qualità per ciascuna. Con ImageSharp si clona l'immagine sorgente, già decodificata e orientata, e si applica Resize: con una delle due dimensioni pari a zero le proporzioni vengono mantenute.

// Variants.cs
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats.Webp;
using SixLabors.ImageSharp.Processing;

namespace WebpToolkit;

public sealed record Variant(int Width, int Height, string Path);

public static class Variants
{
    public static readonly int[] Widths = [320, 640, 960, 1280, 1920];

    public static async Task<List<Variant>> CreateAsync(Image source, string name, string outputDir, CancellationToken ct = default)
    {
        Directory.CreateDirectory(outputDir);
        var variants = new List<Variant>();

        foreach (int width in Widths)
        {
            // Nessuna variante più grande dell'originale
            if (width > source.Width)
            {
                break;
            }
            using Image resized = source.Clone(x => x.Resize(new ResizeOptions
            {
                Size = new Size(width, 0),
                Sampler = KnownResamplers.Lanczos3,
            }));

            string path = System.IO.Path.Combine(outputDir, $"{name}-{width}.webp");
            var encoder = new WebpEncoder
            {
                FileFormat = WebpFileFormatType.Lossy,
                Quality = width <= 640 ? 75 : 80,
                Method = WebpEncodingMethod.Level5,
            };
            await WebpCodec.SaveAsync(resized, path, encoder, ct);
            variants.Add(new Variant(width, resized.Height, path));
        }
        return variants;
    }

    public static string Srcset(IEnumerable<Variant> variants, string publicPath) =>
        string.Join(", ", variants.Select(v => $"{publicPath}/{System.IO.Path.GetFileName(v.Path)} {v.Width}w"));
}

Il campionatore Lanczos3 è il più nitido per le riduzioni di scala; quello predefinito, Bicubic, è leggermente più veloce e comunque di buona qualità. Clone applica le operazioni a una copia e lascia intatta la sorgente, che può quindi essere riusata per tutte le varianti senza essere decodificata di nuovo.

Animazioni: da GIF a WebP

ImageSharp rappresenta un'animazione come un'immagine con più fotogrammi, accessibili tramite image.Frames. Ogni formato conserva i propri metadati di animazione: per le GIF la durata dei fotogrammi è espressa in centesimi di secondo, per WebP in millisecondi. Quando si converte, conviene impostare esplicitamente i valori di destinazione invece di affidarsi a conversioni implicite.

// Animation.cs
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats.Gif;
using SixLabors.ImageSharp.Formats.Webp;

namespace WebpToolkit;

public static class Animation
{
    public static async Task<long> GifToWebpAsync(string source, string target, int quality = 75, CancellationToken ct = default)
    {
        await using FileStream input = File.OpenRead(source);
        using Image image = await ImageLoader.LoadAsync(input, keepAnimation: true, ct);
        Privacy.StripPersonalMetadata(image);

        // Numero di ripetizioni: 0 significa all'infinito
        image.Metadata.GetWebpMetadata().RepeatCount = image.Metadata.GetGifMetadata().RepeatCount;

        foreach (ImageFrame frame in image.Frames)
        {
            // GIF: centesimi di secondo; WebP: millisecondi
            int centiseconds = frame.Metadata.GetGifMetadata().FrameDelay;
            // I browser mostrano per 100 ms i fotogrammi con ritardo inferiore a 2 centesimi
            frame.Metadata.GetWebpMetadata().FrameDelay = (uint)(centiseconds < 2 ? 10 : centiseconds) * 10;
        }

        var encoder = new WebpEncoder
        {
            FileFormat = WebpFileFormatType.Lossy,
            Quality = quality,
            Method = WebpEncodingMethod.Level4,
        };
        return await WebpCodec.SaveAsync(image, target, encoder, ct);
    }

    public static IEnumerable<(int Index, uint DelayMs)> Timeline(Image image) =>
        image.Frames.Select((frame, index) => (index, frame.Metadata.GetWebpMetadata().FrameDelay));

    // Primo fotogramma come anteprima statica
    public static Image Poster(Image animation) => animation.Frames.CloneFrame(0);
}

La correzione dei ritardi molto brevi riproduce il comportamento dei browser, che mostrano per 100 millisecondi i fotogrammi GIF con ritardo pari a 0 o 1 centesimo: senza questo accorgimento, una GIF che nel browser appare fluida diventerebbe un WebP riprodotto a velocità vertiginosa. Il metodo CloneFrame estrae un singolo fotogramma come nuova immagine indipendente.

Limitare la memoria

ImageSharp decodifica le immagini in buffer gestiti dal proprio MemoryAllocator, che si può configurare con limiti espliciti. È una seconda linea di difesa rispetto al controllo delle dimensioni con Identify: se un file riuscisse comunque a richiedere un buffer enorme, l'allocazione fallirebbe con un'eccezione invece di esaurire la memoria del processo.

// Startup.cs
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Memory;

namespace WebpToolkit;

public static class ImagingSetup
{
    public static void Configure()
    {
        Configuration.Default.MemoryAllocator = MemoryAllocator.Create(new MemoryAllocatorOptions
        {
            // Un singolo buffer non può superare 256 MB: circa 64 megapixel in Rgba32
            AllocationLimitMegabytes = 256,
            // Memoria trattenuta nel pool per riusarla tra un'immagine e l'altra
            MaximumPoolSizeMegabytes = 128,
        });
    }
}

Un endpoint ASP.NET Core con negoziazione del formato

Quando gli originali restano in JPEG o PNG, il server può servire WebP ai browser che lo dichiarano nell'intestazione Accept, generandolo alla prima richiesta e conservandolo su disco. ASP.NET Core analizza l'intestazione per noi tramite GetTypedHeaders(), che restituisce i tipi accettati con il relativo fattore di qualità. Un ConcurrentDictionary di Lazy<Task> garantisce che più richieste simultanee per la stessa immagine condividano un'unica conversione.

// Program.cs
using System.Collections.Concurrent;
using Microsoft.Net.Http.Headers;
using WebpToolkit;

ImagingSetup.Configure();

// dotnet run -- batch <sorgente> <destinazione> avvia la conversione in blocco
if (args is ["batch", var sourceDir, var targetDir])
{
    return await BatchConverter.RunAsync(sourceDir, targetDir);
}

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

string mediaRoot = Path.GetFullPath("media");
string cacheRoot = Path.GetFullPath("cache");
var sourceTypes = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
{
    [".jpg"] = "image/jpeg",
    [".jpeg"] = "image/jpeg",
    [".png"] = "image/png",
};
var inFlight = new ConcurrentDictionary<string, Lazy<Task>>();

app.MapGet("/media/{**path}", async (string path, HttpContext context, CancellationToken ct) =>
{
    // GetFullPath risolve i ../: il file deve restare dentro la cartella media
    string source = Path.GetFullPath(Path.Combine(mediaRoot, path));
    if (!source.StartsWith(mediaRoot + Path.DirectorySeparatorChar, StringComparison.Ordinal)
        || !sourceTypes.TryGetValue(Path.GetExtension(source), out string? contentType)
        || !File.Exists(source))
    {
        return Results.NotFound();
    }

    context.Response.Headers.Vary = HeaderNames.Accept;
    context.Response.Headers.CacheControl = "public, max-age=86400";

    if (!AcceptsWebp(context.Request))
    {
        return Results.File(source, contentType, enableRangeProcessing: true);
    }

    string target = Path.ChangeExtension(Path.Combine(cacheRoot, Path.GetRelativePath(mediaRoot, source)), ".webp");
    if (!File.Exists(target) || File.GetLastWriteTimeUtc(target) < File.GetLastWriteTimeUtc(source))
    {
        Lazy<Task> conversion = inFlight.GetOrAdd(target, key => new Lazy<Task>(() => ConvertAsync(source, key)));
        try
        {
            await conversion.Value.WaitAsync(ct);
        }
        finally
        {
            inFlight.TryRemove(new KeyValuePair<string, Lazy<Task>>(target, conversion));
        }
    }
    return Results.File(target, "image/webp", enableRangeProcessing: true);
});

await app.RunAsync();
return 0;

static bool AcceptsWebp(HttpRequest request)
{
    // q=0 significa rifiuto esplicito
    return request.GetTypedHeaders().Accept.Any(media =>
        media.MediaType.Equals("image/webp", StringComparison.OrdinalIgnoreCase) && media.Quality is not 0);
}

static async Task ConvertAsync(string source, string target)
{
    Directory.CreateDirectory(Path.GetDirectoryName(target)!);
    await using FileStream input = File.OpenRead(source);
    using var image = await ImageLoader.LoadAsync(input);
    Privacy.StripPersonalMetadata(image);
    await WebpCodec.SaveAsync(image, target, WebpCodec.Photo);
}

Alcuni dettagli meritano una spiegazione. L'intestazione Vary: Accept è impostata per entrambe le risposte: senza di essa una CDN o un proxy potrebbero memorizzare la versione WebP e servirla a un client che non la supporta. Il Lazy<Task> risolve un problema sottile di GetOrAdd: in caso di concorrenza la factory può essere invocata più volte, ma solo uno dei Lazy creati viene inserito nel dizionario, e il Task parte solo quando qualcuno legge Value. La conversione stessa non riceve il token di cancellazione della richiesta: se il primo client chiude la connessione, il lavoro prosegue per gli altri in attesa, mentre WaitAsync(ct) interrompe solo l'attesa di chi se ne va. La rimozione dal dizionario con la coppia chiave-valore, infine, elimina la voce solo se è ancora quella che abbiamo atteso.

Per applicazioni con molte immagini e trasformazioni dinamiche esiste anche ImageSharp.Web, un middleware che gestisce ridimensionamenti tramite parametri della query string, conversione di formato e cache su disco. Lo schema mostrato qui è però sufficiente in molti casi ed è completamente sotto il nostro controllo.

Conversione parallela di un archivio

Parallel.ForEachAsync, disponibile da .NET 6, è lo strumento naturale per elaborare in parallelo una collezione con codice asincrono, con un limite esplicito al grado di parallelismo. La codifica è dominata dalla CPU, quindi il numero di processori è un buon valore di partenza.

// BatchConverter.cs
using System.Diagnostics;

namespace WebpToolkit;

public static class BatchConverter
{
    private static readonly string[] Extensions = [".jpg", ".jpeg", ".png", ".gif"];

    public static async Task<int> RunAsync(string sourceDir, string targetDir, CancellationToken ct = default)
    {
        var files = Directory.EnumerateFiles(sourceDir, "*", SearchOption.AllDirectories)
            .Where(f => Extensions.Contains(Path.GetExtension(f), StringComparer.OrdinalIgnoreCase));

        int converted = 0, failed = 0;
        long saved = 0;
        var stopwatch = Stopwatch.StartNew();

        var options = new ParallelOptions { MaxDegreeOfParallelism = Environment.ProcessorCount, CancellationToken = ct };
        await Parallel.ForEachAsync(files, options, async (source, token) =>
        {
            string target = Path.ChangeExtension(Path.Combine(targetDir, Path.GetRelativePath(sourceDir, source)), ".webp");
            try
            {
                Directory.CreateDirectory(Path.GetDirectoryName(target)!);
                long before = new FileInfo(source).Length;
                long after;
                if (Path.GetExtension(source).Equals(".gif", StringComparison.OrdinalIgnoreCase))
                {
                    after = await Animation.GifToWebpAsync(source, target, ct: token);
                }
                else
                {
                    await using FileStream input = File.OpenRead(source);
                    using var image = await ImageLoader.LoadAsync(input, ct: token);
                    Privacy.StripPersonalMetadata(image);
                    after = await WebpCodec.SaveAsync(image, target, WebpCodec.For(image), token);
                }
                Interlocked.Increment(ref converted);
                Interlocked.Add(ref saved, before - after);
            }
            catch (Exception e) when (e is not OperationCanceledException)
            {
                Interlocked.Increment(ref failed);
                Console.Error.WriteLine($"Errore su {source}: {e.Message}");
            }
        });

        Console.WriteLine($"Convertiti {converted}, falliti {failed}, risparmiati {saved / 1024} KB in {stopwatch.Elapsed.TotalSeconds:F1} s");
        return failed == 0 ? 0 : 1;
    }
}

Il punto di ingresso di Program.cs riconosce gli argomenti con un list pattern: dotnet run -- batch media media-webp esegue la conversione e termina, senza avviare il server. Directory.EnumerateFiles restituisce i percorsi in modo pigro, uno alla volta, quindi anche un archivio enorme non viene mai caricato per intero in memoria. Le operazioni di Interlocked aggiornano i contatori in modo atomico senza bisogno di lock. Il filtro when (e is not OperationCanceledException) lascia propagare la cancellazione, così un Ctrl+C collegato al token interrompe davvero il lavoro invece di essere contato come un fallimento per ogni file.

Test con xUnit

I test vivono in un progetto separato, creato con dotnet new xunit e collegato al principale con dotnet add reference. Generano immagini in memoria con ImageSharp, le codificano nelle tre varianti del formato e verificano il parser; un ultimo test controlla che la pulizia dei metadati rimuova l'EXIF e conservi il profilo colore.

// WebpTests.cs
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats.Webp;
using SixLabors.ImageSharp.Metadata.Profiles.Exif;
using SixLabors.ImageSharp.PixelFormats;
using WebpToolkit;
using Xunit;

public class WebpTests
{
    private static byte[] Encode(byte alpha, WebpFileFormatType format)
    {
        using var image = new Image<Rgba32>(123, 45, new Rgba32(200, 30, 60, alpha));
        using var stream = new MemoryStream();
        image.Save(stream, new WebpEncoder { FileFormat = format, Quality = 80 });
        return stream.ToArray();
    }

    [Theory]
    [InlineData(255, WebpFileFormatType.Lossy, WebpFormat.Lossy, false)]
    [InlineData(128, WebpFileFormatType.Lossless, WebpFormat.Lossless, true)]
    [InlineData(128, WebpFileFormatType.Lossy, WebpFormat.Extended, true)]
    public void ParsesAllVariants(byte alpha, WebpFileFormatType encoding, WebpFormat expected, bool hasAlpha)
    {
        WebpInfo? parsed = WebpInfo.Parse(Encode(alpha, encoding));
        Assert.NotNull(parsed);
        WebpInfo info = parsed.Value;
        Assert.Equal(expected, info.Format);
        Assert.Equal(hasAlpha, info.Alpha);
        Assert.Equal(123, info.Width);
        Assert.Equal(45, info.Height);
    }

    [Fact]
    public void RejectsOtherRiffFiles()
    {
        Assert.Null(WebpInfo.Parse("RIFF\0\0\0\0WAVEfmt                  "u8));
    }

    [Fact]
    public void StripsExifButKeepsIcc()
    {
        using var image = new Image<Rgba32>(10, 10);
        image.Metadata.ExifProfile = new ExifProfile();
        image.Metadata.ExifProfile.SetValue(ExifTag.Model, "Phone");
        image.Metadata.IccProfile = new SixLabors.ImageSharp.Metadata.Profiles.Icc.IccProfile();

        Privacy.StripPersonalMetadata(image);

        Assert.Null(image.Metadata.ExifProfile);
        Assert.NotNull(image.Metadata.IccProfile);
    }
}

Conclusioni

Con ImageSharp, WebP in .NET è un formato come gli altri: si carica con Image.LoadAsync, si trasforma con Mutate e Clone, si salva con un WebpEncoder configurato secondo il contenuto. L'assenza di dipendenze native semplifica il deploy in container, e le funzionalità del linguaggio, da Span e BinaryPrimitives per il parsing ai letterali UTF-8, da Parallel.ForEachAsync ai filtri sulle eccezioni, rendono il codice compatto senza sacrificare la chiarezza. Come in ogni linguaggio, il lavoro che fa la differenza in produzione sta attorno alla codifica: interrogare l'intestazione prima di decodificare, limitare fotogrammi e memoria, applicare l'orientamento prima di togliere l'EXIF, conservare il profilo colore, rispondere con Vary: Accept e condividere le conversioni concorrenti invece di ripeterle.