ArchiveReader Class

Reads the entries of an archive one after the other, from a stream that does not need to be seekable (a network response, a pipe). The content of the current entry can be read until the reader moves to the next entry; the content that is not read is skipped.

public abstract class ArchiveReader : IAsyncDisposable, IDisposable

Example

// The stream does not need to be seekable: a network response, a pipe, ...
using var input = File.OpenRead(path);
using var archiveReader = ArchiveReader.Create(input);
Assert.Equal(ArchiveFormat.Tar, archiveReader.Format);
Assert.Equal(CompressionFormat.GZip, archiveReader.CompressionFormat);
while (archiveReader.MoveToNextEntry())
{
    var entry = archiveReader.Entry!;
    if (entry.FullName.EndsWith(".txt", StringComparison.Ordinal))
    {
        // The content can be read until the reader moves to the next entry
        using var content = archiveReader.OpenEntryStream();
        using var copy = new MemoryStream();
        content.CopyTo(copy);
        Assert.Equal(entry.Length, copy.Length);
    }
}
Implements

Properties

NameDescription
CompressionFormatGets the compression around the archive (the compression of a .tar.gz, .tar.xz, ...).
EntryGets the current entry, or null before the first call to ArchiveReader.MoveToNextEntry and after the last entry.
FormatGets the format of the archive.

CompressionFormat

ArchiveReader.cs

Gets the compression around the archive (the compression of a .tar.gz, .tar.xz, ...).

public virtual CompressionFormat CompressionFormat { get; }

Property value

CompressionFormat

Gets the current entry, or null before the first call to ArchiveReader.MoveToNextEntry and after the last entry.

public ArchiveEntry? Entry { get; }

Property value

ArchiveEntry?

Format

Gets the format of the archive.

public abstract ArchiveFormat Format { get; }

Property value

ArchiveFormat

Methods

NameDescription
Create(Stream, ArchiveReaderOptions?, bool)Creates a forward-only reader of an archive, whose format (zip, RAR, tar, and tar compressed with gzip, bzip2, XZ, LZMA, lzip, Zstandard or Unix compress) is detected from its first bytes. The stream does not need to be seekable.
Create(string, ArchiveReaderOptions?)Creates a forward-only reader of an archive file, whose format is detected from its first bytes.
Dispose()Releases the resources of the reader.
Dispose(bool)Releases the resources of the reader.
DisposeAsync()Releases the resources of the reader.
DisposeAsyncCore()Releases the resources of the reader asynchronously.
ExtractToDirectory(string, bool)Extracts the remaining entries of the archive under a directory. An entry whose path leaves the directory is rejected with an IOException.
ExtractToDirectoryAsync(string, bool, CancellationToken)Extracts the remaining entries of the archive under a directory. An entry whose path leaves the directory is rejected with an IOException.
MoveToNextEntry()Moves to the next entry of the archive, skipping the content of the current entry that is not read.
MoveToNextEntryAsync(CancellationToken)Moves to the next entry of the archive, skipping the content of the current entry that is not read.
OpenEntryStream()Opens the content of the current entry. The stream is valid until the reader moves to the next entry.
WriteEntryToDirectory(string, bool)Extracts the current entry under a directory, at the path of the entry in the archive.
WriteEntryToDirectoryAsync(string, bool, CancellationToken)Extracts the current entry under a directory, at the path of the entry in the archive.

Create overloads

Create(Stream, ArchiveReaderOptions?, bool)

ArchiveReader.Create.cs

Creates a forward-only reader of an archive, whose format (zip, RAR, tar, and tar compressed with gzip, bzip2, XZ, LZMA, lzip, Zstandard or Unix compress) is detected from its first bytes. The stream does not need to be seekable.

public static ArchiveReader Create(Stream stream, ArchiveReaderOptions? options = null, bool leaveOpen = false)
Parameters
stream Stream
The stream of the archive, positioned at its start.
options ArchiveReaderOptions?
The options to read the archive.
leaveOpen bool
true to leave the stream open when the reader is disposed.
Returns

ArchiveReader The reader, before the first entry: call ArchiveReader.MoveToNextEntry.

Exceptions
InvalidDataException
The data are not an archive of a supported format.
NotSupportedException
The archive is a 7z archive, which cannot be read forward only: use ArchiveFile.Open.

Create(string, ArchiveReaderOptions?)

ArchiveReader.Create.cs

Creates a forward-only reader of an archive file, whose format is detected from its first bytes.

public static ArchiveReader Create(string path, ArchiveReaderOptions? options = null)
Parameters
path string
The path of the archive.
options ArchiveReaderOptions?
The options to read the archive.
Returns

ArchiveReader The reader, before the first entry: call ArchiveReader.MoveToNextEntry.

Dispose overloads

Releases the resources of the reader.

public void Dispose()

Dispose(bool)

ArchiveReader.cs

Releases the resources of the reader.

protected virtual void Dispose(bool disposing)
Parameters
disposing bool
true when called from ArchiveReader.Dispose.

DisposeAsync()

ArchiveReader.cs

Releases the resources of the reader.

net10.0

public ValueTask DisposeAsync()

net11.0

public ValueTask DisposeAsync()

Returns

ValueTask A task that completes when the reader is disposed.

DisposeAsyncCore()

ArchiveReader.cs

Releases the resources of the reader asynchronously.

protected virtual ValueTask DisposeAsyncCore()

Returns

ValueTask A task that completes when the resources are released.

ExtractToDirectory(string, bool)

ArchiveReader.cs

Extracts the remaining entries of the archive under a directory. An entry whose path leaves the directory is rejected with an IOException.

public void ExtractToDirectory(string destinationDirectoryName, bool overwriteFiles = false)

Parameters

destinationDirectoryName string
The directory to extract to. It is created when it does not exist.
overwriteFiles bool
true to replace the existing files; false to throw an IOException when a file exists.

ExtractToDirectoryAsync(string, bool, CancellationToken)

ArchiveReader.cs

Extracts the remaining entries of the archive under a directory. An entry whose path leaves the directory is rejected with an IOException.

net10.0

public Task ExtractToDirectoryAsync(string destinationDirectoryName, bool overwriteFiles = false, CancellationToken cancellationToken = default)

net11.0

public Task ExtractToDirectoryAsync(string destinationDirectoryName, bool overwriteFiles = false, CancellationToken cancellationToken = default)

Parameters

destinationDirectoryName string
The directory to extract to. It is created when it does not exist.
overwriteFiles bool
true to replace the existing files; false to throw an IOException when a file exists.
cancellationToken CancellationToken
The token to monitor for cancellation requests.

Returns

Task A task that completes when every entry is extracted.

MoveToNextEntry()

ArchiveReader.cs

Moves to the next entry of the archive, skipping the content of the current entry that is not read.

public bool MoveToNextEntry()

Returns

bool true when there is a next entry; false at the end of the archive.

Exceptions

InvalidDataException
The archive is corrupted.

MoveToNextEntryAsync(CancellationToken)

ArchiveReader.cs

Moves to the next entry of the archive, skipping the content of the current entry that is not read.

net10.0

public ValueTask<bool> MoveToNextEntryAsync(CancellationToken cancellationToken = default)

net11.0

public ValueTask<bool> MoveToNextEntryAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken
The token to monitor for cancellation requests.

Returns

ValueTask<bool> true when there is a next entry; false at the end of the archive.

Exceptions

InvalidDataException
The archive is corrupted.

OpenEntryStream()

ArchiveReader.cs

Opens the content of the current entry. The stream is valid until the reader moves to the next entry.

public Stream OpenEntryStream()

Returns

Stream A read-only stream of the content of the current entry.

Exceptions

InvalidOperationException
There is no current entry.

WriteEntryToDirectory(string, bool)

ArchiveReader.cs

Extracts the current entry under a directory, at the path of the entry in the archive.

public void WriteEntryToDirectory(string destinationDirectoryName, bool overwriteFiles = false)

Parameters

destinationDirectoryName string
The directory to extract to. It is created when it does not exist.
overwriteFiles bool
true to replace an existing file; false to throw an IOException when the file exists.

Exceptions

InvalidOperationException
There is no current entry.

WriteEntryToDirectoryAsync(string, bool, CancellationToken)

ArchiveReader.cs

Extracts the current entry under a directory, at the path of the entry in the archive.

net10.0

public Task WriteEntryToDirectoryAsync(string destinationDirectoryName, bool overwriteFiles = false, CancellationToken cancellationToken = default)

net11.0

public Task WriteEntryToDirectoryAsync(string destinationDirectoryName, bool overwriteFiles = false, CancellationToken cancellationToken = default)

Parameters

destinationDirectoryName string
The directory to extract to. It is created when it does not exist.
overwriteFiles bool
true to replace an existing file; false to throw an IOException when the file exists.
cancellationToken CancellationToken
The token to monitor for cancellation requests.

Returns

Task A task that completes when the entry is extracted.

Exceptions

InvalidOperationException
There is no current entry.