starred/sharpcompress

Fork 0

mirror of https://github.com/adamhathcock/sharpcompress.git synced 2026-11-15 17:02:03 +00:00

Files

Adam Hathcock ba248dc01e Decode asynchronously buffered LZMA2 chunks with the fast CPU path

2026-10-24 13:37:15 +01:00

34 KiB

Raw Permalink Blame History

API Quick Reference

Quick reference for commonly used SharpCompress APIs.

Factory Methods

Opening Archives

// Auto-detect format
using (var reader = ReaderFactory.OpenReader(stream))
{
    // Works with Zip, Tar, GZip, Rar, etc. Reading 7Zip needs the Archive API
}

// Specific format - Archive API
using (var archive = ZipArchive.OpenArchive("file.zip"))
using (var archive = TarArchive.OpenArchive("file.tar"))
using (var archive = RarArchive.OpenArchive("file.rar"))
using (var archive = SevenZipArchive.OpenArchive("file.7z"))
using (var archive = GZipArchive.OpenArchive("file.gz"))

// With fluent options (preferred)
var options = ReaderOptions.ForEncryptedArchive("password")
    .WithArchiveEncoding(new ArchiveEncoding { Default = Encoding.GetEncoding(932) });
using (var archive = ZipArchive.OpenArchive("encrypted.zip", options))

// Alternative: object initializer
var options2 = new ReaderOptions
{
    Password = "password",
    LeaveStreamOpen = true,
    ArchiveEncoding = new ArchiveEncoding { Default = Encoding.GetEncoding(932) }
};

// Auto-detect and open with the Archive API
using (var archive = ArchiveFactory.OpenArchive("archive.zip"))
{
    foreach (var entry in archive.Entries)
    {
        Console.WriteLine(entry.Key);
    }
}

// Detect before opening (using SharpCompress.Detection)
if (ArchiveDetector.IsArchive("archive.zip", out var archiveType))
{
    Console.WriteLine($"Detected {archiveType}");
}

// Detect the format and choose an API without enumerating entries.
var detection = ArchiveDetector.DetectArchive("archive.tar.xz");
if (detection is not null)
{
    Console.WriteLine($"Container: {detection.ContainerType}");
    Console.WriteLine($"Outer compression: {detection.OuterCompressionType}");
    Console.WriteLine($"Supported APIs: {detection.SupportedApis}");
}

// InspectArchive parses complete archive metadata. It can be expensive for
// sequential formats such as TAR and compressed TAR.
var information = ArchiveInspector.InspectArchive("archive.zip");
if (information is not null)
{
    Console.WriteLine($"Entries: {information.EntryCount}");
    Console.WriteLine($"Solid streams: {information.SolidStreamCount}");
    Console.WriteLine($"Some ZIP entry sizes arrive after their data: {information.Zip?.HasEntriesWithDeferredSizes}");
}

var asyncInformation = await ArchiveInspector.InspectArchiveAsync("archive.zip", cancellationToken);

// Multi-volume archives
var parts = ArchiveFactory.GetFileParts("archive.part1.rar")
    .Select(path => new FileInfo(path))
    .ToArray();
using (var archive = ArchiveFactory.OpenArchive(parts))
{
    archive.WriteToDirectory(@"C:\output");
}

DetectArchive identifies the logical container, its outer compression wrapper, and whether the Archive and Reader APIs are available without enumerating entries. Compressed TAR wrappers such as .tar.gz and .tar.xz are identified as ArchiveType.Tar with an outer compression type and ArchiveAccessMode.Reader.

InspectArchive enumerates metadata and returns ArchiveInformation. It reports Partial status for missing volumes or encrypted headers without a password; malformed archives and incorrect passwords throw. ZIP-specific metadata is exposed through ArchiveInformation.Zip.

Detection and inspection entry points and result types are in the SharpCompress.Detection namespace.

ArchiveDetector also exposes FindFactory<T>, IsArchive, and IsArchiveAsync. SharpCompress.Archives.ArchiveExtractor.WriteToDirectory(sourceArchive, destinationDirectory, options) extracts an archive from a file path. The existing ArchiveFactory versions of these methods remain available for compatibility but are marked obsolete with warnings directing callers to the replacements. Opening, creating archives, and discovering file parts remain on ArchiveFactory.

The stream overloads of DetectArchive and InspectArchive preserve the supplied stream's position and leave it open, including when ReaderOptions.LeaveStreamOpen is false.

Migrating from `GetArchiveInformation`

Removed API	Replacement
`GetArchiveInformation(...)` used only to identify a format	`ArchiveDetector.DetectArchive(...)`
`GetArchiveInformation(...)` used to enumerate archive details	`ArchiveInspector.InspectArchive(...)`
`GetArchiveInformationAsync(...)`	`ArchiveDetector.DetectArchiveAsync(...)` or `ArchiveInspector.InspectArchiveAsync(...)`
`Type`	`Detection.ContainerType`
`SupportsRandomAccess`	`Detection.SupportedApis.HasFlag(ArchiveAccessMode.Archive)`
`ZipDataDescriptorEntryCount`	`Zip.HasEntriesWithDeferredSizes`
`SolidStreamCount`	`SolidStreamCount`

RAR Entry Integrity

RAR Archive and Reader entry streams validate CRC32 (or RAR5 BLAKE2sp when present) on both synchronous and asynchronous extraction paths. Drain an entry stream to the end to perform validation; a mismatch throws InvalidFormatException. Entries without a checksum are extracted without checksum validation. Disposing a partially read Archive entry stream does not validate the unread payload. Reader entry streams normally drain unread data on disposal (synchronous or asynchronous) unless the reader is cancelled, so disposal can validate the checksum and throw on a mismatch. Encrypted entries retain the existing checksum-checking limitations; this does not add authentication for encrypted RAR data.

RAR5 Archive Comments

SharpCompress.Common.Rar.RarVolume.Comment exposes UTF-8 archive comments, including encrypted comments when ReaderOptions.Password is supplied. Comments are loaded while entries are enumerated; the property can be null before enumeration or when no comment is present.

Stored (compression method 0) comments are supported up to 16 MiB of unpacked data; larger or unknown-size comments throw InvalidFormatException. Comments using other compression methods are skipped without affecting entry extraction.

Truncated encrypted comment data throws InvalidFormatException on both synchronous and asynchronous reads. RAR5 KDF counts above 24 are rejected with CryptographicException before deriving encryption keys.

using var archive = RarArchive.OpenArchive(
    "encrypted.rar",
    ReaderOptions.ForFilePath.WithPassword("password")
);
foreach (var entry in archive.Entries)
{
    Console.WriteLine(entry.Key);
}
foreach (var volume in archive.Volumes.OfType<SharpCompress.Common.Rar.RarVolume>())
{
    Console.WriteLine(volume.Comment);
}

Creating Archives

// Writer Factory
using (var writer = WriterFactory.OpenWriter(stream, ArchiveType.Zip, CompressionType.Deflate))
{
    // Write entries
}

// Specific writer
using (var archive = ZipArchive.CreateArchive())
using (var archive = TarArchive.CreateArchive())
using (var archive = GZipArchive.CreateArchive())

// With fluent options (preferred)
var options = WriterOptions.ForZip()
    .WithCompressionLevel(9)
    .WithLeaveStreamOpen(false)
    .WithBufferSize(131072);
using (var archive = ZipArchive.CreateArchive())
{
    archive.SaveTo("output.zip", options);
}

// Alternative: constructor with object initializer
var options2 = new WriterOptions(CompressionType.Deflate)
{
    CompressionLevel = 9,
    LeaveStreamOpen = false,
    BufferSize = 131072
};

WriterOptions.BufferSize controls stream copy buffers used while writing archive entries. If it is not set, SharpCompress falls back to Constants.BufferSize.

Archive API Methods

Reading/Extracting

using (var archive = ZipArchive.OpenArchive("file.zip"))
{
    // Get all entries
    IEnumerable<IArchiveEntry> entries = archive.Entries;

    // Find specific entry
    var entry = archive.Entries.FirstOrDefault(e => e.Key == "file.txt");

    // Extract all
    archive.WriteToDirectory(@"C:\output");

    // Extract single entry
    var firstEntry = archive.Entries.First();
    firstEntry.WriteToFile(@"C:\output\file.txt");

    // Extract single entry to a stream with extraction options
    using (var outputStream = File.Create(@"C:\output\file.txt"))
    {
        firstEntry.WriteTo(
            outputStream,
            new ExtractionOptions { CheckCrc = false }
        );
    }

    // Get entry stream
    using (var stream = entry.OpenEntryStream())
    {
        stream.CopyTo(outputStream);
    }
}

// Async extraction (requires IAsyncArchive)
await using (var asyncArchive = await ZipArchive.OpenAsyncArchive("file.zip"))
{
    // Extract all entries asynchronously
    await asyncArchive.WriteToDirectoryAsync(
        @"C:\output",
        cancellationToken: cancellationToken
    );
}

// Open a specific entry stream asynchronously
await using (var asyncArchive = await ZipArchive.OpenAsyncArchive("file.zip"))
{
    await foreach (var entry in asyncArchive.EntriesAsync)
    {
        await using (var outputStream = File.Create(@"C:\output\" + entry.Key))
        {
            await entry.WriteToAsync(
                outputStream,
                new ExtractionOptions { CheckCrc = false },
                cancellationToken: cancellationToken
            );
        }

        using (var stream = await entry.OpenEntryStreamAsync(cancellationToken))
        {
            // ...
        }
    }
}

Entry Properties

foreach (var entry in archive.Entries)
{
    string name = entry.Key;              // Entry name/path
    long size = entry.Size;               // Uncompressed size
    long compressedSize = entry.CompressedSize;
    bool isDir = entry.IsDirectory;
    DateTime? modTime = entry.LastModifiedTime;
    CompressionType compression = entry.CompressionType;
}

Creating Archives

using (var archive = ZipArchive.CreateArchive())
{
    // Add file
    archive.AddEntry("file.txt", @"C:\source\file.txt");

    // Add multiple files
    archive.AddAllFromDirectory(@"C:\source");
    archive.AddAllFromDirectory(@"C:\source", "*.txt");  // Pattern

    // Save to file
    archive.SaveTo("output.zip", CompressionType.Deflate);

    // Save to stream
    archive.SaveTo(outputStream, new WriterOptions(CompressionType.Deflate)
    {
        CompressionLevel = 9,
        LeaveStreamOpen = true
    });
}

Reader API Methods

Forward-Only Reading

using (var stream = File.OpenRead("file.zip"))
using (var reader = ReaderFactory.OpenReader(stream))
{
    while (reader.MoveToNextEntry())
    {
        IEntry entry = reader.Entry;

        if (!entry.IsDirectory)
        {
            // Extract entry
            reader.WriteEntryToDirectory(@"C:\output");
            reader.WriteEntryToFile(@"C:\output\file.txt");

            // Or get stream
            using (var entryStream = reader.OpenEntryStream())
            {
                entryStream.CopyTo(outputStream);
            }
        }
    }
}

// Async variants (use OpenAsyncReader to get IAsyncReader)
using (var stream = File.OpenRead("file.zip"))
await using (var reader = await ReaderFactory.OpenAsyncReader(stream))
{
    while (await reader.MoveToNextEntryAsync())
    {
        await reader.WriteEntryToFileAsync(
            @"C:\output\" + reader.Entry.Key,
            cancellationToken: cancellationToken
        );
    }

    // Async extraction of all entries
    await reader.WriteAllToDirectoryAsync(
        @"C:\output",
        cancellationToken: cancellationToken
    );
}

Writer API Methods

Creating Archives (Streaming)

using (var stream = File.Create("output.zip"))
using (var writer = WriterFactory.OpenWriter(stream, ArchiveType.Zip, CompressionType.Deflate))
{
    // Write single file
    using (var fileStream = File.OpenRead("source.txt"))
    {
        writer.Write("entry.txt", fileStream, DateTime.Now);
    }
    
    // Write directory
    writer.WriteAll("C:\\source", "*", SearchOption.AllDirectories);
    writer.WriteAll("C:\\source", "*.txt", SearchOption.TopDirectoryOnly);
}

// Async variants: use OpenAsyncWriter to get IAsyncWriter
await using var stream = File.Create("output.zip");
await using var writer = await WriterFactory.OpenAsyncWriter(stream, ArchiveType.Zip, new WriterOptions(CompressionType.Deflate), cancellationToken);

using (var fileStream = File.OpenRead("source.txt"))
{
    await writer.WriteAsync("entry.txt", fileStream, DateTime.Now, cancellationToken);
}

await writer.WriteAllAsync("C:\\source", "*", SearchOption.AllDirectories, cancellationToken);

Common Options

ReaderOptions

Use preset properties and fluent helpers for common configurations:

// External stream with password and custom encoding
var options = ReaderOptions.ForExternalStream
    .WithPassword("password")
    .WithArchiveEncoding(new ArchiveEncoding { Default = Encoding.GetEncoding(932) });

using (var archive = ZipArchive.OpenArchive("file.zip", options))
{
    // ...
}

// Open-time presets
var external = ReaderOptions.ForExternalStream;
var owned = ReaderOptions.ForFilePath;
var encrypted = ReaderOptions.ForEncryptedArchive("password");
var encoded = ReaderOptions.ForEncoding(new ArchiveEncoding { Default = Encoding.UTF8 });
var sfx = ReaderOptions.ForSelfExtractingArchive("password");

// Faster detection when the container is known
var hinted = ReaderOptions.ForExternalStream.WithExtensionHint("tar.gz");

// Increase for non-seekable streams with large detection probes, such as SFX RAR
var buffered = ReaderOptions.ForExternalStream.WithRewindableBufferSize(1_048_576);

// Opt in to formats' optional parallel decode (e.g. 7-Zip's automatic parallel LZMA2
// solid-folder decode); default is sequential decoding
var parallel = ReaderOptions.ForExternalStream.WithEnableParallelism(true);

// Extraction presets
var safeOptions = ExtractionOptions.SafeExtract;  // No overwrite
var flatOptions = ExtractionOptions.FlatExtract;  // No directory structure
var metadataOptions = ExtractionOptions.PreserveMetadata; // Keep timestamps and attributes

// Tune extraction copy buffering
var extractionOptions = new ExtractionOptions
{
    BufferSize = 131072,
    CheckCrc = true, // Default: validate entry checksums when archive metadata provides one
};

// Factory defaults:
// - file path / FileInfo overloads use LeaveStreamOpen = false
// - stream overloads use LeaveStreamOpen = true

Alternative: traditional object initializer:

var options = new ReaderOptions
{
    Password = "password",
    LeaveStreamOpen = true,
    ArchiveEncoding = new ArchiveEncoding { Default = Encoding.GetEncoding(932) },
    ExtensionHint = "zip",
    LookForHeader = true,
    DisableCheckIncomplete = false,
    BufferSize = 81920,
    RewindableBufferSize = 1_048_576,
    EnableParallelism = false,
};

var extractionOptions = new ExtractionOptions
{
    ExtractFullPath = true,
    Overwrite = true,
    BufferSize = 131072,
};

WriterOptions

Factory methods provide a clean, discoverable way to create writer options:

// Factory methods for common archive types
var zipOptions = WriterOptions.ForZip()                           // ZIP with Deflate
    .WithCompressionLevel(9)                                      // 0-9 for Deflate
    .WithLeaveStreamOpen(false);                                  // Close stream when done

var tarOptions = WriterOptions.ForTar(CompressionType.GZip)       // TAR with GZip
    .WithLeaveStreamOpen(false);

var gzipOptions = WriterOptions.ForGZip()                         // GZip file
    .WithCompressionLevel(6);

archive.SaveTo("output.zip", zipOptions);

Use typed writer options when a format exposes extra settings:

WriterFactory.OpenWriter and WriterFactory.OpenAsyncWriter accept ZipWriterOptions through IWriterOptions. UseZip64 supports both seekable and non-seekable output; non-seekable entries use 64-bit data descriptors, even when their final sizes are small. Enable it before writing an entry whose compressed or uncompressed size may reach 4 GiB.

// ZIP archive-level options
var zipWriterOptions = new ZipWriterOptions(CompressionType.Deflate)
{
    ArchiveComment = "Created by SharpCompress",
    UseZip64 = true,
    CompressionLevel = 9,
};

// ZIP per-entry options
using (var writer = new ZipWriter(outputStream, zipWriterOptions))
using (var source = File.OpenRead("source.txt"))
{
    writer.Write("entry.txt", source, new ZipWriterEntryOptions
    {
        CompressionType = CompressionType.ZStandard,
        CompressionLevel = 3,
        EntryComment = "per-entry comment",
        ModificationDateTime = DateTime.UtcNow,
        EnableZip64 = true,
    });
}

// TAR-specific options
var tarOptions = new TarWriterOptions(CompressionType.GZip, finalizeArchiveOnClose: true)
{
    HeaderFormat = TarHeaderWriteFormat.GNU_TAR_LONG_LINK,
};

// GZip-specific options
var gzipOptions = new GZipWriterOptions(compressionLevel: 9);

// 7z writing requires a seekable output stream and writes non-solid archives
var sevenZipOptions = new SevenZipWriterOptions(CompressionType.LZMA2)
{
    CompressHeader = true,
    LzmaProperties = new LzmaEncoderProperties(),
};

Alternative: traditional constructor with object initializer:

var options = new WriterOptions(CompressionType.Deflate)
{
    CompressionLevel = 9,
    LeaveStreamOpen = true,
};
archive.SaveTo("output.zip", options);

WriterOptions.EnableParallelism (also available on ZipWriterOptions, TarWriterOptions, GZipWriterOptions, and SevenZipWriterOptions) opts in to a format's optional parallel encode. No writer currently implements parallel encoding, so this is a no-op today; it is reserved for future use and mirrors ReaderOptions.EnableParallelism.

Extraction behavior

ZipArchiveEntry.OpenEntryStreamAsync and TarArchiveEntry.OpenEntryStreamAsync are virtual and support newly added writable entries as well as entries read from an archive. Opening a new writable entry checks cancellation, rewinds its supplied stream, and returns a non-owning wrapper. Disposing that wrapper leaves the supplied stream open; archive disposal follows the entry's closeStream setting.

var options = new ExtractionOptions
{
    ExtractFullPath = true,                         // Recreate directory structure
    Overwrite = true,                               // Overwrite existing files
    PreserveFileTime = true,                        // Keep original timestamps
    CheckCrc = true                                 // Validate payload checksums when available
};

using (var archive = ZipArchive.OpenArchive("file.zip"))
{
    archive.WriteToDirectory(@"C:\output", options);
}

CheckCrc validates archive-level payload checksums when the format stores reliable metadata, such as ZIP CRC32 values. Formats without payload checksums skip this validation. Decompressor integrity checks that are required to decode a stream may still fail even when CheckCrc is disabled.

WinZip AES authentication is always checked, including when CheckCrc is disabled. Complete or dispose entry streams to verify authentication; plaintext returned before completion must not be treated as authenticated. Invalid authentication tags throw InvalidFormatException, and missing ciphertext or tag bytes throw IncompleteArchiveException.

7z AES key derivation accepts iteration exponents 0 through 24 and the special 0x3F direct-key mode. Larger iteration exponents throw NotSupportedException before key derivation, including when salt and IV are absent.

When using SymbolicLinkHandler, directory extraction rejects link targets outside the extraction root and never follows symbolic links or reparse points while extracting later entries. The handler itself remains trusted application code.

Options matrix

ReaderOptions: open-time behavior (password, encoding, stream ownership)
ExtractionOptions: extract-time behavior (overwrite, paths, timestamps, attributes, symlinks)
WriterOptions: write-time behavior (compression type/level, encoding, stream ownership)
ZipWriterEntryOptions: per-entry ZIP overrides (compression, level, timestamps, comments, zip64)

Compression Providers

ReaderOptions and WriterOptions expose a Providers registry that controls which ICompressionProvider implementations are used for each CompressionType. The registry defaults to CompressionProviderRegistry.Default, so you only need to set it if you want to swap in a custom provider (for example the SystemGZipCompressionProvider or SystemDeflateCompressionProvider). The selected registry is honored by Reader/Writer APIs, Archive APIs, and async entry-stream extraction paths.

var registry = CompressionProviderRegistry.Default
    .With(new SystemGZipCompressionProvider())
    .With(new SystemDeflateCompressionProvider());
var readerOptions = ReaderOptions.ForFilePath.WithProviders(registry);
var writerOptions = new WriterOptions(CompressionType.GZip)
{
    CompressionLevel = 6,
}.WithProviders(registry);

using var reader = ReaderFactory.OpenReader(input, readerOptions);
using var writer = WriterFactory.OpenWriter(output, ArchiveType.GZip, writerOptions);

Registry API summary:

CompressionProviderRegistry.Default: built-in provider registry
CompressionProviderRegistry.Empty: empty registry, primarily useful for tests
With(provider): returns a new registry with that provider added or replaced
GetProvider(type): returns the registered ICompressionProvider, or null
CreateCompressStream(...): creates a compression stream or throws if unsupported
CreateDecompressStream(...): creates a decompression stream or throws if unsupported
CreateCompressStreamAsync(...): async stream creation counterpart
CreateDecompressStreamAsync(...): async stream creation counterpart
GetCompressingProvider(type): returns ICompressionProviderHooks when available

ICompressionProvider implementations declare their CompressionType, whether they support compression/decompression, and create sync/async streams. For simple providers, derive from CompressionProviderBase; it supplies default async implementations that delegate to the synchronous methods. For read-only codecs, derive from DecompressionOnlyProviderBase.

public sealed class CustomGZipProvider : CompressionProviderBase
{
    public override CompressionType CompressionType => CompressionType.GZip;
    public override bool SupportsCompression => true;
    public override bool SupportsDecompression => true;

    public override Stream CreateCompressStream(Stream destination, int compressionLevel) =>
        new GZipStream(destination, CompressionMode.Compress, leaveOpen: false);

    public override Stream CreateDecompressStream(Stream source) =>
        new GZipStream(source, CompressionMode.Decompress, leaveOpen: false);
}

CompressionContext carries metadata that providers may need when creating streams, including InputSize, OutputSize, Properties, CanSeek, FormatOptions, and ReaderOptions. Use CompressionContext.FromStream(stream) to populate stream-derived values, WithReaderOptions(...) to attach reader metadata, and ResolveArchiveEncoding() to get the archive header encoding from the context.

When a format needs additional initialization/finalization data (LZMA, PPMd, etc.) the registry exposes GetCompressingProvider which returns the ICompressionProviderHooks contract; the rest of the API continues to flow through Providers, including pre/properties/post compression hook data.

Compression Types

Available Compressions

// For creating archives
CompressionType.None       // No compression (store)
CompressionType.GZip       // GZip wrapper/combined tar compression
CompressionType.Deflate    // DEFLATE (default for ZIP/GZip)
CompressionType.Deflate64  // Deflate64
CompressionType.BZip2      // BZip2
CompressionType.LZMA       // LZMA (for 7Zip, LZip, XZ)
CompressionType.LZMA2      // LZMA2 (for 7Zip/XZ)
CompressionType.BCJ        // 7Zip branch converter filter
CompressionType.BCJ2       // 7Zip branch converter filter
CompressionType.LZip       // LZip wrapper/combined tar compression
CompressionType.Xz         // XZ wrapper/combined tar compression
CompressionType.PPMd       // PPMd (for ZIP)
CompressionType.Rar        // RAR compression (read-only)
CompressionType.Lzw        // LZW, including .Z/tar.Z reading
CompressionType.Shrink     // ZIP shrink (read-only)
CompressionType.Reduce1    // ZIP reduce methods (read-only)
CompressionType.Reduce2
CompressionType.Reduce3
CompressionType.Reduce4
CompressionType.Explode    // ZIP implode/explode (read-only)
CompressionType.Squeezed   // ARC/ARJ legacy compression (read-only)
CompressionType.Packed     // ARC legacy compression (read-only)
CompressionType.Crunched   // ARC legacy compression (read-only)
CompressionType.Squashed   // Legacy compression (read-only)
CompressionType.Crushed    // Legacy compression (read-only)
CompressionType.Distilled  // Legacy compression (read-only)
CompressionType.ZStandard  // ZStandard
CompressionType.ArjLZ77    // ARJ compression (read-only)
CompressionType.AceLZ77    // ACE compression (read-only)
CompressionType.Unknown

// For Tar archives with compression
// Use WriterFactory to create compressed tar archives
using (var writer = WriterFactory.OpenWriter(stream, ArchiveType.Tar, CompressionType.GZip))  // Tar.GZip
using (var writer = WriterFactory.OpenWriter(stream, ArchiveType.Tar, CompressionType.BZip2)) // Tar.BZip2

Archive Types

ArchiveType.Zip
ArchiveType.Tar
ArchiveType.GZip
ArchiveType.Rar
ArchiveType.SevenZip
ArchiveType.Arc
ArchiveType.Arj
ArchiveType.Ace
ArchiveType.Lzw

Patterns & Examples

Extract with Error Handling

try
{
    using (var archive = ZipArchive.OpenArchive("archive.zip", 
        ReaderOptions.ForEncryptedArchive("password")))
    {
        archive.WriteToDirectory(@"C:\output");
    }
}
catch (CryptographicException)
{
    Console.WriteLine("Password required");
}
catch (ArchiveException)
{
    Console.WriteLine("Archive is invalid");
}
catch (SharpCompressException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Extract with Progress

var progress = new Progress<ProgressReport>(report =>
{
    Console.WriteLine($"Extracting {report.EntryPath}: {report.PercentComplete}%");
});

var options = ReaderOptions.ForFilePath.WithProgress(progress);
using (var archive = ZipArchive.OpenArchive("archive.zip", options))
{
    archive.WriteToDirectory(@"C:\output");
}

Async Extract with Cancellation

Async archive and reader/writer operations dispose SharpCompress resources asynchronously on every target, including .NET Framework 4.8 and .NET Standard 2.0. SharpCompressStream.DisposeAsync() and ZlibStream.DisposeAsync() are available on every target; stream wrappers forward disposal to runtime IAsyncDisposable implementations where available, falling back to synchronous disposal only for streams that do not support it.

var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromMinutes(5));

try
{
    await using (var archive = await ZipArchive.OpenAsyncArchive("archive.zip"))
    {
        await archive.WriteToDirectoryAsync(
            @"C:\output",
            cancellationToken: cts.Token
        );
    }
}
catch (OperationCanceledException)
{
    Console.WriteLine("Extraction cancelled");
}

Create with Custom Compression

using (var archive = ZipArchive.CreateArchive())
{
    archive.AddAllFromDirectory(@"D:\source");
    
    // Fastest
    archive.SaveTo("fast.zip", new WriterOptions(CompressionType.Deflate)
    {
        CompressionLevel = 1
    });
    
    // Balanced (default)
    archive.SaveTo("normal.zip", CompressionType.Deflate);
    
    // Best compression
    archive.SaveTo("best.zip", new WriterOptions(CompressionType.Deflate)
    {
        CompressionLevel = 9
    });
}

Stream Processing (No File I/O)

using (var outputStream = new MemoryStream())
using (var archive = ZipArchive.CreateArchive())
{
    // Add content from memory
    using (var contentStream = new MemoryStream(Encoding.UTF8.GetBytes("Hello")))
    {
        archive.AddEntry("file.txt", contentStream);
    }
    
    // Save to memory
    archive.SaveTo(outputStream, CompressionType.Deflate);
    
    // Get bytes
    byte[] archiveBytes = outputStream.ToArray();
}

Buffered Forward-Only Streams

SharpCompressStream can wrap streams with buffering for forward-only scenarios:

// Wrap a non-seekable stream with buffering
using (var bufferedStream = new SharpCompressStream(rawStream))
{
    // Provides ring buffer functionality for reading ahead
    // and seeking within buffered data
    using (var reader = ReaderFactory.OpenReader(bufferedStream))
    {
        while (reader.MoveToNextEntry())
        {
            reader.WriteEntryToDirectory(@"C:\output");
        }
    }
}

Useful for:

Non-seekable streams (network streams, pipes)
Forward-only reading with limited look-ahead
Buffering unbuffered streams for better performance

Extract Specific Files

using (var archive = ZipArchive.OpenArchive("archive.zip"))
{
    var filesToExtract = new[] { "file1.txt", "file2.txt" };
    
    foreach (var entry in archive.Entries.Where(e => filesToExtract.Contains(e.Key)))
    {
        entry.WriteToFile(@"C:\output\" + entry.Key);
    }
}

List Archive Contents

using (var archive = ZipArchive.OpenArchive("archive.zip"))
{
    foreach (var entry in archive.Entries)
    {
        if (entry.IsDirectory)
            Console.WriteLine($"[DIR]  {entry.Key}");
        else
            Console.WriteLine($"[FILE] {entry.Key} ({entry.Size} bytes)");
    }
}

Common Mistakes

✗ Wrong - Stream not disposed

var stream = File.OpenRead("archive.zip");
var archive = ZipArchive.OpenArchive(stream);
archive.WriteToDirectory(@"C:\output");
// stream not disposed - leaked resource

✓ Correct - Using blocks

using (var stream = File.OpenRead("archive.zip"))
using (var archive = ZipArchive.OpenArchive(stream))
{
    archive.WriteToDirectory(@"C:\output");
}
// Both properly disposed

✗ Wrong - Mixing API styles

// Loading entire archive then iterating
using (var archive = ZipArchive.OpenArchive("large.zip"))
{
    var entries = archive.Entries.ToList();  // Loads all in memory
    foreach (var e in entries)
    {
        e.WriteToFile(...);  // Then extracts each
    }
}

✓ Correct - Use Reader for large files

// Streaming iteration
using (var stream = File.OpenRead("large.zip"))
using (var reader = ReaderFactory.OpenReader(stream))
{
    while (reader.MoveToNextEntry())
    {
        reader.WriteEntryToDirectory(@"C:\output");
    }
}

Low-Level XZ Memory Reads

On .NET 6 and later, SharpCompress.Compressors.Xz.XZStream and XZBlock override ReadAsync(Memory<byte>, CancellationToken) with a native ValueTask read path. Array-backed and custom/native memory are supported; CRC32, CRC64, and SHA-256 checks remain enabled. SHA-256 uses a bounded pooled scratch buffer when the destination memory cannot expose an array. Read through EOF to validate the complete stream, including its final block check.

using var input = File.OpenRead("input.tar.xz");
using var xz = new SharpCompress.Compressors.Xz.XZStream(input);
using var output = File.Create("output.tar");
var buffer = new byte[65536];
int read;
while ((read = await xz.ReadAsync(buffer.AsMemory(), cancellationToken)) != 0)
{
    await output.WriteAsync(buffer.AsMemory(0, read), cancellationToken);
}

Disposing these low-level XZ streams releases their owned filter buffers without closing the caller-provided input; dispose the input separately. The existing array-based async signatures are unchanged.

CRC-Checking Stream Lifetime

SharpCompressStream rejects reading and starting recording after disposal. Its pooled ring buffer is released even when disposal of the underlying stream fails.

LzmaStream also rejects reads and writes after disposal. Failed initialization releases internal buffers without closing the supplied stream; successful construction retains the specified leaveOpen semantics. Disposal releases internal buffers even if finalization or underlying stream disposal throws.

On modern .NET targets, async LZMA2 reads may prefetch the current compressed chunk (at most 64 KiB) using async I/O before producing output. They never prefetch the following chunk header. Decoding the buffered payload uses CPU-only batches of at most 16 KiB of output between cancellation checks. Cancellation or failure during a partial fill does not permit unsafe decoding of uninitialized bytes; disposing the stream returns the input lease. Raw LZMA and legacy-target async decoding retain their existing streaming paths.

SharpCompress.Compressors.LZMA.Utilities.CrcCheckStream validates its expected CRC on disposal. A mismatch throws ArchiveOperationException, but pooled buffers are still released. Repeated disposal is safe, including after failed CRC validation. Once disposed, CanWrite is false, and Write / WriteAsync throw ObjectDisposedException.

USAGE.md - Complete code examples
FORMATS.md - Supported formats
PERFORMANCE.md - API selection guide

7z Decoder Lifetime

Both Dispose() and DisposeAsync() release a 7z archive's cached folder decoder, including after partially reading an entry. Temporary encoded-header decoders are released after parsing or validation failure. Decoder cleanup returns pooled input and dictionary buffers without closing a borrowed archive source; the archive's LeaveStreamOpen setting still controls source ownership.

For solid archives, prefer ExtractAllEntries() / ExtractAllEntriesAsync() to reuse the folder decoder across entries. A reader borrowed from an archive can be disposed without closing that archive's source.

7z Encrypted Decoding Errors

AES-encrypted 7z codec data errors and encrypted-header CRC failures throw SharpCompress.Common.CryptographicException, with the original decoder error in InnerException. The exception can indicate either an incorrect password or corrupt encrypted data; 7z AES has no independent password verifier. CryptographicException(string message, Exception inner) preserves an underlying failure. Unencrypted codec errors retain their existing behavior. This does not guarantee detection of every incorrect password, particularly for data without compression or integrity checking.

7z Encryption Detection

For 7z archives, IsEncrypted is true when any entry has an AES-encrypted data stream. Streamless empty files and directories are not encrypted. Archives without files return false.

34 KiB Raw Permalink Blame History

API Quick Reference

Factory Methods

Opening Archives

Migrating from GetArchiveInformation

RAR Entry Integrity

RAR5 Archive Comments

Creating Archives

Archive API Methods

Reading/Extracting

Entry Properties

Creating Archives

Reader API Methods

Forward-Only Reading

Writer API Methods

Creating Archives (Streaming)

Common Options

ReaderOptions

WriterOptions

Extraction behavior

Options matrix

Compression Providers

Compression Types

Available Compressions

Archive Types

Patterns & Examples

Extract with Error Handling

Extract with Progress

Async Extract with Cancellation

Create with Custom Compression

Stream Processing (No File I/O)

Buffered Forward-Only Streams

Extract Specific Files

List Archive Contents

Common Mistakes

✗ Wrong - Stream not disposed

✓ Correct - Using blocks

✗ Wrong - Mixing API styles

✓ Correct - Use Reader for large files

Low-Level XZ Memory Reads

CRC-Checking Stream Lifetime

Related Documentation

7z Decoder Lifetime

7z Encrypted Decoding Errors

7z Encryption Detection

34 KiB

Raw Permalink Blame History

Migrating from `GetArchiveInformation`