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, IDisposableExample
// 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
| Name | Description |
|---|---|
| CompressionFormat | Gets the compression around the archive (the compression of a .tar.gz, .tar.xz, ...). |
| Entry | Gets the current entry, or null before the first call to ArchiveReader.MoveToNextEntry and after the last entry. |
| Format | Gets the format of the archive. |
CompressionFormat
ArchiveReader.csGets the compression around the archive (the compression of a .tar.gz, .tar.xz, ...).
public virtual CompressionFormat CompressionFormat { get; }Property value
Entry
ArchiveReader.csGets the current entry, or null before the first call to ArchiveReader.MoveToNextEntry and after the last entry.
public ArchiveEntry? Entry { get; }Property value
Format
Methods
| Name | Description |
|---|---|
| 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.csCreates 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
streamStream- The stream of the archive, positioned at its start.
optionsArchiveReaderOptions?- The options to read the archive.
leaveOpenbooltrueto 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.csCreates 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
pathstring- The path of the archive.
optionsArchiveReaderOptions?- The options to read the archive.
Returns
ArchiveReader The reader, before the first entry: call ArchiveReader.MoveToNextEntry.
Dispose overloads
Dispose()
ArchiveReader.csReleases the resources of the reader.
public void Dispose()Dispose(bool)
ArchiveReader.csReleases the resources of the reader.
Parameters
disposingbooltruewhen called fromArchiveReader.Dispose.
DisposeAsync()
ArchiveReader.csDisposeAsyncCore()
ArchiveReader.csExtractToDirectory(string, bool)
ArchiveReader.csExtracts the remaining entries of the archive under a directory. An entry whose path leaves the directory is rejected with an IOException.
Parameters
destinationDirectoryNamestring- The directory to extract to. It is created when it does not exist.
overwriteFilesbooltrueto replace the existing files;falseto throw anIOExceptionwhen a file exists.
ExtractToDirectoryAsync(string, bool, CancellationToken)
ArchiveReader.csExtracts 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
destinationDirectoryNamestring- The directory to extract to. It is created when it does not exist.
overwriteFilesbooltrueto replace the existing files;falseto throw anIOExceptionwhen a file exists.cancellationTokenCancellationToken- The token to monitor for cancellation requests.
Returns
Task A task that completes when every entry is extracted.
MoveToNextEntry()
ArchiveReader.csMoves 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.csMoves 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
cancellationTokenCancellationToken- 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.csOpens 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.csExtracts the current entry under a directory, at the path of the entry in the archive.
Parameters
destinationDirectoryNamestring- The directory to extract to. It is created when it does not exist.
overwriteFilesbooltrueto replace an existing file;falseto throw anIOExceptionwhen the file exists.
Exceptions
InvalidOperationException- There is no current entry.
WriteEntryToDirectoryAsync(string, bool, CancellationToken)
ArchiveReader.csExtracts 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
destinationDirectoryNamestring- The directory to extract to. It is created when it does not exist.
overwriteFilesbooltrueto replace an existing file;falseto throw anIOExceptionwhen the file exists.cancellationTokenCancellationToken- 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.