ZCS.XZ 5.8.3.2

ZCS.XZ

A high-performance .NET library for XZ (LZMA2) compression and decompression, built on top of the native liblzma library via P/Invoke.

Features

• Streaming API — standard System.IO.Stream-based compress/decompress, compatible with CopyTo, ReadAsync, pipelines, etc.
• Zero-copy writes — the compressor pins the caller's buffer directly via unsafe fixed, eliminating intermediate copies on the write path.
• Multi-threaded compression — optional parallel encoding via lzma_stream_encoder_mt with configurable thread count.
• Auto-detection — the decompressor automatically handles both .xz and legacy .lzma file formats.
• Concatenated streams — supports concatenated .xz members (e.g., files produced by xz --keep with multiple appends).
• Cross-platform — ships native liblzma binaries for Windows, Linux, and macOS on x64 and ARM64.
• Multi-targeting — supports .NET 8, .NET 9, and .NET 10.
• 100 % code coverage — comprehensive test suite with full line, branch, and method coverage.

Installation

Install via the NuGet Package Manager:

dotnet add package ZCS.XZ

Or via the Package Manager Console in Visual Studio:

Install-Package ZCS.XZ

Quick Start

Compress data

using ZCS.XZ;

byte[] data = GetData();

using var output = File.Create("data.xz");
using (var xz = new XZCompressStream(output))
{
    xz.Write(data);
}
// The .xz stream is finalized when the XZCompressStream is disposed.

Decompress data

using ZCS.XZ;

using var input = File.OpenRead("data.xz");
using var xz = new XZDecompressStream(input);
using var output = new MemoryStream();
xz.CopyTo(output);

byte[] decompressed = output.ToArray();

Compress a file with options

using ZCS.XZ;

var options = new XZCompressOptions
{
    Level = XZCompressionLevel.Maximum, // Maximum compression
    Extreme = true,                     // Marginally better ratio, slower
    Threads = 0,                        // Auto-detect thread count
    BufferSize = 131072,                // 128 KB internal buffer
};

using var input = File.OpenRead("largefile.bin");
using var output = File.Create("largefile.bin.xz");
using (var xz = new XZCompressStream(output, options))
{
    input.CopyTo(xz);
}

Decompress with a memory limit

using ZCS.XZ;

ulong maxMemory = 256 * 1024 * 1024; // 256 MB

using var input = File.OpenRead("data.xz");
using var xz = new XZDecompressStream(input, memoryLimit: maxMemory, leaveOpen: false);
using var output = new MemoryStream();
xz.CopyTo(output);

API Reference

XZCompressStream

A write-only stream that compresses data and writes the .xz output to an underlying stream.

Important: The stream must be disposed to finalize the .xz output (writes the stream footer). Failing to dispose produces a corrupt file.

XZDecompressStream

A read-only stream that decompresses .xz (or legacy .lzma) data from an underlying stream.

XZCompressOptions

XZCompressionLevel

XZException

Thrown when liblzma returns an error. The LzmaReturnCode property contains the raw integer code (e.g., LZMA_DATA_ERROR, LZMA_MEM_ERROR).

LzmaCheck

Enum for integrity check types: None, Crc32, Crc64, Sha256.

Supported Platforms

The native liblzma binaries are bundled under the runtimes/{rid}/native/ directory and resolved automatically at runtime.

Building from Source

Prerequisites

• .NET 10 SDK or later
• Native liblzma binaries placed under ZCS.XZ/runtimes/{rid}/native/

Build

dotnet build

Run Tests

dotnet test

Run Tests with Code Coverage

dotnet test --collect:"XPlat Code Coverage"

To generate an HTML coverage report, install ReportGenerator:

dotnet tool install -g dotnet-reportgenerator-globaltool
reportgenerator -reports:**/coverage.cobertura.xml -targetdir:CoverageReport -reporttypes:Html

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a branch for your feature or bug fix: git checkout -b feature/my-feature.
3. Write tests — aim to maintain 100 % code coverage.
4. Build and test: dotnet build && dotnet test.
5. Submit a pull request with a clear description of your changes.

Please open an issue first if you plan a large change, so we can discuss the approach.

License

This project is licensed under the MIT License.

Acknowledgements

• XZ Utils / liblzma — the underlying native compression library.
• Lasse Collin and Jia Tan — liblzma authors.
• Joveler.Compression.XZ — another excellent .NET XZ binding that served as a reference and inspiration for this project.