C# e i formati di compressione

.NET offre oggi uno degli ecosistemi di compressione più completi tra le piattaforme gestite, e con .NET 11 si aggiunge anche Zstandard. Le API seguono un modello coerente basato su stream, affiancato da encoder senza allocazioni per i percorsi critici.

C# di Gabriele Romanato

Il namespace System.IO.Compression di .NET si è evoluto molto rispetto ai tempi del .NET Framework: oggi offre Gzip, DEFLATE, zlib e Brotli come stream, encoder Brotli basati su Span<T> senza allocazioni, archivi ZIP con ZipArchive e ZipFile e, da .NET 7, anche archivi TAR con System.Formats.Tar. In questo articolo vediamo come usare tutte queste API con C# moderno, dalla compressione in memoria a quella asincrona in streaming, dalla configurazione fine dei parametri all'estrazione sicura degli archivi.

Gli stream di compressione

Il cuore del namespace è costituito da quattro classi derivate da Stream, che seguono il pattern decorator: avvolgono uno stream sottostante e comprimono ciò che vi si scrive, oppure decomprimono ciò che se ne legge.

  • DeflateStream produce DEFLATE raw (RFC 1951), senza intestazioni;
  • ZLibStream, introdotto in .NET 6, produce il formato zlib (RFC 1950), quello che in HTTP corrisponde a Content-Encoding: deflate;
  • GZipStream produce il formato Gzip (RFC 1952), compatibile con i file .gz;
  • BrotliStream produce il formato Brotli (RFC 7932).

Da .NET 9 la famiglia DEFLATE si appoggia su tutte le piattaforme a zlib-ng, una versione moderna e ottimizzata di zlib distribuita insieme al runtime, mentre Brotli usa la libreria di riferimento di Google: il comportamento è quindi lo stesso su Windows, Linux e macOS, senza dipendere dalla zlib di sistema.

Compressione in memoria

La direzione dello stream si sceglie nel costruttore: passando un CompressionLevel si ottiene uno stream di compressione, passando CompressionMode.Decompress uno di decompressione. Come in tutti i formati con trailer, i dati compressi sono completi solo dopo la chiusura dello stream, per cui il risultato va letto dopo il Dispose.

using System.IO.Compression;
using System.Text;
using System.Text.Json;

static byte[] Compress(ReadOnlySpan<byte> data, Func<Stream, Stream> createEncoder)
{
    using var output = new MemoryStream();
    // Il blocco using interno chiude l'encoder e scrive il trailer prima di leggere l'output
    using (var encoder = createEncoder(output))
    {
        encoder.Write(data);
    }
    return output.ToArray();
}

static byte[] Decompress(byte[] data, Func<Stream, Stream> createDecoder)
{
    using var input = new MemoryStream(data);
    using var decoder = createDecoder(input);
    using var output = new MemoryStream();
    decoder.CopyTo(output);
    return output.ToArray();
}

var users = Enumerable.Range(1, 1000).Select(i => new { Id = i, Name = $"user-{i}", Active = i % 2 == 0 });
byte[] payload = JsonSerializer.SerializeToUtf8Bytes(new { Users = users });

byte[] gzip = Compress(payload, s => new GZipStream(s, CompressionLevel.Optimal, leaveOpen: true));
byte[] zlib = Compress(payload, s => new ZLibStream(s, CompressionLevel.Optimal, leaveOpen: true));
byte[] brotli = Compress(payload, s => new BrotliStream(s, CompressionLevel.Optimal, leaveOpen: true));

Console.WriteLine($"Originale: {payload.Length,8} byte");
Console.WriteLine($"Gzip:      {gzip.Length,8} byte");
Console.WriteLine($"Zlib:      {zlib.Length,8} byte");
Console.WriteLine($"Brotli:    {brotli.Length,8} byte");

byte[] restored = Decompress(gzip, s => new GZipStream(s, CompressionMode.Decompress));
Console.WriteLine(restored.AsSpan().SequenceEqual(payload)); // True

Il parametro leaveOpen: true impedisce che la chiusura dell'encoder chiuda anche il MemoryStream sottostante, che altrimenti diventerebbe inutilizzabile. In realtà MemoryStream.ToArray funziona anche su uno stream chiuso, ma con altri tipi di stream questo dettaglio è fondamentale.

Livelli e opzioni di compressione

L'enumerazione CompressionLevel offre quattro valori astratti: NoCompression, Fastest, Optimal e SmallestSize (introdotto in .NET 6). La corrispondenza con i livelli numerici dipende dal codec: per la famiglia DEFLATE Optimal corrisponde al livello 6 e SmallestSize al 9; per Brotli Optimal corrisponde alla qualità 4 e SmallestSize alla 11.

Per un controllo più fine, .NET 9 ha introdotto le classi ZLibCompressionOptions e BrotliCompressionOptions, che permettono di specificare il livello numerico esatto e, per la famiglia DEFLATE, anche la strategia di compressione. Le opzioni zlib si applicano a tutti e tre gli stream della famiglia.

using System.Diagnostics;
using System.IO.Compression;

byte[] input = File.ReadAllBytes(args.Length > 0 ? args[0] : "data.json");

void Measure(string label, Func<Stream, Stream> createEncoder)
{
    var stopwatch = Stopwatch.StartNew();
    using var output = new MemoryStream();
    using (var encoder = createEncoder(output))
    {
        encoder.Write(input);
    }
    stopwatch.Stop();
    double ratio = (double)output.Length / input.Length;
    Console.WriteLine($"{label,-14} {output.Length,10} byte {ratio,7:P1} {stopwatch.Elapsed.TotalMilliseconds,8:F2} ms");
}

foreach (int level in new[] { 1, 6, 9 })
{
    var options = new ZLibCompressionOptions
    {
        CompressionLevel = level,
        CompressionStrategy = ZLibCompressionStrategy.Default
    };
    Measure($"gzip -{level}", s => new GZipStream(s, options, leaveOpen: true));
}

foreach (int quality in new[] { 4, 6, 11 })
{
    var options = new BrotliCompressionOptions { Quality = quality };
    Measure($"brotli q{quality}", s => new BrotliStream(s, options, leaveOpen: true));
}

Le strategie disponibili sono Default, Filtered, HuffmanOnly, RunLengthEncoding e Fixed, con lo stesso significato che hanno nella libreria zlib in C.

Brotli senza allocazioni

Per gli scenari in cui le prestazioni sono critiche, come un server che comprime migliaia di piccoli messaggi al secondo, le struct BrotliEncoder e BrotliDecoder lavorano direttamente su Span<byte>, senza creare stream né allocare buffer intermedi. Il metodo statico TryCompress comprime in un colpo solo in un buffer preallocato, che si può dimensionare con GetMaxCompressedLength e prendere in prestito da ArrayPool.

using System.Buffers;
using System.IO.Compression;
using System.Text;

static byte[] BrotliCompress(ReadOnlySpan<byte> source, int quality = 5, int window = 22)
{
    int maxLength = BrotliEncoder.GetMaxCompressedLength(source.Length);
    byte[] rented = ArrayPool<byte>.Shared.Rent(maxLength);
    try
    {
        if (!BrotliEncoder.TryCompress(source, rented, out int written, quality, window))
        {
            throw new InvalidOperationException("Buffer di destinazione insufficiente");
        }
        return rented.AsSpan(0, written).ToArray();
    }
    finally
    {
        ArrayPool<byte>.Shared.Return(rented);
    }
}

static byte[] BrotliDecompress(ReadOnlySpan<byte> source, int maxOutput)
{
    byte[] buffer = new byte[maxOutput];
    // TryDecompress fallisce anche se l'output non entra nel buffer: un limite naturale
    if (!BrotliDecoder.TryDecompress(source, buffer, out int written))
    {
        throw new InvalidDataException("Dati Brotli non validi o oltre il limite");
    }
    return buffer.AsSpan(0, written).ToArray();
}

byte[] message = Encoding.UTF8.GetBytes(string.Concat(Enumerable.Repeat("{\"event\":\"click\",\"page\":\"/home\"}", 200)));
byte[] compressed = BrotliCompress(message, quality: 6);
byte[] restored = BrotliDecompress(compressed, maxOutput: 1024 * 1024);

Console.WriteLine($"{message.Length} -> {compressed.Length} byte, identici: {restored.AsSpan().SequenceEqual(message)}");

Streaming asincrono di file

Per file di grandi dimensioni e per il codice server, le API asincrone evitano di bloccare i thread durante l'I/O. CopyToAsync accetta un CancellationToken, il che permette di interrompere un'operazione lunga, ad esempio quando il client chiude la connessione.

using System.IO.Compression;
using System.Text;

await GzipFiles.CompressAsync("app.log", "app.log.gz");
Console.WriteLine($"Errori: {await GzipFiles.CountMatchingLinesAsync("app.log.gz", " ERROR ")}");

public static class GzipFiles
{
    private const int BufferSize = 81920;

    public static async Task CompressAsync(string source, string destination, CancellationToken ct = default)
    {
        await using var input = new FileStream(source, FileMode.Open, FileAccess.Read, FileShare.Read, BufferSize, useAsync: true);
        await using var output = new FileStream(destination, FileMode.Create, FileAccess.Write, FileShare.None, BufferSize, useAsync: true);
        await using var gzip = new GZipStream(output, CompressionLevel.SmallestSize);
        await input.CopyToAsync(gzip, BufferSize, ct);
    }

    // Conta le righe che contengono un testo in un file compresso, senza caricarlo in memoria
    public static async Task<int> CountMatchingLinesAsync(string gzipPath, string needle, CancellationToken ct = default)
    {
        await using var file = File.OpenRead(gzipPath);
        await using var gzip = new GZipStream(file, CompressionMode.Decompress);
        using var reader = new StreamReader(gzip, Encoding.UTF8);

        int count = 0;
        while (await reader.ReadLineAsync(ct) is { } line)
        {
            if (line.Contains(needle, StringComparison.Ordinal))
            {
                count++;
            }
        }
        return count;
    }
}

L'ordine delle dichiarazioni await using conta: le risorse vengono rilasciate in ordine inverso, quindi il GZipStream viene chiuso prima del FileStream e ha la possibilità di scrivere il trailer. GZipStream in decompressione gestisce inoltre automaticamente i file multi-membro, cioè più flussi Gzip concatenati.

Zstandard

Zstandard è entrato nella libreria di base con .NET 11, attualmente in anteprima, tramite la classe ZstandardStream, che segue lo stesso modello degli altri stream di compressione e aggiunge il supporto ai dizionari e alle opzioni avanzate tramite ZstandardCompressionOptions.

using System.IO.Compression;

// Richiede .NET 11: l'API è ancora in anteprima e potrebbe cambiare prima del rilascio
await using var output = File.Create("events.jsonl.zst");
await using var zstd = new ZstandardStream(output, CompressionLevel.Optimal);
await using var input = File.OpenRead("events.jsonl");
await input.CopyToAsync(zstd);

Sulle versioni stabili di .NET la scelta più diffusa è il pacchetto NuGet ZstdSharp.Port, un porting in puro C# della libreria di riferimento, che non richiede librerie native e offre sia API in memoria sia stream.

using System.Text;
using ZstdSharp;

byte[] data = Encoding.UTF8.GetBytes(string.Concat(Enumerable.Repeat("{\"level\":\"info\",\"msg\":\"ok\"}\n", 5000)));

// Il livello va da 1 a 22; Compressor e Decompressor sono riutilizzabili
using var compressor = new Compressor(level: 10);
using var decompressor = new Decompressor();

byte[] compressed = compressor.Wrap(data).ToArray();
byte[] restored = decompressor.Unwrap(compressed).ToArray();

Console.WriteLine($"{data.Length} -> {compressed.Length} byte, identici: {restored.AsSpan().SequenceEqual(data)}");

// Versione in streaming
await using (var file = File.Create("data.zst"))
await using (var zstd = new CompressionStream(file, level: 10))
{
    await zstd.WriteAsync(data);
}

Compressione delle risposte in ASP.NET Core

ASP.NET Core include un middleware di compressione delle risposte che gestisce in automatico la negoziazione con Accept-Encoding, l'intestazione Vary e l'esclusione dei tipi MIME non comprimibili. La compressione su HTTPS è disabilitata per default a causa degli attacchi di tipo BREACH e va abilitata esplicitamente, valutando se le risposte contengono segreti riflessi insieme a input dell'utente.

using System.IO.Compression;
using Microsoft.AspNetCore.ResponseCompression;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    // L'ordine dei provider determina la preferenza a parità di qualità richiesta dal client
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
    options.MimeTypes = ResponseCompressionDefaults.MimeTypes.Concat(["image/svg+xml", "application/x-ndjson"]);
});

// Per la compressione al volo un livello basso è il compromesso migliore
builder.Services.Configure<BrotliCompressionProviderOptions>(o => o.Level = CompressionLevel.Fastest);
builder.Services.Configure<GzipCompressionProviderOptions>(o => o.Level = CompressionLevel.Optimal);

var app = builder.Build();
app.UseResponseCompression();

app.MapGet("/api/items", () => Enumerable.Range(1, 2000).Select(i => new { Id = i, Name = $"item-{i}" }));

app.Run();

Lato client, HttpClient decomprime automaticamente le risposte se lo si configura tramite SocketsHttpHandler.AutomaticDecompression, ad esempio con DecompressionMethods.All: il gestore aggiunge l'intestazione Accept-Encoding e restituisce il contenuto già decompresso.

Archivi ZIP

Per le operazioni più comuni la classe statica ZipFile offre CreateFromDirectory ed ExtractToDirectory. Per un controllo completo si usa ZipArchive, che rappresenta l'archivio come una collezione di ZipArchiveEntry e può essere aperto in modalità Create, Read o Update.

using System.IO.Compression;

ZipBuilder.FromDirectory("docs", "docs.zip");
ZipBuilder.AddTextEntry("docs.zip", "VERSION.txt", $"build {DateTime.UtcNow:yyyyMMddHHmm}");

public static class ZipBuilder
{
    // Estensioni di file già compressi
    private static readonly HashSet<string> Stored = new(StringComparer.OrdinalIgnoreCase)
    {
        ".jpg", ".jpeg", ".png", ".gif", ".webp", ".mp4", ".zip", ".gz", ".pdf"
    };

    public static void FromDirectory(string sourceDir, string zipPath)
    {
        using var zip = ZipFile.Open(zipPath, ZipArchiveMode.Create);

        foreach (string path in Directory.EnumerateFiles(sourceDir, "*", SearchOption.AllDirectories).Order())
        {
            // Nei file ZIP il separatore è sempre lo slash
            string entryName = Path.GetRelativePath(sourceDir, path).Replace('\\', '/');
            var level = Stored.Contains(Path.GetExtension(path))
                ? CompressionLevel.NoCompression
                : CompressionLevel.SmallestSize;

            zip.CreateEntryFromFile(path, entryName, level);
        }
    }

    public static void AddTextEntry(string zipPath, string entryName, string content)
    {
        using var zip = ZipFile.Open(zipPath, ZipArchiveMode.Update);
        zip.GetEntry(entryName)?.Delete();

        var entry = zip.CreateEntry(entryName, CompressionLevel.Optimal);
        using var writer = new StreamWriter(entry.Open());
        writer.Write(content);
    }
}

La modalità Update carica in memoria il contenuto delle voci modificate e riscrive l'archivio alla chiusura: con archivi di grandi dimensioni conviene invece crearne uno nuovo in modalità Create, che scrive in streaming senza mantenere nulla in memoria.

Estrazione sicura degli archivi ZIP

ZipFile.ExtractToDirectory e ZipArchiveEntry.ExtractToFile sono già protetti contro lo zip slip: se una voce si risolve fuori dalla directory di destinazione lanciano una IOException. Nessuna protezione è invece prevista contro le decompression bomb, e la proprietà Length di una voce riporta la dimensione dichiarata nell'archivio, che un attaccante può falsificare. Un'estrazione robusta di archivi caricati dagli utenti deve quindi contare i byte effettivamente scritti.

using System.IO.Compression;

await SafeUnzip.ExtractAsync("upload.zip", "extracted");

public sealed class UnsafeArchiveException(string message) : IOException(message);

public sealed record ExtractionLimits(int MaxEntries = 10_000, long MaxTotalBytes = 1L << 30, double MaxRatio = 200);

public static class SafeUnzip
{
    public static async Task ExtractAsync(string zipPath, string destination, ExtractionLimits? limits = null, CancellationToken ct = default)
    {
        limits ??= new ExtractionLimits();
        string root = Path.GetFullPath(destination);
        // Il separatore finale evita che /tmp/out-evil risulti dentro /tmp/out
        string rootWithSeparator = Path.EndsInDirectorySeparator(root) ? root : root + Path.DirectorySeparatorChar;
        Directory.CreateDirectory(root);

        using var zip = ZipFile.OpenRead(zipPath);
        if (zip.Entries.Count > limits.MaxEntries)
        {
            throw new UnsafeArchiveException($"Troppe voci: {zip.Entries.Count}");
        }

        long written = 0;
        byte[] buffer = new byte[81920];

        foreach (var entry in zip.Entries)
        {
            string target = Path.GetFullPath(Path.Combine(root, entry.FullName));
            if (!target.StartsWith(rootWithSeparator, StringComparison.Ordinal))
            {
                throw new UnsafeArchiveException($"Percorso non sicuro: {entry.FullName}");
            }
            if (entry.CompressedLength > 0 && (double)entry.Length / entry.CompressedLength > limits.MaxRatio)
            {
                throw new UnsafeArchiveException($"Rapporto di compressione sospetto: {entry.FullName}");
            }

            // Le voci che terminano con lo slash sono directory
            if (entry.FullName.EndsWith('/'))
            {
                Directory.CreateDirectory(target);
                continue;
            }

            Directory.CreateDirectory(Path.GetDirectoryName(target)!);
            await using var input = entry.Open();
            await using var output = File.Create(target);

            int read;
            while ((read = await input.ReadAsync(buffer, ct)) > 0)
            {
                written += read;
                if (written > limits.MaxTotalBytes)
                {
                    throw new UnsafeArchiveException("Dimensione totale estratta oltre il limite");
                }
                await output.WriteAsync(buffer.AsMemory(0, read), ct);
            }
        }
    }
}

Su Windows il confronto tra percorsi andrebbe fatto con StringComparison.OrdinalIgnoreCase, dato che il file system non distingue maiuscole e minuscole; su Linux il confronto ordinale è quello corretto.

Archivi TAR con System.Formats.Tar

Da .NET 7 il namespace System.Formats.Tar legge e scrive archivi TAR nei formati V7, UStar, PAX e GNU. Come in tutti gli altri linguaggi, la compressione si ottiene componendo l'archivio con uno stream di compressione: per un .tar.gz basta passare un GZipStream come destinazione.

using System.Formats.Tar;
using System.IO.Compression;

await TarGz.CreateAsync("project", "project.tar.gz");
await TarGz.ListAsync("project.tar.gz");
await TarGz.ExtractAsync("project.tar.gz", "restored");

public static class TarGz
{
    public static async Task CreateAsync(string sourceDir, string archivePath, CancellationToken ct = default)
    {
        await using var file = File.Create(archivePath);
        await using var gzip = new GZipStream(file, CompressionLevel.SmallestSize);
        // includeBaseDirectory: false archivia il contenuto senza la directory radice
        await TarFile.CreateFromDirectoryAsync(sourceDir, gzip, includeBaseDirectory: false, ct);
    }

    public static async Task ListAsync(string archivePath, CancellationToken ct = default)
    {
        await using var file = File.OpenRead(archivePath);
        await using var gzip = new GZipStream(file, CompressionMode.Decompress);
        await using var reader = new TarReader(gzip);

        while (await reader.GetNextEntryAsync(copyData: false, ct) is { } entry)
        {
            Console.WriteLine($"{entry.EntryType,-16} {entry.Length,10} {entry.Name}");
        }
    }

    public static async Task ExtractAsync(string archivePath, string destination, CancellationToken ct = default)
    {
        Directory.CreateDirectory(destination);
        await using var file = File.OpenRead(archivePath);
        await using var gzip = new GZipStream(file, CompressionMode.Decompress);
        await TarFile.ExtractToDirectoryAsync(gzip, destination, overwriteFiles: false, ct);
    }
}

Anche TarFile.ExtractToDirectory verifica che le voci e i target dei link restino all'interno della destinazione. Per archivi di provenienza esterna, tuttavia, è preferibile iterare con TarReader, sommare le dimensioni con entry.Length, ignorare i tipi di voce diversi da file regolari e directory, e scrivere i file con entry.ExtractToFileAsync solo dopo aver validato percorso e dimensione.

Conclusioni

.NET offre oggi uno degli ecosistemi di compressione più completi tra le piattaforme gestite, e con .NET 11 si aggiunge anche Zstandard. Le API seguono un modello coerente basato su stream, affiancato da encoder senza allocazioni per i percorsi critici. Le regole pratiche sono quelle di sempre: chiudere gli stream di compressione prima di leggere il risultato, scegliere livelli bassi per la compressione al volo e alti per gli asset statici, valutare il rischio BREACH prima di comprimere su HTTPS e non fidarsi mai delle dimensioni dichiarate negli archivi caricati dagli utenti.