Skip to content

USAGE.md

Latest commit

 

History

History
473 lines (388 loc) · 15.6 KB

USAGE.md

File metadata and controls

473 lines (388 loc) · 15.6 KB

SharpCompress Usage

Async/Await Support

SharpCompress now provides full async/await support for all I/O operations. All Read, Write, and extraction operations have async equivalents ending in Async that accept an optional CancellationToken. This enables better performance and scalability for I/O-bound operations.

Key Async Methods:

  • reader.WriteEntryToAsync(stream, cancellationToken) - Extract entry asynchronously
  • reader.WriteAllToDirectoryAsync(path, cancellationToken: cancellationToken) - Extract all asynchronously
  • writer.WriteAsync(filename, stream, modTime, cancellationToken) - Write entry asynchronously
  • writer.WriteAllAsync(directory, pattern, searchOption, cancellationToken) - Write directory asynchronously
  • entry.OpenEntryStreamAsync(cancellationToken) - Open entry stream asynchronously

See Async Examples section below for usage patterns.

Stream Rules

When dealing with Streams, the rule should be that you don't close a stream you didn't create. This, in effect, should mean you should always put a Stream in a using block to dispose it.

However, the .NET Framework often has classes that will dispose streams by default to make things "easy" like the following:

using (var reader = new StreamReader(File.Open("foo")))
{
    ...
}

In this example, reader should get disposed. However, stream rules should say the the FileStream created by File.Open should remain open. However, the .NET Framework closes it for you by default unless you override the constructor. In general, you should be writing Stream code like this:

using (var fileStream = File.Open("foo"))
using (var reader = new StreamReader(fileStream))
{
    ...
}

To deal with the "correct" rules as well as the expectations of users, I've decided to always close wrapped streams as of 0.21.

To be explicit though, consider always using the overloads that use ReaderOptions or WriterOptions and explicitly set LeaveStreamOpen the way you want.

Default behavior in factory APIs:

  • File path / FileInfo overloads set LeaveStreamOpen = false.
  • Caller-provided Stream overloads set LeaveStreamOpen = true.

If using Compression Stream classes directly and you don't want the wrapped stream to be closed. Use the NonDisposingStream as a wrapper to prevent the stream being disposed. The change in 0.21 simplified a lot even though the usage is a bit more convoluted.

Samples

Also, look over the tests for more thorough examples

Create Zip Archive from multiple files

using(var archive = ZipArchive.CreateArchive())
{
    archive.AddEntry("file01.txt", "C:\\file01.txt");
    archive.AddEntry("file02.txt", "C:\\file02.txt");
    ...
    
    archive.SaveTo("C:\\temp.zip", CompressionType.Deflate);
}

Create Zip Archive from all files in a directory to a file

using (var archive = ZipArchive.CreateArchive())
{
    archive.AddAllFromDirectory("D:\\temp");
    archive.SaveTo("C:\\temp.zip", CompressionType.Deflate);
}

Create Zip Archive from all files in a directory and save in memory

var memoryStream = new MemoryStream();
using (var archive = ZipArchive.CreateArchive())
{
    archive.AddAllFromDirectory("D:\\temp");
    archive.SaveTo(memoryStream, new WriterOptions(CompressionType.Deflate)
                                {
                                    LeaveStreamOpen = true
                                });
}
//reset memoryStream to be usable now
memoryStream.Position = 0;

Extract all files from a rar file to a directory using RarArchive

Note: Extracting a solid rar or 7z file needs to be done in sequential order to get acceptable decompression speed. ExtractAllEntries is primarily intended for solid archives (like solid Rar) or 7Zip archives, where sequential extraction provides the best performance. For general/simple extraction with any supported archive type, use archive.WriteToDirectory() instead.

// Use ReaderOptions for open-time behavior and ExtractionOptions for extract-time behavior
using (var archive = RarArchive.OpenArchive("Test.rar", ReaderOptions.ForFilePath))
{
    // Simple extraction with RarArchive; this WriteToDirectory pattern works for all archive types
    archive.WriteToDirectory(
        @"D:\temp",
        new ExtractionOptions
        {
            ExtractFullPath = true,
            Overwrite = true,
            BufferSize = 131072,
        }
    );
}

Iterate over all files from a Rar file using RarArchive

using (var archive = RarArchive.OpenArchive("Test.rar"))
{
    foreach (var entry in archive.Entries.Where(entry => !entry.IsDirectory))
    {
        Console.WriteLine($"{entry.Key}: {entry.Size} bytes");
    }
}

Extract solid Rar or 7Zip archives with progress reporting

For optimal performance with solid Rar and 7Zip archives, extract entries sequentially. WriteToDirectory handles that internally for simple extraction. Use ExtractAllEntries when you need to manually iterate in sequential order.

using SharpCompress.Common;
using SharpCompress.Readers;

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

using (var archive = RarArchive.OpenArchive("archive.rar",
    ReaderOptions.ForFilePath
        .WithProgress(progress)))
{
    archive.WriteToDirectory(
        @"D:\output",
        new ExtractionOptions { ExtractFullPath = true, Overwrite = true }
    );
}

Manual sequential extraction:

using (var archive = RarArchive.OpenArchive("archive.rar",
    ReaderOptions.ForFilePath.WithProgress(progress)))
using (var reader = archive.ExtractAllEntries())
{
    while (reader.MoveToNextEntry())
    {
        if (!reader.Entry.IsDirectory)
        {
            reader.WriteEntryToDirectory(@"D:\output");
        }
    }
}

Use ReaderFactory to autodetect archive type and Open the entry stream

using (Stream stream = File.OpenRead("Tar.tar.bz2"))
using (var reader = ReaderFactory.OpenReader(stream))
{
    while (reader.MoveToNextEntry())
    {
        if (!reader.Entry.IsDirectory)
        {
            Console.WriteLine(reader.Entry.Key);
            reader.WriteEntryToDirectory(@"C:\temp");
        }
    }
}

Use ReaderFactory to autodetect archive type and Open the entry stream

using (Stream stream = File.OpenRead("Tar.tar.bz2"))
using (var reader = ReaderFactory.OpenReader(stream))
{
    while (reader.MoveToNextEntry())
    {
        if (!reader.Entry.IsDirectory)
        {
            using (var entryStream = reader.OpenEntryStream())
            {
                entryStream.CopyTo(...);
            }
        }
    }
}

Use WriterFactory to write all files from a directory in a streaming manner.

using (Stream stream = File.OpenWrite("C:\\temp.tgz"))
using (var writer = WriterFactory.OpenWriter(
    stream,
    ArchiveType.Tar,
    WriterOptions.ForTar(CompressionType.GZip).WithLeaveStreamOpen(true)))
{
    writer.WriteAll("D:\\temp", "*", SearchOption.AllDirectories);
}

Use ArchiveFactory to autodetect and open archives

if (ArchiveFactory.IsArchive("archive.zip", out var archiveType))
{
    Console.WriteLine($"Detected {archiveType}");
}

using (var archive = ArchiveFactory.OpenArchive("archive.zip"))
{
    archive.WriteToDirectory(@"D:\output");
}

Use ArchiveInformation to choose the right API

var archivePath = "archive.arc";
var info = ArchiveFactory.GetArchiveInformation(archivePath);
if (info is null)
{
    Console.WriteLine("Not a supported archive");
}
else if (info.SupportsRandomAccess)
{
    using var archive = ArchiveFactory.OpenArchive(archivePath);
    archive.WriteToDirectory(@"D:\output");
}
else
{
    using var reader = ReaderFactory.OpenReader(archivePath);
    reader.WriteAllToDirectory(@"D:\output");
}

SupportsRandomAccess is false for reader-only formats such as Ace, Arc, Arj, and standalone LZW. Use the Reader API for those formats.

Open multi-volume archives

var parts = ArchiveFactory.GetFileParts("archive.part1.rar")
    .Select(path => new FileInfo(path))
    .ToArray();

using (var archive = ArchiveFactory.OpenArchive(parts))
{
    archive.WriteToDirectory(@"D:\output");
}

Use ReaderOptions for self-extracting archives and detection hints

var sfxOptions = ReaderOptions.ForSelfExtractingArchive("password");
using (var archive = RarArchive.OpenArchive("setup.exe", sfxOptions))
{
    archive.WriteToDirectory(@"D:\output");
}

using (Stream stream = File.OpenRead("backup"))
using (var reader = ReaderFactory.OpenReader(
    stream,
    ReaderOptions.ForExternalStream.WithExtensionHint("tar.gz")))
{
    while (reader.MoveToNextEntry())
    {
        if (!reader.Entry.IsDirectory)
        {
            reader.WriteEntryToDirectory(@"D:\output");
        }
    }
}

Write ZIP entries with per-entry options

using Stream archiveStream = File.Create("output.zip");
using var writer = new ZipWriter(
    archiveStream,
    new ZipWriterOptions(CompressionType.Deflate)
    {
        ArchiveComment = "Archive comment",
        UseZip64 = true,
    });

using Stream source = File.OpenRead("input.txt");
writer.Write("entry.txt", source, new ZipWriterEntryOptions
{
    CompressionType = CompressionType.ZStandard,
    CompressionLevel = 3,
    EntryComment = "Entry comment",
    ModificationDateTime = DateTime.UtcNow,
    EnableZip64 = true,
});

Write a 7z archive

using Stream stream = File.Create("output.7z");
using var writer = WriterFactory.OpenWriter(
    stream,
    ArchiveType.SevenZip,
    new SevenZipWriterOptions(CompressionType.LZMA2)
    {
        CompressHeader = true,
    });

using Stream source = File.OpenRead("input.txt");
writer.Write("input.txt", source, DateTime.UtcNow);

Extract zip which has non-utf8 encoded filename(cp932)

var encoding = Encoding.GetEncoding(932);
var opts = new ReaderOptions()
    .WithArchiveEncoding(new ArchiveEncoding
    {
        CustomDecoder = (data, x, y) => encoding.GetString(data)
    });

using var archive = ZipArchive.OpenArchive("test.zip", opts);
foreach(var entry in archive.Entries)
{
    Console.WriteLine($"{entry.Key}");
}

Custom Compression Providers

By default ReaderOptions and WriterOptions already include CompressionProviderRegistry.Default via their Providers property, so you can read and write without touching the registry yet still get SharpCompress’s built-in implementations.

The configured registry is used consistently across Reader APIs, Writer APIs, Archive APIs, and async entry-stream extraction, including compressed TAR wrappers and ZIP async decompression.

To replace specific algorithms (for example to use System.IO.Compression for GZip or Deflate), create a modified registry and pass it through the same options:

var customRegistry = CompressionProviderRegistry.Default
    .With(new SystemGZipCompressionProvider())
    .With(new SystemDeflateCompressionProvider());

var readerOptions = ReaderOptions.ForFilePath
    .WithProviders(customRegistry);
using var reader = ReaderFactory.OpenReader(stream, readerOptions);

var writerOptions = new WriterOptions(CompressionType.GZip)
    .WithProviders(customRegistry);
using var writer = WriterFactory.OpenWriter(outputStream, ArchiveType.GZip, writerOptions);

The registry is immutable. With(provider) returns a new registry and replaces any existing provider for that provider's CompressionType. You can inspect or use providers directly with GetProvider, CreateCompressStream, CreateDecompressStream, and their async/context overloads, but most application code should flow the registry through ReaderOptions or WriterOptions so archive readers and writers can supply the right CompressionContext.

To implement a custom provider, implement ICompressionProvider directly or derive from CompressionProviderBase for default async methods. Derive from DecompressionOnlyProviderBase for read-only codecs. Providers can use CompressionContext for stream size, seekability, reader options, compression properties, and format-specific metadata.

The registry also exposes GetCompressingProvider (now returning ICompressionProviderHooks) when a compression format needs pre- or post-stream data (e.g., LZMA/PPMd). Implementations that need extra headers can supply those bytes through the ICompressionProviderHooks members while the rest of the API still works through the Providers property.

Async Examples

Async Reader Examples

Extract single entry asynchronously:

using Stream stream = File.OpenRead("archive.zip");
await using var reader = await ReaderFactory.OpenAsyncReader(stream, cancellationToken: cancellationToken);
while (await reader.MoveToNextEntryAsync(cancellationToken))
{
    if (!reader.Entry.IsDirectory)
    {
        using var outputStream = File.Create("output.bin");
        await reader.WriteEntryToAsync(outputStream, cancellationToken);
    }
}

Extract all entries asynchronously:

using Stream stream = File.OpenRead("archive.tar.gz");
await using var reader = await ReaderFactory.OpenAsyncReader(stream, cancellationToken: cancellationToken);
await reader.WriteAllToDirectoryAsync(
    @"D:\temp",
    cancellationToken: cancellationToken
);

Open and process entry stream asynchronously:

await using var archive = await ZipArchive.OpenAsyncArchive("archive.zip", cancellationToken: cancellationToken);
await foreach (var entry in archive.EntriesAsync)
{
    if (!entry.IsDirectory)
    {
        using var entryStream = await entry.OpenEntryStreamAsync(cancellationToken);
        // Process the decompressed stream asynchronously
        await ProcessStreamAsync(entryStream, cancellationToken);
    }
}

Async Writer Examples

Write single file asynchronously:

using Stream archiveStream = File.OpenWrite("output.zip");
await using var writer = await WriterFactory.OpenAsyncWriter(archiveStream, ArchiveType.Zip, new WriterOptions(CompressionType.Deflate), cancellationToken);
using Stream fileStream = File.OpenRead("input.txt");
await writer.WriteAsync("entry.txt", fileStream, DateTime.Now, cancellationToken);

Write entire directory asynchronously:

using Stream stream = File.OpenWrite("backup.tar.gz");
await using var writer = await WriterFactory.OpenAsyncWriter(stream, ArchiveType.Tar, new WriterOptions(CompressionType.GZip), cancellationToken);
await writer.WriteAllAsync(
    @"D:\files",
    "*",
    SearchOption.AllDirectories,
    cancellationToken
);

Write with progress tracking and cancellation:

var cts = new CancellationTokenSource();

// Set timeout or cancel from UI
cts.CancelAfter(TimeSpan.FromMinutes(5));

using Stream stream = File.OpenWrite("archive.zip");
await using var writer = await WriterFactory.OpenAsyncWriter(stream, ArchiveType.Zip, new WriterOptions(CompressionType.Deflate), cts.Token);
try
{
    await writer.WriteAllAsync(@"D:\data", "*", SearchOption.AllDirectories, cts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("Operation was cancelled");
}

Archive Async Examples

Extract from archive asynchronously:

await using var archive = await ZipArchive.OpenAsyncArchive("archive.zip", cancellationToken: cancellationToken);
// Simple async extraction - works for all archive types
await archive.WriteToDirectoryAsync(
    @"C:\output",
    cancellationToken: cancellationToken
);

Benefits of Async Operations:

  • Non-blocking I/O for better application responsiveness
  • Improved scalability for server applications
  • Support for cancellation via CancellationToken
  • Better resource utilization in async/await contexts
  • Compatible with modern .NET async patterns
⚡