Table of Contents

Class ZipEntry

Namespace
Ionic.Zip
Assembly
SunamoDotNetZip.dll

Represents a single entry in a ZipFile. Typically, applications get a ZipEntry by enumerating the entries within a ZipFile, or by adding an entry to a ZipFile.

[Guid("ebc25cf6-9120-4283-b972-0e5520d00004")]
[ComVisible(true)]
[ClassInterface(ClassInterfaceType.AutoDispatch)]
public class ZipEntry
Inheritance
ZipEntry
Inherited Members
Extension Methods

Constructors

ZipEntry()

Default constructor.

public ZipEntry()

Remarks

Applications should never need to call this directly. It is exposed to support COM Automation environments.

Properties

AccessedTime

Last Access time for the file represented by the entry.

public DateTime AccessedTime { get; set; }

Property Value

DateTime

Remarks

This value may or may not be meaningful. If the ZipEntry was read from an existing Zip archive, this information may not be available. For an explanation of why, see ModifiedTime.

See Also

AlternateEncoding

Specifies the alternate text encoding used by this ZipEntry

public Encoding AlternateEncoding { get; set; }

Property Value

Encoding

Examples

This example shows how to create a zipfile encoded with a language-specific encoding:

using (var zip = new ZipFile())
{
   zip.AlternateEnoding = System.Text.Encoding.GetEncoding("ibm861");
   zip.AlternateEnodingUsage = ZipOption.Always;
   zip.AddFileS(arrayOfFiles);
   zip.Save("Myarchive-Encoded-in-IBM861.zip");
}

Remarks

The default text encoding used in Zip files for encoding filenames and comments is IBM437, which is something like a superset of ASCII. In cases where this is insufficient, applications can specify an alternate encoding.

When creating a zip file, the usage of the alternate encoding is governed by the AlternateEncodingUsage property. Typically you would set both properties to tell DotNetZip to employ an encoding that is not IBM437 in the zipfile you are creating.

Keep in mind that because the ZIP specification states that the only valid encodings to use are IBM437 and UTF-8, if you use something other than that, then zip tools and libraries may not be able to successfully read the zip archive you generate.

The zip specification states that applications should presume that IBM437 is in use, except when a special bit is set, which indicates UTF-8. There is no way to specify an arbitrary code page, within the zip file itself. When you create a zip file encoded with gb2312 or ibm861 or anything other than IBM437 or UTF-8, then the application that reads the zip file needs to "know" which code page to use. In some cases, the code page used when reading is chosen implicitly. For example, WinRar uses the ambient code page for the host desktop operating system. The pitfall here is that if you create a zip in Copenhagen and send it to Tokyo, the reader of the zipfile may not be able to decode successfully.

See Also

AlternateEncodingUsage

Describes if and when this instance should apply AlternateEncoding to encode the FileName and Comment, when saving.

public ZipOption AlternateEncodingUsage { get; set; }

Property Value

ZipOption
See Also

Attributes

The file attributes for the entry.

public FileAttributes Attributes { get; set; }

Property Value

FileAttributes

Remarks

The attributes in NTFS include ReadOnly, Archive, Hidden, System, and Indexed. When adding a ZipEntry to a ZipFile, these attributes are set implicitly when adding an entry from the filesystem. When adding an entry from a stream or string, the Attributes are not set implicitly. Regardless of the way an entry was added to a ZipFile, you can set the attributes explicitly if you like.

When reading a ZipEntry from a ZipFile, the attributes are set according to the data stored in the ZipFile. If you extract the entry from the archive to a filesystem file, DotNetZip will set the attributes on the resulting file accordingly.

The attributes can be set explicitly by the application. For example the application may wish to set the FileAttributes.ReadOnly bit for all entries added to an archive, so that on unpack, this attribute will be set on the extracted file. Any changes you make to this property are made permanent only when you call a Save() method on the ZipFile instance that contains the ZipEntry.

For example, an application may wish to zip up a directory and set the ReadOnly bit on every file in the archive, so that upon later extraction, the resulting files will be marked as ReadOnly. Not every extraction tool respects these attributes, but if you unpack with DotNetZip, as for example in a self-extracting archive, then the attributes will be set as they are stored in the ZipFile.

These attributes may not be interesting or useful if the resulting archive is extracted on a non-Windows platform. How these attributes get used upon extraction depends on the platform and tool used.

BitField

The bitfield for the entry as defined in the zip spec. You probably never need to look at this.

public short BitField { get; }

Property Value

short

Remarks

You probably do not need to concern yourself with the contents of this property, but in case you do:

bitmeaning
0set if encryption is used.
1-2 set to determine whether normal, max, fast deflation. DotNetZip library always leaves these bits unset when writing (indicating "normal" deflation"), but can read an entry with any value here.
3 Indicates that the Crc32, Compressed and Uncompressed sizes are zero in the local header. This bit gets set on an entry during writing a zip file, when it is saved to a non-seekable output stream.
4reserved for "enhanced deflating". This library doesn't do enhanced deflating.
5set to indicate the zip is compressed patched data. This library doesn't do that.
6 set if PKWare's strong encryption is used (must also set bit 1 if bit 6 is set). This bit is not set if WinZip's AES encryption is set.
7not used
8not used
9not used
10not used
11 Language encoding flag (EFS). If this bit is set, the filename and comment fields for this file must be encoded using UTF-8. This library currently does not support UTF-8.
12Reserved by PKWARE for enhanced compression.
13 Used when encrypting the Central Directory to indicate selected data values in the Local Header are masked to hide their actual values. See the section in the Zip specification describing the Strong Encryption Specification for details.
14Reserved by PKWARE.
15Reserved by PKWARE.

Comment

The comment attached to the ZipEntry.

public string Comment { get; set; }

Property Value

string

Remarks

Each entry in a zip file can optionally have a comment associated to it. The comment might be displayed by a zip tool during extraction, for example.

By default, the Comment is encoded in IBM437 code page. You can specify an alternative with AlternateEncoding and AlternateEncodingUsage.

See Also

CompressedSize

The compressed size of the file, in bytes, within the zip archive.

public long CompressedSize { get; }

Property Value

long

Remarks

When reading a ZipFile, this value is read in from the existing zip file. When creating or updating a ZipFile, the compressed size is computed during compression. Therefore the value on a ZipEntry is valid after a call to Save() (or one of its overloads) in that case.

See Also

CompressionLevel

Sets the compression level to be used for the entry when saving the zip archive. This applies only for CompressionMethod = DEFLATE.

public CompressionLevel CompressionLevel { get; set; }

Property Value

CompressionLevel

Remarks

When using the DEFLATE compression method, Varying the compression level used on entries can affect the size-vs-speed tradeoff when compression and decompressing data streams or files.

If you do not set this property, the default compression level is used, which normally gives a good balance of compression efficiency and compression speed. In some tests, using BestCompression can double the time it takes to compress, while delivering just a small increase in compression efficiency. This behavior will vary with the type of data you compress. If you are in doubt, just leave this setting alone, and accept the default.

When setting this property on a ZipEntry that is read from an existing zip file, calling ZipFile.Save() will cause the new CompressionLevel to be used on the entry in the newly saved zip file.

Setting this property may have the side effect of modifying the CompressionMethod property. If you set the CompressionLevel to a value other than None, CompressionMethod will be set to Deflate, if it was previously None.

Setting this property has no effect if the CompressionMethod is something other than Deflate or None.

See Also

CompressionMethod

The compression method employed for this ZipEntry.

public CompressionMethod CompressionMethod { get; set; }

Property Value

CompressionMethod

Examples

In this example, the first entry added to the zip archive uses the default behavior - compression is used where it makes sense. The second entry, the MP3 file, is added to the archive without being compressed.

using (ZipFile zip = new ZipFile(ZipFileToCreate))
{
  ZipEntry e1= zip.AddFile(@"notes\Readme.txt");
  ZipEntry e2= zip.AddFile(@"music\StopThisTrain.mp3");
  e2.CompressionMethod = CompressionMethod.None;
  zip.Save();
}
Using zip As New ZipFile(ZipFileToCreate)
  zip.AddFile("notes\Readme.txt")
  Dim e2 as ZipEntry = zip.AddFile("music\StopThisTrain.mp3")
  e2.CompressionMethod = CompressionMethod.None
  zip.Save
End Using

Remarks

The Zip specification allows a variety of compression methods. This library supports just two: 0x08 = Deflate. 0x00 = Store (no compression), for reading or writing.

When reading an entry from an existing zipfile, the value you retrieve here indicates the compression method used on the entry by the original creator of the zip. When writing a zipfile, you can specify either 0x08 (Deflate) or 0x00 (None). If you try setting something else, you will get an exception.

You may wish to set CompressionMethod to CompressionMethod.None (0) when zipping already-compressed data like a jpg, png, or mp3 file. This can save time and cpu cycles.

When setting this property on a ZipEntry that is read from an existing zip file, calling ZipFile.Save() will cause the new CompressionMethod to be used on the entry in the newly saved zip file.

Setting this property may have the side effect of modifying the CompressionLevel property. If you set the CompressionMethod to a value other than None, and CompressionLevel is previously set to None, then CompressionLevel will be set to Default.

See Also

CompressionRatio

The ratio of compressed size to uncompressed size of the ZipEntry.

public double CompressionRatio { get; }

Property Value

double

Remarks

This is a ratio of the compressed size to the uncompressed size of the entry, expressed as a double in the range of 0 to 100+. A value of 100 indicates no compression at all. It could be higher than 100 when the compression algorithm actually inflates the data, as may occur for small files, or uncompressible data that is encrypted.

You could format it for presentation to a user via a format string of "{3,5:F0}%" to see it as a percentage.

If the size of the original uncompressed file is 0, implying a denominator of 0, the return value will be zero.

This property is valid after reading in an existing zip file, or after saving the ZipFile that contains the ZipEntry. You cannot know the effect of a compression transform until you try it.

Crc

The 32-bit CRC (Cyclic Redundancy Check) on the contents of the ZipEntry.

public int Crc { get; }

Property Value

int

Remarks

You probably don't need to concern yourself with this. It is used internally by DotNetZip to verify files or streams upon extraction.

The value is a 32-bit CRC using 0xEDB88320 for the polynomial. This is the same CRC-32 used in PNG, MPEG-2, and other protocols and formats. It is a read-only property; when creating a Zip archive, the CRC for each entry is set only after a call to Save() on the containing ZipFile. When reading an existing zip file, the value of this property reflects the stored CRC for the entry.

CreationTime

The file creation time for the file represented by the entry.

public DateTime CreationTime { get; set; }

Property Value

DateTime

Remarks

This value may or may not be meaningful. If the ZipEntry was read from an existing zip archive, and the creation time was not set on the entry when the zip file was created, then this property may be meaningless. For an explanation of why, see ModifiedTime.

See Also

DontEmitLastModified

Ability to set Last Modified DOS time to zero (for using with EmitTimesInWindowsFormatWhenSaving+EmitTimesInUnixFormatWhenSaving setted to false) some flasher hardware use as marker of first binary

public bool DontEmitLastModified { get; set; }

Property Value

bool

EmitTimesInUnixFormatWhenSaving

Specifies whether the Creation, Access, and Modified times for the given entry will be emitted in "Unix(tm) format" when the zip archive is saved.

public bool EmitTimesInUnixFormatWhenSaving { get; set; }

Property Value

bool

Remarks

An application creating a zip archive can use this flag to explicitly specify that the file times for the entry should or should not be stored in the zip archive in the format used by Unix. By default this flag is false, meaning the Unix-format times are not stored in the zip archive.

When adding an entry from a file or directory, the Creation (CreationTime), Access (AccessedTime), and Modified (ModifiedTime) times for the given entry are automatically set from the filesystem values. When adding an entry from a stream or string, all three values are implicitly set to DateTime.Now. Applications can also explicitly set those times by calling SetEntryTimes(DateTime, DateTime, DateTime).

PKWARE's zip specification describes multiple ways to format these times in a zip file. One is the format Windows applications normally use: 100ns ticks since Jan 1, 1601 UTC. The other is a format Unix applications typically use: seconds since Jan 1, 1970 UTC. Each format can be stored in an "extra field" in the zip entry when saving the zip archive. The former uses an extra field with a Header Id of 0x000A, while the latter uses a header ID of 0x5455.

Not all tools and libraries can interpret these fields. Windows compressed folders is one that can read the Windows Format timestamps, while I believe the Infozip tools can read the Unix format timestamps. Although the time values are easily convertible, subject to a loss of precision, some tools and libraries may be able to read only one or the other. DotNetZip can read or write times in either or both formats.

The times stored are taken from ModifiedTime, AccessedTime, and CreationTime.

This property is not mutually exclusive from the EmitTimesInWindowsFormatWhenSaving property. It is possible that a zip entry can embed the timestamps in both forms, one form, or neither. But, there are no guarantees that a program running on Mac or Linux will gracefully handle NTFS Formatted times, or that a non-DotNetZip-powered application running on Windows will be able to handle file times in Unix format. When in doubt, test.

Normally you will use the ZipFile.EmitTimesInUnixFormatWhenSaving property, to specify the behavior for all entries, rather than the property on each individual entry.

See Also

EmitTimesInWindowsFormatWhenSaving

Specifies whether the Creation, Access, and Modified times for the given entry will be emitted in "Windows format" when the zip archive is saved.

public bool EmitTimesInWindowsFormatWhenSaving { get; set; }

Property Value

bool

Remarks

An application creating a zip archive can use this flag to explicitly specify that the file times for the entry should or should not be stored in the zip archive in the format used by Windows. The default value of this property is true.

When adding an entry from a file or directory, the Creation (CreationTime), Access (AccessedTime), and Modified (ModifiedTime) times for the given entry are automatically set from the filesystem values. When adding an entry from a stream or string, all three values are implicitly set to DateTime.Now. Applications can also explicitly set those times by calling SetEntryTimes(DateTime, DateTime, DateTime).

PKWARE's zip specification describes multiple ways to format these times in a zip file. One is the format Windows applications normally use: 100ns ticks since Jan 1, 1601 UTC. The other is a format Unix applications typically use: seconds since January 1, 1970 UTC. Each format can be stored in an "extra field" in the zip entry when saving the zip archive. The former uses an extra field with a Header Id of 0x000A, while the latter uses a header ID of 0x5455.

Not all zip tools and libraries can interpret these fields. Windows compressed folders is one that can read the Windows Format timestamps, while I believe the Infozip tools can read the Unix format timestamps. Although the time values are easily convertible, subject to a loss of precision, some tools and libraries may be able to read only one or the other. DotNetZip can read or write times in either or both formats.

The times stored are taken from ModifiedTime, AccessedTime, and CreationTime.

This property is not mutually exclusive from the EmitTimesInUnixFormatWhenSaving property. It is possible that a zip entry can embed the timestamps in both forms, one form, or neither. But, there are no guarantees that a program running on Mac or Linux will gracefully handle NTFS Formatted times, or that a non-DotNetZip-powered application running on Windows will be able to handle file times in Unix format. When in doubt, test.

Normally you will use the ZipFile.EmitTimesInWindowsFormatWhenSaving property, to specify the behavior for all entries in a zip, rather than the property on each individual entry.

See Also

Encryption

Set this to specify which encryption algorithm to use for the entry when saving it to a zip archive.

public EncryptionAlgorithm Encryption { get; set; }

Property Value

EncryptionAlgorithm

Examples

This example creates a zip archive that uses encryption, and then extracts entries from the archive. When creating the zip archive, the ReadMe.txt file is zipped without using a password or encryption. The other file uses encryption. 

// Create a zip archive with AES Encryption.
using (ZipFile zip = new ZipFile())
{
    zip.AddFile("ReadMe.txt")
    ZipEntry e1= zip.AddFile("2008-Regional-Sales-Report.pdf");
    e1.Encryption= EncryptionAlgorithm.WinZipAes256;
    e1.Password= "Top.Secret.No.Peeking!";
    zip.Save("EncryptedArchive.zip");
}

// Extract a zip archive that uses AES Encryption.
// You do not need to specify the algorithm during extraction.
using (ZipFile zip = ZipFile.Read("EncryptedArchive.zip"))
{
// Specify the password that is used during extraction, for
// all entries that require a password:
zip.Password= "Top.Secret.No.Peeking!";
zip.ExtractAll("extractDirectory");
}
' Create a zip that uses Encryption.
Using zip As New ZipFile()
    zip.AddFile("ReadMe.txt")
    Dim e1 as ZipEntry
    e1= zip.AddFile("2008-Regional-Sales-Report.pdf")
    e1.Encryption= EncryptionAlgorithm.WinZipAes256
    e1.Password= "Top.Secret.No.Peeking!"
    zip.Save("EncryptedArchive.zip")
End Using

' Extract a zip archive that uses AES Encryption.
' You do not need to specify the algorithm during extraction.
Using (zip as ZipFile = ZipFile.Read("EncryptedArchive.zip"))
    ' Specify the password that is used during extraction, for
    ' all entries that require a password:
    zip.Password= "Top.Secret.No.Peeking!"
    zip.ExtractAll("extractDirectory")
End Using

Remarks

Set this property in order to encrypt the entry when the ZipFile is saved. When setting this property, you must also set a Password on the entry. If you set a value other than None on this property and do not set a Password then the entry will not be encrypted. The ZipEntry data is encrypted as the ZipFile is saved, when you call Save() or one of its cousins on the containing ZipFile instance. You do not need to specify the Encryption when extracting entries from an archive.

The Zip specification from PKWare defines a set of encryption algorithms, and the data formats for the zip archive that support them, and PKWare supports those algorithms in the tools it produces. Other vendors of tools and libraries, such as WinZip or Xceed, typically support a subset of the algorithms specified by PKWare. These tools can sometimes support additional different encryption algorithms and data formats, not specified by PKWare. The AES Encryption specified and supported by WinZip is the most popular example. This library supports a subset of the complete set of algorithms specified by PKWare and other vendors.

There is no common, ubiquitous multi-vendor standard for strong encryption within zip files. There is broad support for so-called "traditional" Zip encryption, sometimes called Zip 2.0 encryption, as specified by PKWare, but this encryption is considered weak and breakable. This library currently supports the Zip 2.0 "weak" encryption, and also a stronger WinZip-compatible AES encryption, using either 128-bit or 256-bit key strength. If you want DotNetZip to support an algorithm that is not currently supported, call the author of this library and maybe we can talk business.

The ZipFile class also has a Encryption property. In most cases you will use that property when setting encryption. This property takes precedence over any Encryption set on the ZipFile itself. Typically, you would use the per-entry Encryption when most entries in the zip archive use one encryption algorithm, and a few entries use a different one. If all entries in the zip file use the same Encryption, then it is simpler to just set this property on the ZipFile itself, when creating a zip archive.

Some comments on updating archives: If you read a ZipFile, you can modify the Encryption on an encrypted entry: you can remove encryption from an entry that was encrypted; you can encrypt an entry that was not encrypted previously; or, you can change the encryption algorithm. The changes in encryption are not made permanent until you call Save() on the ZipFile. To effect changes in encryption, the entry content is streamed through several transformations, depending on the modification the application has requested. For example if the entry is not encrypted and the application sets Encryption to PkzipWeak, then at the time of Save(), the original entry is read and decompressed, then re-compressed and encrypted. Conversely, if the original entry is encrypted with PkzipWeak encryption, and the application sets the Encryption property to WinZipAes128, then at the time of Save(), the original entry is decrypted via PKZIP encryption and decompressed, then re-compressed and re-encrypted with AES. This all happens automatically within the library, but it can be time-consuming for large entries.

Additionally, when updating archives, it is not possible to change the password when changing the encryption algorithm. To change both the algorithm and the password, you need to Save() the zipfile twice. First set the Encryption to None, then call Save(). Then set the Encryption to the new value (not "None"), then call Save() once again.

The WinZip AES encryption algorithms are not supported on the .NET Compact Framework.

Exceptions

InvalidOperationException

Thrown in the setter if EncryptionAlgorithm.Unsupported is specified.

See Also

ExtractExistingFile

The action the library should take when extracting a file that already exists.

public ExtractExistingFileAction ExtractExistingFile { get; set; }

Property Value

ExtractExistingFileAction

Examples

This example shows how to set the ExtractExistingFile property in an ExtractProgress event, in response to user input. The ExtractProgress event is invoked if and only if the ExtractExistingFile property was previously set to ExtractExistingFileAction.InvokeExtractProgressEvent.

public static void ExtractProgress(object sender, ExtractProgressEventArgs e)
{
    if (e.EventType == ZipProgressEventType.Extracting_BeforeExtractEntry)
        Console.WriteLine("extract {0} ", e.CurrentEntry.FileName);

    else if (e.EventType == ZipProgressEventType.Extracting_ExtractEntryWouldOverwrite)
    {
        ZipEntry entry = e.CurrentEntry;
        string response = null;
        // Ask the user if he wants overwrite the file
        do
        {
            Console.Write("Overwrite {0} in {1} ? (y/n/C) ", entry.FileName, e.ExtractLocation);
            response = Console.ReadLine();
            Console.WriteLine();

        } while (response != null && response[0]!='Y' &&
                 response[0]!='N' && response[0]!='C');

        if  (response[0]=='C')
            e.Cancel = true;
        else if (response[0]=='Y')
            entry.ExtractExistingFile = ExtractExistingFileAction.OverwriteSilently;
        else
            entry.ExtractExistingFile= ExtractExistingFileAction.DoNotOverwrite;
    }
}

Remarks

This property affects the behavior of the Extract methods (one of the Extract() or ExtractWithPassword() overloads), when extraction would would overwrite an existing filesystem file. If you do not set this property, the library throws an exception when extracting an entry would overwrite an existing file.

This property has no effect when extracting to a stream, or when the file to be extracted does not already exist.

See Also

FileName

The name of the file contained in the ZipEntry.

public string FileName { get; set; }

Property Value

string

Remarks

This is the name of the entry in the ZipFile itself. When creating a zip archive, if the ZipEntry has been created from a filesystem file, via a call to AddFile(string, string) or AddItem(string, string), or a related overload, the value of this property is derived from the name of that file. The FileName property does not include drive letters, and may include a different directory path, depending on the value of the directoryPathInArchive parameter used when adding the entry into the ZipFile.

In some cases there is no related filesystem file - for example when a ZipEntry is created using AddEntry(string, string) or one of the similar overloads. In this case, the value of this property is derived from the fileName and the directory path passed to that method.

When reading a zip file, this property takes the value of the entry name as stored in the zip file. If you extract such an entry, the extracted file will take the name given by this property.

Applications can set this property when creating new zip archives or when reading existing archives. When setting this property, the actual value that is set will replace backslashes with forward slashes, in accordance with the Zip specification, for compatibility with Unix(tm) and ... get this.... Amiga!

If an application reads a ZipFile via Read(string) or a related overload, and then explicitly sets the FileName on an entry contained within the ZipFile, and then calls Save(), the application will effectively rename the entry within the zip archive.

If an application sets the value of FileName, then calls Extract() on the entry, the entry is extracted to a file using the newly set value as the filename. The FileName value is made permanent in the zip archive only after a call to one of the ZipFile.Save() methods on the ZipFile that contains the ZipEntry.

If an application attempts to set the FileName to a value that would result in a duplicate entry in the ZipFile, an exception is thrown.

When a ZipEntry is contained within a ZipFile, applications cannot rename the entry within the context of a foreach (For Each in VB) loop, because of the way the ZipFile stores entries. If you need to enumerate through all the entries and rename one or more of them, use ZipFile.EntriesSorted as the collection. See also, ZipFile.GetEnumerator().

IncludedInMostRecentSave

Indicates whether the entry was included in the most recent save.

public bool IncludedInMostRecentSave { get; }

Property Value

bool

Remarks

An entry can be excluded or skipped from a save if there is an error opening or reading the entry.

See Also

Info

Provides a human-readable string with information about the ZipEntry.

public string Info { get; }

Property Value

string

InputStream

The stream that provides content for the ZipEntry.

public Stream InputStream { get; set; }

Property Value

Stream

Remarks

The application can use this property to set the input stream for an entry on a just-in-time basis. Imagine a scenario where the application creates a ZipFile comprised of content obtained from hundreds of files, via calls to AddFile(). The DotNetZip library opens streams on these files on a just-in-time basis, only when writing the entry out to an external store within the scope of a ZipFile.Save() call. Only one input stream is opened at a time, as each entry is being written out.

Now imagine a different application that creates a ZipFile with content obtained from hundreds of streams, added through AddEntry(string, Stream). Normally the application would supply an open stream to that call. But when large numbers of streams are being added, this can mean many open streams at one time, unnecessarily.

To avoid this, call AddEntry(string, OpenDelegate, CloseDelegate) and specify delegates that open and close the stream at the time of Save.

Setting the value of this property when the entry was not added from a stream (for example, when the ZipEntry was added with AddFile(string) or AddDirectory(string), or when the entry was added by reading an existing zip archive) will throw an exception.

InputStreamWasJitProvided

A flag indicating whether the InputStream was provided Just-in-time.

public bool InputStreamWasJitProvided { get; }

Property Value

bool

Remarks

When creating a zip archive, an application can obtain content for one or more of the ZipEntry instances from streams, using the AddEntry(string, Stream) method. At the time of calling that method, the application can supply null as the value of the stream parameter. By doing so, the application indicates to the library that it will provide a stream for the entry on a just-in-time basis, at the time one of the ZipFile.Save() methods is called and the data for the various entries are being compressed and written out.

In this case, the application can set the InputStream property, typically within the SaveProgress event (event type: Saving_BeforeWriteEntry) for that entry.

The application will later want to call Close() and Dispose() on that stream. In the SaveProgress event, when the event type is Saving_AfterWriteEntry, the application can do so. This flag indicates that the stream has been provided by the application on a just-in-time basis and that it is the application's responsibility to call Close/Dispose on that stream.

See Also

IsDirectory

True if the entry is a directory (not a file). This is a readonly property on the entry.

public bool IsDirectory { get; }

Property Value

bool

IsText

Indicates whether an entry is marked as a text file. Be careful when using on this property. Unless you have a good reason, you should probably ignore this property.

public bool IsText { get; set; }

Property Value

bool

Examples

using (var zip = new ZipFile())
{
    var e = zip.UpdateFile("Descriptions.mme", "");
    e.IsText = true;
    zip.Save(zipPath);
}
Using zip As New ZipFile
    Dim e2 as ZipEntry = zip.AddFile("Descriptions.mme", "")
    e.IsText= True
    zip.Save(zipPath)
End Using

Remarks

The ZIP format includes a provision for specifying whether an entry in the zip archive is a text or binary file. This property exposes that metadata item. Be careful when using this property: It's not clear that this property as a firm meaning, across tools and libraries.

To be clear, when reading a zip file, the property value may or may not be set, and its value may or may not be valid. Not all entries that you may think of as "text" entries will be so marked, and entries marked as "text" are not guaranteed in any way to be text entries. Whether the value is set and set correctly depends entirely on the application that produced the zip file.

There are many zip tools available, and when creating zip files, some of them "respect" the IsText metadata field, and some of them do not. Unfortunately, even when an application tries to do "the right thing", it's not always clear what "the right thing" is.

There's no firm definition of just what it means to be "a text file", and the zip specification does not help in this regard. Twenty years ago, text was ASCII, each byte was less than 127. IsText meant, all bytes in the file were less than 127. These days, it is not the case that all text files have all bytes less than 127. Any unicode file may have bytes that are above 0x7f. The zip specification has nothing to say on this topic. Therefore, it's not clear what IsText really means.

This property merely tells a reading application what is stored in the metadata for an entry, without guaranteeing its validity or its meaning.

When DotNetZip is used to create a zipfile, it attempts to set this field "correctly." For example, if a file ends in ".txt", this field will be set. Your application may override that default setting. When writing a zip file, you must set the property before calling Save() on the ZipFile.

When reading a zip file, a more general way to decide just what kind of file is contained in a particular entry is to use the file type database stored in the operating system. The operating system stores a table that says, a file with .jpg extension is a JPG image file, a file with a .xml extension is an XML document, a file with a .txt is a pure ASCII text document, and so on. To get this information on Windows, you need to read and parse the registry.

LastModified

The time and date at which the file indicated by the ZipEntry was last modified.

public DateTime LastModified { get; set; }

Property Value

DateTime

Remarks

The DotNetZip library sets the LastModified value for an entry, equal to the Last Modified time of the file in the filesystem. If an entry is added from a stream, the library uses System.DateTime.Now for this value, for the given entry.

This property allows the application to retrieve and possibly set the LastModified value on an entry, to an arbitrary value. DateTime values with a DateTimeKind setting of DateTimeKind.Unspecified are taken to be expressed as DateTimeKind.Local.

Be aware that because of the way PKWare's Zip specification describes how times are stored in the zip file, the full precision of the System.DateTime datatype is not stored for the last modified time when saving zip files. For more information on how times are formatted, see the PKZip specification.

The actual last modified time of a file can be stored in multiple ways in the zip file, and they are not mutually exclusive:

  • In the so-called "DOS" format, which has a 2-second precision. Values are rounded to the nearest even second. For example, if the time on the file is 12:34:43, then it will be stored as 12:34:44. This first value is accessible via the LastModified property. This value is always present in the metadata for each zip entry. In some cases the value is invalid, or zero.
  • In the so-called "Windows" or "NTFS" format, as an 8-byte integer quantity expressed as the number of 1/10 milliseconds (in other words the number of 100 nanosecond units) since January 1, 1601 (UTC). This format is how Windows represents file times. This time is accessible via the ModifiedTime property.
  • In the "Unix" format, a 4-byte quantity specifying the number of seconds since January 1, 1970 UTC.
  • In an older format, now deprecated but still used by some current tools. This format is also a 4-byte quantity specifying the number of seconds since January 1, 1970 UTC.

Zip tools and libraries will always at least handle (read or write) the DOS time, and may also handle the other time formats. Keep in mind that while the names refer to particular operating systems, there is nothing in the time formats themselves that prevents their use on other operating systems.

When reading ZIP files, the DotNetZip library reads the Windows-formatted time, if it is stored in the entry, and sets both LastModified and ModifiedTime to that value. When writing ZIP files, the DotNetZip library by default will write both time quantities. It can also emit the Unix-formatted time if desired (See EmitTimesInUnixFormatWhenSaving.)

The last modified time of the file created upon a call to ZipEntry.Extract() may be adjusted during extraction to compensate for differences in how the .NET Base Class Library deals with daylight saving time (DST) versus how the Windows filesystem deals with daylight saving time. Raymond Chen provides some good context.

In a nutshell: Daylight savings time rules change regularly. In 2007, for example, the inception week of DST changed. In 1977, DST was in place all year round. In 1945, likewise. And so on. Win32 does not attempt to guess which time zone rules were in effect at the time in question. It will render a time as "standard time" and allow the app to change to DST as necessary. .NET makes a different choice.

Compare the output of FileInfo.LastWriteTime.ToString("f") with what you see in the Windows Explorer property sheet for a file that was last written to on the other side of the DST transition. For example, suppose the file was last modified on October 17, 2003, during DST but DST is not currently in effect. Explorer's file properties reports Thursday, October 17, 2003, 8:45:38 AM, but .NETs FileInfo reports Thursday, October 17, 2003, 9:45 AM.

Win32 says, "Thursday, October 17, 2002 8:45:38 AM PST". Note: Pacific STANDARD Time. Even though October 17 of that year occurred during Pacific Daylight Time, Win32 displays the time as standard time because that's what time it is NOW.

.NET BCL assumes that the current DST rules were in place at the time in question. So, .NET says, "Well, if the rules in effect now were also in effect on October 17, 2003, then that would be daylight time" so it displays "Thursday, October 17, 2003, 9:45 AM PDT" - daylight time.

So .NET gives a value which is more intuitively correct, but is also potentially incorrect, and which is not invertible. Win32 gives a value which is intuitively incorrect, but is strictly correct.

Because of this funkiness, this library adds one hour to the LastModified time on the extracted file, if necessary. That is to say, if the time in question had occurred in what the .NET Base Class Library assumed to be DST. This assumption may be wrong given the constantly changing DST rules, but it is the best we can do.

ModifiedTime

Last Modified time for the file represented by the entry.

public DateTime ModifiedTime { get; set; }

Property Value

DateTime

Remarks

This value corresponds to the "last modified" time in the NTFS file times as described in the Zip specification. When getting this property, the value may be different from LastModified. When setting the property, the LastModified property also gets set, but with a lower precision.

Let me explain. It's going to take a while, so get comfortable. Originally, waaaaay back in 1989 when the ZIP specification was originally described by the esteemed Mr. Phil Katz, the dominant operating system of the time was MS-DOS. MSDOS stored file times with a 2-second precision, because, c'mon, who is ever going to need better resolution than THAT? And so ZIP files, regardless of the platform on which the zip file was created, store file times in exactly the same format that DOS used in 1989.

Since then, the ZIP spec has evolved, but the internal format for file timestamps remains the same. Despite the fact that the way times are stored in a zip file is rooted in DOS heritage, any program on any operating system can format a time in this way, and most zip tools and libraries DO - they round file times to the nearest even second and store it just like DOS did 25+ years ago.

PKWare extended the ZIP specification to allow a zip file to store what are called "NTFS Times" and "Unix(tm) times" for a file. These are the last write, last access, and file creation times of a particular file. These metadata are not actually specific to NTFS or Unix. They are tracked for each file by NTFS and by various Unix filesystems, but they are also tracked by other filesystems, too. The key point is that the times are formatted in the zip file in the same way that NTFS formats the time (ticks since win32 epoch), or in the same way that Unix formats the time (seconds since Unix epoch). As with the DOS time, any tool or library running on any operating system is capable of formatting a time in one of these ways and embedding it into the zip file.

These extended times are higher precision quantities than the DOS time. As described above, the (DOS) LastModified has a precision of 2 seconds. The Unix time is stored with a precision of 1 second. The NTFS time is stored with a precision of 0.0000001 seconds. The quantities are easily convertible, except for the loss of precision you may incur.

A zip archive can store the {C,A,M} times in NTFS format, in Unix format, or not at all. Often a tool running on Unix or Mac will embed the times in Unix format (1 second precision), while WinZip running on Windows might embed the times in NTFS format (precision of of 0.0000001 seconds). When reading a zip file with these "extended" times, in either format, DotNetZip represents the values with the ModifiedTime, AccessedTime and CreationTime properties on the ZipEntry.

While any zip application or library, regardless of the platform it runs on, could use any of the time formats allowed by the ZIP specification, not all zip tools or libraries do support all these formats. Storing the higher-precision times for each entry is optional for zip files, and many tools and libraries don't use the higher precision quantities at all. The old DOS time, represented by LastModified, is guaranteed to be present, though it sometimes unset.

Ok, getting back to the question about how the LastModified property relates to this ModifiedTime property... LastModified is always set, while ModifiedTime is not. (The other times stored in the NTFS times extension, CreationTime and AccessedTime also may not be set on an entry that is read from an existing zip file.) When reading a zip file, then LastModified takes the DOS time that is stored with the file. If the DOS time has been stored as zero in the zipfile, then this library will use DateTime.Now for the LastModified value. If the ZIP file was created by an evolved tool, then there will also be higher precision NTFS or Unix times in the zip file. In that case, this library will read those times, and set LastModified and ModifiedTime to the same value, the one corresponding to the last write time of the file. If there are no higher precision times stored for the entry, then ModifiedTime remains unset (likewise AccessedTime and CreationTime), and LastModified keeps its DOS time.

When creating zip files with this library, by default the extended time properties (ModifiedTime, AccessedTime, and CreationTime) are set on the ZipEntry instance, and these data are stored in the zip archive for each entry, in NTFS format. If you add an entry from an actual filesystem file, then the entry gets the actual file times for that file, to NTFS-level precision. If you add an entry from a stream, or a string, then the times get the value DateTime.Now. In this case LastModified and ModifiedTime will be identical, to 2 seconds of precision. You can explicitly set the CreationTime, AccessedTime, and ModifiedTime of an entry using the property setters. If you want to set all of those quantities, it's more efficient to use the SetEntryTimes(DateTime, DateTime, DateTime) method. Those changes are not made permanent in the zip file until you call Save() or one of its cousins.

When creating a zip file, you can override the default behavior of this library for formatting times in the zip file, disabling the embedding of file times in NTFS format or enabling the storage of file times in Unix format, or both. You may want to do this, for example, when creating a zip file on Windows, that will be consumed on a Mac, by an application that is not hip to the "NTFS times" format. To do this, use the EmitTimesInWindowsFormatWhenSaving and EmitTimesInUnixFormatWhenSaving properties. A valid zip file may store the file times in both formats. But, there are no guarantees that a program running on Mac or Linux will gracefully handle the NTFS-formatted times when Unix times are present, or that a non-DotNetZip-powered application running on Windows will be able to handle file times in Unix format. DotNetZip will always do something reasonable; other libraries or tools may not. When in doubt, test.

I'll bet you didn't think one person could type so much about time, eh? And reading it was so enjoyable, too! Well, in appreciation, maybe you should donate?

See Also

OutputUsedZip64

Indicates whether the entry actually used ZIP64 extensions, as it was most recently written to the output file or stream.

public bool? OutputUsedZip64 { get; }

Property Value

bool?

Remarks

This Nullable property is null (Nothing in VB) until a Save() method on the containing ZipFile instance has been called. HasValue is true only after a Save() method has been called.

The value of this property for a particular ZipEntry may change over successive calls to Save() methods on the containing ZipFile, even if the file that corresponds to the ZipEntry does not. This may happen if other entries contained in the ZipFile expand, causing the offset for this particular entry to exceed 0xFFFFFFFF.

See Also

Password

The Password to be used when encrypting a ZipEntry upon ZipFile.Save(), or when decrypting an entry upon Extract().

public string Password { set; }

Property Value

string

Examples

This example creates a zip file with two entries, and then extracts the entries from the zip file. When creating the zip file, the two files are added to the zip file using password protection. Each entry uses a different password. During extraction, each file is extracted with the appropriate password. 

// create a file with encryption
using (ZipFile zip = new ZipFile())
{
    ZipEntry entry;
    entry= zip.AddFile("Declaration.txt");
    entry.Password= "123456!";
    entry = zip.AddFile("Report.xls");
    entry.Password= "1Secret!";
    zip.Save("EncryptedArchive.zip");
}

// extract entries that use encryption
using (ZipFile zip = ZipFile.Read("EncryptedArchive.zip"))
{
ZipEntry entry;
entry = zip["Declaration.txt"];
entry.Password = "123456!";
entry.Extract("extractDir");
entry = zip["Report.xls"];
entry.Password = "1Secret!";
entry.Extract("extractDir");
}
Using zip As New ZipFile
    Dim entry as ZipEntry
    entry= zip.AddFile("Declaration.txt")
    entry.Password= "123456!"
    entry = zip.AddFile("Report.xls")
    entry.Password= "1Secret!"
    zip.Save("EncryptedArchive.zip")
End Using


' extract entries that use encryption
Using (zip as ZipFile = ZipFile.Read("EncryptedArchive.zip"))
    Dim entry as ZipEntry
    entry = zip("Declaration.txt")
    entry.Password = "123456!"
    entry.Extract("extractDir")
    entry = zip("Report.xls")
    entry.Password = "1Secret!"
    entry.Extract("extractDir")
End Using

Remarks

This is a write-only property on the entry. Set this to request that the entry be encrypted when writing the zip archive, or set it to specify the password to be used when extracting an existing entry that is encrypted.

The password set here is implicitly used to encrypt the entry during the Save() operation, or to decrypt during the Extract() or OpenReader() operation. If you set the Password on a ZipEntry after calling Save(), there is no effect.

Consider setting the Encryption property when using a password. Answering concerns that the standard password protection supported by all zip tools is weak, WinZip has extended the ZIP specification with a way to use AES Encryption to protect entries in the Zip file. Unlike the "PKZIP 2.0" encryption specified in the PKZIP specification, AES Encryption uses a standard, strong, tested, encryption algorithm. DotNetZip can create zip archives that use WinZip-compatible AES encryption, if you set the Encryption property. But, archives created that use AES encryption may not be readable by all other tools and libraries. For example, Windows Explorer cannot read a "compressed folder" (a zip file) that uses AES encryption, though it can read a zip file that uses "PKZIP encryption."

The ZipFile class also has a Password property. This property takes precedence over any password set on the ZipFile itself. Typically, you would use the per-entry Password when most entries in the zip archive use one password, and a few entries use a different password. If all entries in the zip file use the same password, then it is simpler to just set this property on the ZipFile itself, whether creating a zip archive or extracting a zip archive.

Some comments on updating archives: If you read a ZipFile, you cannot modify the password on any encrypted entry, except by extracting the entry with the original password (if any), removing the original entry via RemoveEntry(ZipEntry), and then adding a new entry with a new Password.

For example, suppose you read a ZipFile, and there is an encrypted entry. Setting the Password property on that ZipEntry and then calling Save() on the ZipFile does not update the password on that entry in the archive. Neither is an exception thrown. Instead, what happens during the Save() is the existing entry is copied through to the new zip archive, in its original encrypted form. Upon re-reading that archive, the entry can be decrypted with its original password.

If you read a ZipFile, and there is an un-encrypted entry, you can set the Password on the entry and then call Save() on the ZipFile, and get encryption on that entry.

See Also

ProvisionalAlternateEncoding

The text encoding to use for the FileName and Comment on this ZipEntry, when the default encoding is insufficient.

[Obsolete("This property is obsolete since v1.9.1.6. Use AlternateEncoding and AlternateEncodingUsage instead.", true)]
public Encoding ProvisionalAlternateEncoding { get; set; }

Property Value

Encoding

Remarks

Don't use this property. See AlternateEncoding.

RequiresZip64

Indicates whether the entry requires ZIP64 extensions.

public bool? RequiresZip64 { get; }

Property Value

bool?

Remarks

This property is null (Nothing in VB) until a Save() method on the containing ZipFile instance has been called. The property is non-null (HasValue is true) only after a Save() method has been called.

After the containing ZipFile has been saved, the Value of this property is true if any of the following three conditions holds: the uncompressed size of the entry is larger than 0xFFFFFFFF; the compressed size of the entry is larger than 0xFFFFFFFF; the relative offset of the entry within the zip archive is larger than 0xFFFFFFFF. These quantities are not known until a Save() is attempted on the zip archive and the compression is applied.

If none of the three conditions holds, then the Value is false.

A Value of false does not indicate that the entry, as saved in the zip archive, does not use ZIP64. It merely indicates that ZIP64 is not required. An entry may use ZIP64 even when not required if the UseZip64WhenSaving property on the containing ZipFile instance is set to Always, or if the UseZip64WhenSaving property on the containing ZipFile instance is set to AsNecessary and the output stream was not seekable.

See Also

SetCompression

A callback that allows the application to specify the compression to use for a given entry that is about to be added to the zip archive.

public SetCompressionCallback SetCompression { get; set; }

Property Value

SetCompressionCallback

Remarks

See SetCompression

Source

An enum indicating the source of the ZipEntry.

public ZipEntrySource Source { get; }

Property Value

ZipEntrySource

Timestamp

The type of timestamp attached to the ZipEntry.

public ZipEntryTimestamp Timestamp { get; }

Property Value

ZipEntryTimestamp

Remarks

This property is valid only for a ZipEntry that was read from a zip archive. It indicates the type of timestamp attached to the entry.

See Also

UncompressedSize

The size of the file, in bytes, before compression, or after extraction.

public long UncompressedSize { get; }

Property Value

long

Remarks

When reading a ZipFile, this value is read in from the existing zip file. When creating or updating a ZipFile, the uncompressed size is computed during compression. Therefore the value on a ZipEntry is valid after a call to Save() (or one of its overloads) in that case.

See Also

UseUnicodeAsNecessary

Set to indicate whether to use UTF-8 encoding for filenames and comments.

[Obsolete("Beginning with v1.9.1.6 of DotNetZip, this property is obsolete.  It will be removed in a future version of the library. Your applications should  use AlternateEncoding and AlternateEncodingUsage instead.")]
public bool UseUnicodeAsNecessary { get; set; }

Property Value

bool

Remarks

If this flag is set, the comment and filename for the entry will be encoded with UTF-8, as described in the Zip specification, if necessary. "Necessary" means, the filename or entry comment (if any) cannot be reflexively encoded and decoded using the default code page, IBM437.

Setting this flag to true is equivalent to setting ProvisionalAlternateEncoding to System.Text.Encoding.UTF8.

This flag has no effect or relation to the text encoding used within the file itself.

UsesEncryption

A derived property that is true if the entry uses encryption.

public bool UsesEncryption { get; }

Property Value

bool

Remarks

This is a readonly property on the entry. When reading a zip file, the value for the ZipEntry is determined by the data read from the zip file. After saving a ZipFile, the value of this property for each ZipEntry indicates whether encryption was actually used (which will have been true if the Password was set and the Encryption property was something other than None.

VersionNeeded

The version of the zip engine needed to read the ZipEntry.

public short VersionNeeded { get; }

Property Value

short

Remarks

This is a readonly property, indicating the version of the Zip specification that the extracting tool or library must support to extract the given entry. Generally higher versions indicate newer features. Older zip engines obviously won't know about new features, and won't be able to extract entries that depend on those newer features.

valueFeatures
20a basic Zip Entry, potentially using PKZIP encryption.
45The ZIP64 extension is used on the entry.
46 File is compressed using BZIP2 compression*
50 File is encrypted using PkWare's DES, 3DES, (broken) RC2 or RC4
51 File is encrypted using PKWare's AES encryption or corrected RC2 encryption.
52 File is encrypted using corrected RC2-64 encryption**
61 File is encrypted using non-OAEP key wrapping***
63 File is compressed using LZMA, PPMd+, Blowfish, or Twofish

There are other values possible, not listed here. DotNetZip supports regular PKZip encryption, and ZIP64 extensions. DotNetZip cannot extract entries that require a zip engine higher than 45.

This value is set upon reading an existing zip file, or after saving a zip archive.

ZipErrorAction

The action to take when an error is encountered while opening or reading files as they are saved into a zip archive.

public ZipErrorAction ZipErrorAction { get; set; }

Property Value

ZipErrorAction

Remarks

Errors can occur within a call to ZipFile.Save, as the various files contained in a ZipFile are being saved into the zip archive. During the Save, DotNetZip will perform a File.Open on the file associated to the ZipEntry, and then will read the entire contents of the file as it is zipped. Either the open or the Read may fail, because of lock conflicts or other reasons. Using this property, you can specify the action to take when such errors occur.

Typically you will NOT set this property on individual ZipEntry instances. Instead, you will set the ZipFile.ZipErrorAction property on the ZipFile instance, before adding any entries to the ZipFile. If you do this, errors encountered on behalf of any of the entries in the ZipFile will be handled the same way.

But, if you use a ZipError handler, you will want to set this property on the ZipEntry within the handler, to communicate back to DotNetZip what you would like to do with the particular error.

See Also

Methods

CloneForNewZipFile(ZipFile)

Creates a new ZipEntry that is a clone of the current entry, suitable for adding to a different zip file.

public ZipEntry CloneForNewZipFile(ZipFile newZipFile)

Parameters

newZipFile ZipFile

The target ZipFile where the entry will be added.

Returns

ZipEntry

A cloned ZipEntry for the new zip file.

Exceptions

InvalidOperationException

Thrown if the current entry was not loaded from a zip file, has been modified, represents a directory, uses a different compression method than the target zip file, or is from a multi-part zip.

Extract()

Extract the entry to the filesystem, starting at the current working directory.

public void Extract()

Remarks

This method extracts an entry from a zip file into the current working directory. The path of the entry as extracted is the full path as specified in the zip archive, relative to the current working directory. After the file is extracted successfully, the file attributes and timestamps are set.

The action taken when extraction an entry would overwrite an existing file is determined by the ExtractExistingFile property.

Within the call to Extract(), the content for the entry is written into a filesystem file, and then the last modified time of the file is set according to the LastModified property on the entry. See the remarks the LastModified property for some details about the last modified time.

See Also

Extract(ExtractExistingFileAction)

Extract the entry to a file in the filesystem, using the specified behavior when extraction would overwrite an existing file.

public void Extract(ExtractExistingFileAction extractExistingFile)

Parameters

extractExistingFile ExtractExistingFileAction

The action to take if extraction would overwrite an existing file.

Remarks

See the remarks on the LastModified property, for some details about how the last modified time of the file is set after extraction.

Extract(Stream)

Extracts the entry to the specified stream.

public void Extract(Stream stream)

Parameters

stream Stream

the stream to which the entry should be extracted.

Remarks

The caller can specify any write-able stream, for example a FileStream, a MemoryStream, or ASP.NET's Response.OutputStream. The content will be decrypted and decompressed as necessary. If the entry is encrypted and no password is provided, this method will throw.

The position on the stream is not reset by this method before it extracts. You may want to call stream.Seek() before calling ZipEntry.Extract().

Extract(string)

Extract the entry to the filesystem, starting at the specified base directory.

public void Extract(string baseDirectory)

Parameters

baseDirectory string

the pathname of the base directory

Examples

This example extracts only the entries in a zip file that are .txt files, into a directory called "textfiles".

using (ZipFile zip = ZipFile.Read("PackedDocuments.zip"))
{
  foreach (string s1 in zip.EntryFilenames)
  {
    if (s1.EndsWith(".txt"))
    {
      zip[s1].Extract("textfiles");
    }
  }
}
Using zip As ZipFile = ZipFile.Read("PackedDocuments.zip")
    Dim s1 As String
    For Each s1 In zip.EntryFilenames
        If s1.EndsWith(".txt") Then
            zip(s1).Extract("textfiles")
        End If
    Next
End Using

Remarks

Using this method, existing entries in the filesystem will not be overwritten. If you would like to force the overwrite of existing files, see the ExtractExistingFile property, or call Extract(string, ExtractExistingFileAction).

See the remarks on the LastModified property, for some details about how the last modified time of the created file is set.

See Also

Extract(string, ExtractExistingFileAction)

Extract the entry to the filesystem, starting at the specified base directory, and using the specified behavior when extraction would overwrite an existing file.

public void Extract(string baseDirectory, ExtractExistingFileAction extractExistingFile)

Parameters

baseDirectory string

the pathname of the base directory

extractExistingFile ExtractExistingFileAction

The action to take if extraction would overwrite an existing file.

Examples

String sZipPath = "Airborne.zip";
String sFilePath = "Readme.txt";
String sRootFolder = "Digado";
using (ZipFile zip = ZipFile.Read(sZipPath))
{
  if (zip.EntryFileNames.Contains(sFilePath))
  {
    // use the string indexer on the zip file
    zip[sFileName].Extract(sRootFolder,
                           ExtractExistingFileAction.OverwriteSilently);
  }
}
Dim sZipPath as String = "Airborne.zip"
Dim sFilePath As String = "Readme.txt"
Dim sRootFolder As String = "Digado"
Using zip As ZipFile = ZipFile.Read(sZipPath)
  If zip.EntryFileNames.Contains(sFilePath)
    ' use the string indexer on the zip file
    zip(sFilePath).Extract(sRootFolder, _
                           ExtractExistingFileAction.OverwriteSilently)
  End If
End Using

Remarks

See the remarks on the LastModified property, for some details about how the last modified time of the created file is set.

ExtractWithPassword(ExtractExistingFileAction, string)

Extract the entry to a file in the filesystem, relative to the current directory, using the specified behavior when extraction would overwrite an existing file.

public void ExtractWithPassword(ExtractExistingFileAction extractExistingFile, string password)

Parameters

extractExistingFile ExtractExistingFileAction

The action to take if extraction would overwrite an existing file.

password string

The Password to use for decrypting the entry.

Remarks

See the remarks on the LastModified property, for some details about how the last modified time of the created file is set.

ExtractWithPassword(Stream, string)

Extracts the entry to the specified stream, using the specified Password. For example, the caller could extract to Console.Out, or to a MemoryStream.

public void ExtractWithPassword(Stream stream, string password)

Parameters

stream Stream

the stream to which the entry should be extracted.

password string

The password to use for decrypting the entry.

Remarks

The caller can specify any write-able stream, for example a FileStream, a MemoryStream, or ASP.NET's Response.OutputStream. The content will be decrypted and decompressed as necessary. If the entry is encrypted and no password is provided, this method will throw.

The position on the stream is not reset by this method before it extracts. You may want to call stream.Seek() before calling ZipEntry.Extract().

ExtractWithPassword(string)

Extract the entry to the filesystem, using the current working directory and the specified password.

public void ExtractWithPassword(string password)

Parameters

password string

The Password to use for decrypting the entry.

Examples

In this example, entries that use encryption are extracted using a particular password.

using (var zip = ZipFile.Read(FilePath))
{
    foreach (ZipEntry e in zip)
    {
        if (e.UsesEncryption)
            e.ExtractWithPassword("Secret!");
        else
            e.Extract();
    }
}
Using zip As ZipFile = ZipFile.Read(FilePath)
    Dim e As ZipEntry
    For Each e In zip
        If (e.UsesEncryption)
          e.ExtractWithPassword("Secret!")
        Else
          e.Extract
        End If
    Next
End Using

Remarks

Existing entries in the filesystem will not be overwritten. If you would like to force the overwrite of existing files, see the ExtractExistingFileproperty, or call ExtractWithPassword(ExtractExistingFileAction, string).

See the remarks on the LastModified property for some details about how the "last modified" time of the created file is set.

See Also

ExtractWithPassword(string, ExtractExistingFileAction, string)

Extract the entry to the filesystem, starting at the specified base directory, and using the specified behavior when extraction would overwrite an existing file.

public void ExtractWithPassword(string baseDirectory, ExtractExistingFileAction extractExistingFile, string password)

Parameters

baseDirectory string

the pathname of the base directory

extractExistingFile ExtractExistingFileAction

The action to take if extraction would overwrite an existing file.

password string

The Password to use for decrypting the entry.

Remarks

See the remarks on the LastModified property, for some details about how the last modified time of the created file is set.

ExtractWithPassword(string, string)

Extract the entry to the filesystem, starting at the specified base directory, and using the specified password.

public void ExtractWithPassword(string baseDirectory, string password)

Parameters

baseDirectory string

The pathname of the base directory.

password string

The Password to use for decrypting the entry.

Remarks

Existing entries in the filesystem will not be overwritten. If you would like to force the overwrite of existing files, see the ExtractExistingFileproperty, or call ExtractWithPassword(ExtractExistingFileAction, string).

See the remarks on the LastModified property, for some details about how the last modified time of the created file is set.

See Also

OpenReader()

Opens a readable stream corresponding to the zip entry in the archive. The stream decompresses and decrypts as necessary, as it is read.

public CrcCalculatorStream OpenReader()

Returns

CrcCalculatorStream

The Stream for reading.

Examples

This example shows how to open a zip archive, then read in a named entry via a stream. After the read loop is complete, the code compares the calculated during the read loop with the expected CRC on the ZipEntry, to verify the extraction.

using (ZipFile zip = new ZipFile(ZipFileToRead))
{
  ZipEntry e1= zip["Elevation.mp3"];
  using (CrcCalculatorStream s = e1.OpenReader())
  {
    byte[] buffer = new byte[4096];
    int n, totalBytesRead= 0;
    do {
      n = s.Read(buffer,0, buffer.Length);
      totalBytesRead+=n;
    } while (n>0);
     if (s.Crc32 != e1.Crc32)
      throw new Exception(string.Format("The Zip Entry failed the CRC Check. (0x{0:X8}!=0x{1:X8})", s.Crc32, e1.Crc32));
     if (totalBytesRead != e1.UncompressedSize)
      throw new Exception(string.Format("We read an unexpected number of bytes. ({0}!={1})", totalBytesRead, e1.UncompressedSize));
  }
}
Using zip As New ZipFile(ZipFileToRead)
    Dim e1 As ZipEntry = zip.Item("Elevation.mp3")
    Using s As CrcCalculatorStream = e1.OpenReader
        Dim n As Integer
        Dim buffer As Byte() = New Byte(4096) {}
        Dim totalBytesRead As Integer = 0
        Do
            n = s.Read(buffer, 0, buffer.Length)
            totalBytesRead = (totalBytesRead + n)
        Loop While (n > 0)
        If (s.Crc32 <> e1.Crc32) Then
            Throw New Exception(String.Format("The Zip Entry failed the CRC Check. (0x{0:X8}!=0x{1:X8})", s.Crc32, e1.Crc32))
        End If
        If (totalBytesRead <> e1.UncompressedSize) Then
            Throw New Exception(String.Format("We read an unexpected number of bytes. ({0}!={1})", totalBytesRead, e1.UncompressedSize))
        End If
    End Using
End Using

Remarks

DotNetZip offers a variety of ways to extract entries from a zip file. This method allows an application to extract an entry by reading a Stream.

The return value is of type CrcCalculatorStream. Use it as you would any stream for reading. When an application calls Read(byte[], int, int) on that stream, it will receive data from the zip entry that is decrypted and decompressed as necessary.

CrcCalculatorStream adds one additional feature: it keeps a CRC32 checksum on the bytes of the stream as it is read. The CRC value is available in the Crc property on the CrcCalculatorStream. When the read is complete, your application should check this CRC against the Crc property on the ZipEntry to validate the content of the ZipEntry. You don't have to validate the entry using the CRC, but you should, to verify integrity. Check the example for how to do this.

If the entry is protected with a password, then you need to provide a password prior to calling OpenReader(), either by setting the Password property on the entry, or the Password property on the ZipFile itself. Or, you can use OpenReader(string), the overload of OpenReader that accepts a password parameter.

If you want to extract entry data into a write-able stream that is already opened, like a FileStream, do not use this method. Instead, use Extract(Stream).

Your application may use only one stream created by OpenReader() at a time, and you should not call other Extract methods before completing your reads on a stream obtained from OpenReader(). This is because there is really only one source stream for the compressed content. A call to OpenReader() seeks in the source stream, to the beginning of the compressed content. A subsequent call to OpenReader() on a different entry will seek to a different position in the source stream, as will a call to Extract() or one of its overloads. This will corrupt the state for the decompressing stream from the original call to OpenReader().

The OpenReader() method works only when the ZipEntry is obtained from an instance of ZipFile. This method will throw an exception if the ZipEntry is obtained from a ZipInputStream.

See Also

OpenReader(string)

Opens a readable stream for an encrypted zip entry in the archive. The stream decompresses and decrypts as necessary, as it is read.

public CrcCalculatorStream OpenReader(string password)

Parameters

password string

The password to use for decrypting the entry.

Returns

CrcCalculatorStream

The Stream for reading.

Remarks

See the documentation on the OpenReader() method for full details. This overload allows the application to specify a password for the ZipEntry to be read.

SetEntryTimes(DateTime, DateTime, DateTime)

Sets the NTFS Creation, Access, and Modified times for the given entry.

public void SetEntryTimes(DateTime created, DateTime accessed, DateTime modified)

Parameters

created DateTime

the creation time of the entry.

accessed DateTime

the last access time of the entry.

modified DateTime

the last modified time of the entry.

Remarks

When adding an entry from a file or directory, the Creation, Access, and Modified times for the given entry are automatically set from the filesystem values. When adding an entry from a stream or string, the values are implicitly set to DateTime.Now. The application may wish to set these values to some arbitrary value, before saving the archive, and can do so using the various setters. If you want to set all of the times, this method is more efficient.

The values you set here will be retrievable with the ModifiedTime, CreationTime and AccessedTime properties.

When this method is called, if both EmitTimesInWindowsFormatWhenSaving and EmitTimesInUnixFormatWhenSaving are false, then the EmitTimesInWindowsFormatWhenSaving flag is automatically set.

DateTime values provided here without a DateTimeKind are assumed to be Local Time.

See Also

ToString()

Provides a string representation of the instance.

public override string ToString()

Returns

string

a string representation of the instance.

Edit this page