Class Archive
Namespace: Aspose.Zip
Assembly: Aspose.Zip.dll (25.2.0)
This class represents zip archive file. Use it to compose, extract, or update zip archives.
public class Archive : IArchive, IDisposableInheritance
Implements
Inherited Members
object.GetType(), object.MemberwiseClone(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()
Constructors
Archive(ArchiveEntrySettings)
Initializes a new instance of the Aspose.Zip.Archive class with optional settings for its entries.
public Archive(ArchiveEntrySettings newEntrySettings = null)Parameters
newEntrySettings ArchiveEntrySettings
Compression and encryption settings used for newly added Aspose.Zip.ArchiveEntry items. If not specified, the most common Deflate compression without encryption would be used.
Examples
The following example shows how to compress a single file with default settings.
using (FileStream zipFile = File.Open("archive.zip", FileMode.Create))
{
using (var archive = new Archive())
{
archive.CreateEntry("data.bin", "file.dat");
archive.Save(zipFile);
}
}Archive(Stream, ArchiveLoadOptions, ArchiveEntrySettings)
Initializes a new instance of the Aspose.Zip.Archive class and composes an entry list can be extracted from the archive.
public Archive(Stream sourceStream, ArchiveLoadOptions loadOptions = null, ArchiveEntrySettings newEntrySettings = null)Parameters
sourceStream Stream
The source of the archive.
loadOptions ArchiveLoadOptions
Options to load existing archive with.
newEntrySettings ArchiveEntrySettings
Compression and encryption settings used for newly added Aspose.Zip.ArchiveEntry items. If not specified, the most common Deflate compression without encryption would be used.
Examples
The following example extracts an encrypted archive, then decompresses first entry to a MemoryStream.
var fs = File.OpenRead("encrypted.zip");
var extracted = new MemoryStream();
using (Archive archive = new Archive(fs, new ArchiveLoadOptions() { DecryptionPassword = "p@s$" }))
{
using (var decompressed = archive.Entries[0].Open())
{
byte[] b = new byte[8192];
int bytesRead;
while (0 < (bytesRead = decompressed.Read(b, 0, b.Length)))
extracted.Write(b, 0, bytesRead);
}
}Remarks
This constructor does not decompress any entry. See Aspose.Zip.ArchiveEntry.Open(System.String) method for decompressing.
Exceptions
sourceStream is not seekable.
Encryption header for AES contradicts WinZip compression method.
Archive(string, ArchiveLoadOptions, ArchiveEntrySettings)
Initializes a new instance of the Aspose.Zip.Archive class and composes entry list can be extracted from the archive.
public Archive(string path, ArchiveLoadOptions loadOptions = null, ArchiveEntrySettings newEntrySettings = null)Parameters
path string
The fully qualified or the relative path to the archive file.
loadOptions ArchiveLoadOptions
Options to load existing archive with.
newEntrySettings ArchiveEntrySettings
Compression and encryption settings used for newly added Aspose.Zip.ArchiveEntry items. If not specified, the most common Deflate compression without encryption would be used.
Examples
The following example extracts an encrypted archive, then decompresses first entry to a MemoryStream.
var extracted = new MemoryStream();
using (Archive archive = new Archive("encrypted.zip", new ArchiveLoadOptions() { DecryptionPassword = "p@s$" }))
{
using (var decompressed = archive.Entries[0].Open())
{
byte[] b = new byte[8192];
int bytesRead;
while (0 < (bytesRead = decompressed.Read(b, 0, b.Length)))
extracted.Write(b, 0, bytesRead);
}
}Remarks
This constructor does not decompress any entry. See Aspose.Zip.ArchiveEntry.Open(System.String) method for decompressing.
Exceptions
path is null.
The caller does not have the required permission to access.
The path is empty, contains only white spaces, or contains invalid characters.
Access to file path is denied.
The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
File at path contains a colon (:) in the middle of the string.
The file is not found.
The specified path is invalid, such as being on an unmapped drive.
The file is already open.
File is corrupted.
Archive(string, string[], ArchiveLoadOptions)
Initializes a new instance of the Aspose.Zip.Archive class from multi-volume zip archive and composes an entry list can be extracted from the archive.
public Archive(string mainSegment, string[] segmentsInOrder, ArchiveLoadOptions loadOptions = null)Parameters
mainSegment string
Path to the last segment of multi-volume archive with the central directory.
Usually this segment has *.zip extension and smaller than others.
segmentsInOrder string[]
Paths to each segment but the last of multi-volume zip archive respecting order.
Usually they named filename.z01, filename.z02, …, filename.z(n-1).
loadOptions ArchiveLoadOptions
Options to load existing archive with.
Examples
This sample extract to a directory an archive of three segments.
using (Archive a = new Archive("archive.zip", new string[] { "archive.z01", "archive.z02" }))
{
a.ExtractToDirectory("destination");
}Exceptions
Cannot load ZIP headers because provided files are corrupted.
Properties
Entries
Gets entries of Aspose.Zip.ArchiveEntry type constituting the archive.
public ReadOnlyCollection<archiveentry> Entries { get; }Property Value
ReadOnlyCollection<ArchiveEntry>
NewEntrySettings
Compression and encryption settings used for newly added Aspose.Zip.ArchiveEntry items.
public ArchiveEntrySettings NewEntrySettings { get; }Property Value
Methods
CreateEntries(DirectoryInfo, bool)
Adds to the archive all files and directories recursively in the directory given.
public Archive CreateEntries(DirectoryInfo directory, bool includeRootDirectory = true)Parameters
directory DirectoryInfo
Directory to compress.
includeRootDirectory bool
Indicates whether to include the root directory itself or not.
Returns
The archive with entries composed.
Examples
using (Archive archive = new Archive())
{
DirectoryInfo folder = new DirectoryInfo("C:\folder");
archive.CreateEntries(folder);
archive.Save("folder.zip");
}Exceptions
The path to directory is invalid, such as being on an unmapped drive.
The caller does not have the required permission to access directory.
CreateEntries(string, bool)
Adds to the archive all files and directories recursively in the directory given.
public Archive CreateEntries(string sourceDirectory, bool includeRootDirectory = true)Parameters
sourceDirectory string
Directory to compress.
includeRootDirectory bool
Indicates whether to include the root directory itself or not.
Returns
The archive with entries composed.
Examples
using (Archive archive = new Archive())
{
archive.CreateEntries("C:\folder");
archive.Save("folder.zip");
}CreateEntry(string, string, bool, ArchiveEntrySettings)
Create a single entry within the archive.
public ArchiveEntry CreateEntry(string name, string path, bool openImmediately = false, ArchiveEntrySettings newEntrySettings = null)Parameters
name string
The name of the entry.
path string
The fully qualified name of the new file, or the relative file name to be compressed.
openImmediately bool
True, if open the file immediately, otherwise open the file on archive saving.
newEntrySettings ArchiveEntrySettings
Compression and encryption settings used for added Aspose.Zip.ArchiveEntry item.
Returns
Zip entry instance.
Examples
using (FileStream zipFile = File.Open("archive.zip", FileMode.Create))
{
using (var archive = new Archive())
{
archive.CreateEntry("data.bin", "file.dat");
archive.Save(zipFile);
}
}Remarks
The entry name is solely set within name parameter. The file name provided in path parameter does not affect the entry name.
If the file is opened immediately with openImmediately parameter it becomes blocked until archive is saved.
Exceptions
path is null.
The caller does not have the required permission to access.
The path is empty, contains only white spaces, or contains invalid characters.
Access to file path is denied.
The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
File at path contains a colon (:) in the middle of the string.
CreateEntry(string, Stream, ArchiveEntrySettings)
Create a single entry within the archive.
public ArchiveEntry CreateEntry(string name, Stream source, ArchiveEntrySettings newEntrySettings = null)Parameters
name string
The name of the entry.
source Stream
The input stream for the entry.
newEntrySettings ArchiveEntrySettings
Compression and encryption settings used for added Aspose.Zip.ArchiveEntry item.
Returns
Zip entry instance.
Examples
using (var archive = new Archive(new ArchiveEntrySettings(null, new AesEcryptionSettings("p@s$", EncryptionMethod.AES256))))
{
archive.CreateEntry("data.bin", new MemoryStream(new byte[] {0x00, 0xFF} ));
archive.Save("archive.zip");
}CreateEntry(string, FileInfo, bool, ArchiveEntrySettings)
Create a single entry within the archive.
public ArchiveEntry CreateEntry(string name, FileInfo fileInfo, bool openImmediately = false, ArchiveEntrySettings newEntrySettings = null)Parameters
name string
The name of the entry.
fileInfo FileInfo
The metadata of file to be compressed.
openImmediately bool
True, if open the file immediately, otherwise open the file on archive saving.
newEntrySettings ArchiveEntrySettings
Compression and encryption settings used for added Aspose.Zip.ArchiveEntry item.
Returns
Zip entry instance.
Examples
Compose archive with entries encrypted with different encryption methods and passwords each.
using (FileStream zipFile = File.Open("archive.zip", FileMode.Create))
{
FileInfo fi1 = new FileInfo("data1.bin");
FileInfo fi2 = new FileInfo("data2.bin");
FileInfo fi3 = new FileInfo("data3.bin");
using (var archive = new Archive())
{
archive.CreateEntry("entry1.bin", fi1, false, new ArchiveEntrySettings(new DeflateCompressionSettings(), new TraditionalEncryptionSettings("pass1")));
archive.CreateEntry("entry2.bin", fi2, false, new ArchiveEntrySettings(new DeflateCompressionSettings(), new AesEcryptionSettings("pass2", EncryptionMethod.AES128)));
archive.CreateEntry("entry3.bin", fi3, false, new ArchiveEntrySettings(new DeflateCompressionSettings(), new AesEcryptionSettings("pass3", EncryptionMethod.AES256)));
archive.Save(zipFile);
}
}Remarks
The entry name is solely set within name parameter. The file name provided in fileInfo parameter does not affect the entry name.
If the file is opened immediately with openImmediately parameter it becomes blocked until archive is saved.
Exceptions
fileInfo is read-only or is a directory.
The specified path is invalid, such as being on an unmapped drive.
The file is already open.
CreateEntry(string, Stream, ArchiveEntrySettings, FileSystemInfo)
Create a single entry within the archive.
public ArchiveEntry CreateEntry(string name, Stream source, ArchiveEntrySettings newEntrySettings, FileSystemInfo fileInfo)Parameters
name string
The name of the entry.
source Stream
The input stream for the entry.
newEntrySettings ArchiveEntrySettings
Compression and encryption settings used for added Aspose.Zip.ArchiveEntry item.
fileInfo FileSystemInfo
The metadata of file or folder to be compressed.
Returns
Zip entry instance.
Examples
Compose archive with encrypted entry.
using (FileStream zipFile = File.Open("archive.zip", FileMode.Create))
{
using (var archive = new Archive())
{
archive.CreateEntry("entry1.bin", new MemoryStream(new byte[] {0x00, 0xFF} ), new ArchiveEntrySettings(new DeflateCompressionSettings(), new TraditionalEncryptionSettings("pass1")), new FileInfo("data1.bin"));
archive.Save(zipFile);
}
}Remarks
The entry name is solely set within name parameter. The file name provided in fileInfo parameter does not affect the entry name.
fileInfo can refer to System.IO.DirectoryInfo if the entry is directory.
Exceptions
Both source and fileInfo are null or source is null and fileInfo stands for directory.
CreateEntry(string, Func<stream>, ArchiveEntrySettings)
Create a single entry within the archive.
public ArchiveEntry CreateEntry(string name, Func<stream> streamProvider, ArchiveEntrySettings newEntrySettings = null)Parameters
name string
The name of the entry.
streamProvider Func<Stream>
The method providing input stream for the entry.
newEntrySettings ArchiveEntrySettings
Compression and encryption settings used for added Aspose.Zip.ArchiveEntry item.
Returns
Zip entry instance.
Examples
Compose archive with encrypted entry.
System.Func<Stream> provider = delegate(){ return new MemoryStream(new byte[]{0xFF, 0x00}); };
using (FileStream zipFile = File.Open("archive.zip", FileMode.Create))
{
using (var archive = new Archive())
{
archive.CreateEntry("entry1.bin", provider, new ArchiveEntrySettings(new DeflateCompressionSettings(), new TraditionalEncryptionSettings("pass1"))));
archive.Save(zipFile);
}
}Remarks
This method is for .NET Framework 4.0 and above and for .NET Standard 2.0 version.
DeleteEntry(ArchiveEntry)
Removes the first occurrence of the specific entry from the entry list.
public Archive DeleteEntry(ArchiveEntry entry)Parameters
entry ArchiveEntry
The entry to remove from the entries list.
Returns
The archive with the entry deleted.
Examples
Here is how you can remove all entries except the last one:
using (var archive = new Archive("archive.zip"))
{
while (archive.Entries.Count > 1)
archive.DeleteEntry(archive.Entries[0]);
archive.Save("last_entry.zip");
}Exceptions
The archive is disposed.
DeleteEntry(int)
Removes the entry from the entry list by index.
public Archive DeleteEntry(int entryIndex)Parameters
entryIndex int
The zero-based index of the entry to remove.
Returns
The archive with the entry deleted.
Examples
using (var archive = new TarArchive("two_files.zip"))
{
archive.DeleteEntry(0);
archive.Save("single_file.zip");
}Exceptions
Archive is disposed.
entryIndex is less than 0.-or- entryIndex is equal to or greater than Entries count.
Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()Dispose(bool)
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
protected virtual void Dispose(bool disposing)Parameters
disposing bool
Whether managed resources should be disposed.
ExtractToDirectory(string)
Extracts all the files in the archive to the directory provided.
public void ExtractToDirectory(string destinationDirectory)Parameters
destinationDirectory string
The path to the directory to place the extracted files in.
Examples
using (var archive = new Archive("archive.zip"))
{
archive.ExtractToDirectory("C:\extracted");
}Remarks
If the directory does not exist, it will be created.
Exceptions
destinationDirectory is null.
The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters and file names must be less than 260 characters.
The caller does not have the required permission to access the existing directory.
If directory does not exist, path contains a colon character (:) that is not part of a drive label (“C:").
destinationDirectory is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the System.IO.Path.GetInvalidPathChars method.
-or- path is prefixed with, or contains, only a colon character (:).
The directory specified by path is a file. -or- The network name is not known.
Wrong password has been supplied. - or - Archive is corrupted.
Save(Stream, ArchiveSaveOptions)
Saves archive to the stream provided.
public void Save(Stream outputStream, ArchiveSaveOptions saveOptions = null)Parameters
outputStream Stream
Destination stream.
saveOptions ArchiveSaveOptions
Options for archive saving.
Examples
using (FileStream zipFile = File.Open("archive.zip", FileMode.Create))
{
using (var archive = new Archive())
{
archive.CreateEntry("entry.bin", "data.bin");
archive.Save(zipFile);
}
}Remarks
outputStream must be writable.
Exceptions
outputStream is not writable.
The archive is disposed.
Save(string, ArchiveSaveOptions)
Saves archive to the destination file provided.
public void Save(string destinationFileName, ArchiveSaveOptions saveOptions = null)Parameters
destinationFileName string
The path of the archive to be created. If the specified file name points to an existing file, it will be overwritten.
saveOptions ArchiveSaveOptions
Options for archive saving.
Examples
using (var archive = new Archive())
{
archive.CreateEntry("entry.bin", "data.bin");
archive.Save("archive.zip", new ArchiveSaveOptions() { Encoding = Encoding.ASCII });
}Remarks
It is possible to save an archive to the same path as it was loaded from. However, this is not recommended because this approach uses copying to a temporary file.
Exceptions
destinationFileName is null.
The caller does not have the required permission to access.
The destinationFileName is empty, contains only white spaces, or contains invalid characters.
Access to file destinationFileName is denied.
The specified destinationFileName, file name, or both exceed the system-defined maximum length.
For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
File at destinationFileName contains a colon (:) in the middle of the string.
The file is not found.
The specified path is invalid, such as being on an unmapped drive.
The file is already open.
SaveSplit(string, SplitArchiveSaveOptions)
Saves multi-volume archive to destination directory provided.
public void SaveSplit(string destinationDirectory, SplitArchiveSaveOptions options)Parameters
destinationDirectory string
The path to the directory where archive segments to be created.
options SplitArchiveSaveOptions
Options for archive saving, including file name.
Examples
using (Archive archive = new Archive())
{
archive.CreateEntry("entry.bin", "data.bin");
archive.SaveSplit(@"C:\Folder", new SplitArchiveSaveOptions("volume", 65536));
}Remarks
This method composes several (n) files filename.z01, filename.z02, ..., filename.z(n-1), filename.zip.
Cannot make existing archive multi-volume.
Exceptions
This archive was opened from existing source.
This archive is both compressed with XZ method and encrypted.
destinationDirectory is null.
The caller does not have the required permission to access the directory.
destinationDirectory contains invalid characters such as “, >, <, or |.
The specified path exceeds the system-defined maximum length.
The archive is disposed. </stream>
