Chilkat.Zip Class Overview

Chilkat.Zip provides a full-featured API for creating, opening, modifying, inspecting, extracting, encrypting, and writing ZIP archives. It supports filesystem entries, in-memory entries, ZIP64, ZIPX, AES encryption, legacy password protection, wildcard matching, selective extraction, path control, exclusions, self-extracting EXEs on Windows, and in-memory ZIP processing.

What the Class Is Used For

Use Chilkat.Zip when an application needs to work with ZIP archives from files, memory, embedded resources, or self-extracting EXEs. The class maintains an in-memory representation of the ZIP directory and entries. Files and data entries can be added, removed, inspected, or extracted, and the final archive is written only when a Write* method is called.

Create ZIP Archives Add files, directories, strings, bytes, BinData, and StringBuilder content.
Open Existing ZIPs Open from disk, memory, BinData, embedded resources, or self-extracting EXEs.
Extract Selectively Extract all files, newer files, matching entries, or files into a single directory.
Encrypt and Protect Create AES-encrypted ZIPs or work with legacy Zip 2.0 password-protected archives.

Important Object Model

Many methods modify the in-memory ZIP object, not the ZIP file on disk immediately. For example, AddFile, AppendFiles, AddString, AddData, and DeleteEntry update the ZIP object. The archive is written only when a method such as WriteZip, WriteZipAndClose, WriteBd, or WriteToMemory is called.

Practical rule: Think of Chilkat.Zip as a ZIP workspace. You open or create the workspace, add or modify entries, and then explicitly write the final ZIP archive.

Typical Workflow: Create a ZIP File

  1. Call NewZip to initialize a new ZIP archive and set the output filename.
  2. Optionally set path behavior with AppendFromDir, DiscardPaths, or PathPrefix.
  3. Add filesystem files with AddFile, AppendFiles, or AppendFilesEx.
  4. Add in-memory entries with AddString, AddData, AddBd, or AddSb.
  5. Optionally configure encryption, compression level, no-compress extensions, exclusions, comments, or ZIPX behavior.
  6. Call WriteZip, WriteZipAndClose, WriteBd, or WriteToMemory to produce the final archive.
  7. If a method fails or behaves unexpectedly, inspect LastErrorText.

Typical Workflow: Open and Extract a ZIP

  1. Open the archive with OpenZip, OpenFromMemory, or OpenBd.
  2. If the ZIP is encrypted or password protected, set DecryptPassword.
  3. Optionally call VerifyPassword before extraction.
  4. Optionally inspect entries using NumEntries, FileCount, EntryAt, EntryMatching, or GetDirectoryAsXML.
  5. Configure extraction behavior with OverwriteExisting, ClearReadOnlyAttr, MaxUncompressSize, MinDate, or MaxDate.
  6. Extract with Unzip, UnzipInto, UnzipMatching, UnzipMatchingInto, or UnzipNewer.

Core Concepts

Concept Meaning Important Members
ZIP Workspace The object holds entries in memory until a write method saves the archive. NewZip, WriteZip, WriteZipAndClose
Filesystem Entries Files and directories referenced from the local filesystem. AddFile, AppendFiles, AppendFilesEx
In-Memory Entries ZIP entries created from strings, bytes, BinData, or StringBuilder content. AddString, AddData, AddBd, AddSb
Entry Inspection Retrieve, search, and inspect entries before extraction or writing. EntryAt, EntryOf, EntryMatching, GetDirectoryAsXML
Selective Extraction Extract only selected entries, newer entries, or flatten paths. UnzipMatching, UnzipNewer, UnzipInto
Self-Extracting EXE Windows-only support for creating and extracting Chilkat self-extracting executables. WriteExe, WriteExe2, ExtractExe

Adding Entries

Method Adds Important Details
AddFile Local file or directory Adds a filesystem reference. File data is read later when a Write* method is called.
AppendFiles Files matching a wildcard pattern Supports * wildcards and optional recursive directory processing.
AppendFilesEx Files matching a wildcard pattern with advanced options Adds controls for saving extra paths, archive-only files, hidden files, and system files.
AddString String as a text file Converts text to bytes using the specified charset and stores it as a ZIP entry.
AddSb StringBuilder content Adds text from a StringBuilder using the specified charset.
AddData Byte array Adds binary data as a new entry.
AddBd BinData content Adds the bytes contained in a BinData object.
AddEncoded Encoded binary data Decodes text such as base64 or hex and stores the resulting bytes as an entry.
AddEmpty Empty file or directory Useful when an empty directory structure must be preserved.

Opening ZIP Archives

Method Source Use When
OpenZip Filesystem path Open a ZIP archive from the local filesystem.
OpenFromMemory In-memory byte array Open ZIP data received from a database, HTTP response, or other memory source.
OpenFromByteData In-memory byte data Open a ZIP archive from byte data.
OpenBd BinData Open a ZIP archive contained in a BinData object.
OpenEmbedded ZIP resource embedded in a Windows EXE Open a ZIP archive packaged as a resource in a Windows executable.
Encryption detection: When a ZIP is opened, properties such as PasswordProtect and Encryption are automatically set when legacy password protection or strong encryption is detected.

Writing ZIP Archives

Method Output Important Details
WriteZip Filesystem ZIP file Saves the ZIP and implicitly re-opens it so further operations can continue. Uses ZIP64 automatically when needed.
WriteZipAndClose Filesystem ZIP file, then closes Saves and closes the ZIP. On return, the object is reset as if NewZip had been called.
WriteToMemory Byte array Writes the ZIP entirely to memory.
WriteBd BinData Writes the ZIP archive to a BinData object.
QuickAppend Existing filesystem ZIP Appends new entries efficiently without rewriting existing entries.
CloseZip No output Closes the currently open ZIP and clears all entries from the object.
Large archive support: WriteZip and WriteZipAndClose use ZIP64 extensions automatically when older ZIP limits are exceeded.

Extraction Methods

Method What It Extracts Path Behavior
Unzip All files and directories Preserves stored paths and creates subdirectories as needed.
UnzipInto All files Extracts into a single directory, ignoring stored path information.
UnzipMatching Entries matching a wildcard pattern Preserves stored paths and creates subdirectories as needed.
UnzipMatchingInto Matching entries Extracts matching files into a single directory, ignoring stored paths.
UnzipNewer Only files that do not exist or are newer than existing files Preserves stored paths and creates subdirectories as needed.
ExtractExe Files from a Chilkat-created self-extracting EXE Extracts into the specified directory.
Return values: Extraction methods such as Unzip, UnzipInto, UnzipMatching, UnzipMatchingInto, and UnzipNewer return the number of files extracted, or -1 on failure.

Path Control When Adding Files

Property / Option Purpose Applies To
AppendFromDir Defines a base directory that is not included in stored ZIP entry paths. Useful with AppendFiles to control relative paths inside the archive.
DiscardPaths Stores only filenames, removing directory path information. Files added from the local filesystem.
PathPrefix Prepends a directory prefix to stored ZIP paths. AppendFiles, AppendFilesEx, AddFile, and AppendOneFileOrDir.
saveExtraPath Controls whether extra leading path information is preserved. AddFile and AppendFilesEx.
In-memory entries: PathPrefix does not affect entries added entirely from memory, such as AddString, AddData, AddBd, or AddSb. For those entries, the ZIP path is determined by the method's path argument.

Finding and Inspecting Entries

Method / Property Purpose Notes
NumEntries Total number of ZIP entries. Includes files and directories.
FileCount Number of file entries. Excludes directory entries.
EntryAt Retrieves the entry at a zero-based index. The first entry is index 0.
EntryOf Finds an entry by exact stored path. Use when the full path in the ZIP is known.
EntryMatching Finds the first entry matching a wildcard pattern. Matching is against the full stored ZIP path.
EntryById Finds an entry by unique EntryID. Useful when a ZipEntry ID is known.
GetDirectoryAsXML Returns the ZIP directory structure as XML. Useful for inspecting contents without extracting files.
GetMaxUncompressedSize Returns the largest uncompressed file size as a decimal string. Useful for estimating disk space or checking unusually large entries.

Encryption and Password Protection

Member Purpose Important Details
Encryption Specifies encryption mode. 0 means no encryption. 4 means WinZip-compatible AES encryption.
EncryptKeyLength AES key length. Valid values are 128, 192, and 256.
EncryptPassword Password used when creating encrypted ZIP archives. Set before writing an encrypted archive.
DecryptPassword Password used to extract encrypted ZIP archives. Encrypted ZIPs can be opened without a password, but encrypted entries cannot be extracted until the correct password is supplied.
PasswordProtect Indicates legacy Zip 2.0 password protection. Automatically set when an opened archive uses legacy password protection.
PwdProtCharset Charset used to convert legacy decrypt passwords to bytes. Applies only to older Zip 2.0 password protection, not AES-encrypted ZIPs.
VerifyPassword Verifies the current decrypt password. Use before extraction to check whether the password is valid.
Mutual exclusion: Encryption and PasswordProtect are mutually exclusive. If PasswordProtect = true, then Encryption should be 0.

Filtering, Exclusions, and Limits

Member Purpose Use When
SetExclusions Sets wildcard exclusion patterns. Skip files matching one or more patterns during add operations.
ExcludeDir Skips recursive directories by name. Exclude directories such as build, cache, or temporary folders.
CaseSensitive Controls filename matching case sensitivity. Affects matching methods such as EntryMatching and UnzipMatching.
MinDate Minimum last-modified timestamp. Skip files older than this date during add or extract operations.
MaxDate Maximum last-modified timestamp. Skip files newer than this date during add or extract operations.
MaxUncompressSize Maximum extracted file size. Prevent extraction of files larger than the specified uncompressed size.
IgnoreAccessDenied Controls behavior for filesystem permission errors. Default is true. When true, files that cannot be read, written, or created due to permissions are skipped.

Compression Options

Member Purpose Guidance
SetCompressionLevel Sets compression level for entries currently in the ZIP object. Use 0 for no compression and 9 for maximum compression. Call after entries are added.
AddNoCompressExtension Adds an extension to the no-compression list. Useful for already-compressed files such as .zip, .jpg, .png, or .gz.
RemoveNoCompressExtension Removes an extension from the no-compression list. After removal, matching files may be compressed normally.
IsNoCompressExtension Checks whether an extension is in the no-compression list. Accepts extensions with or without the leading dot.
Zipx Creates ZIPX archives. When true, uses the most appropriate compression method for each file.
ZipxDefaultAlg Default compression algorithm for ZIPX archives. Possible values include deflate, ppmd, lzma, bzip2, and deflate64.
UncommonOptions Advanced options for uncommon scenarios. ForceZip64 forces ZIP64 format even when not required.
Compression-level timing: SetCompressionLevel should be called after files or data entries have already been added to the ZIP object.

Windows Self-Extracting EXE Support

Chilkat can create Windows self-extracting EXEs containing the ZIP archive and extraction logic. These features are Windows-only and are controlled through WriteExe, WriteExe2, WriteExeToMemory, and related EXE properties.

Category Members Purpose
Create EXE WriteExe, WriteExe2, WriteExeToMemory Create a self-extracting Windows executable.
Auto-run setup AutoRun, AutoRunParams, ExeWaitForSetup Run an executable after extraction and optionally wait for it to finish.
Extraction directory AutoTemp, ExeDefaultDir, ExeUnzipDir Control where the self-extracting EXE extracts files.
User interface ExeTitle, ExeUnzipCaption, ExeNoInterface, ExeSilentProgress, ExeFinishNotifier Configure dialogs, progress UI, captions, and silent behavior.
Advanced configuration ExeXmlConfig, SetExeConfigParam, GetExeConfigParam Configure self-extractor text and behavior using XML or individual params.
Extract existing EXE ExtractExe Extract files from a Chilkat-created self-extracting EXE.
No-interaction setup pattern: For a self-extracting EXE with no user interaction, the reference recommends ExeSilentProgress = false, ExeNoInterface = true, and ExeFinishNotifier = false, often with AutoTemp and AutoRun.

Progress, Abort, and Temporary Files

Property Purpose Guidance
AbortCurrent Stops the currently executing operation. Useful for canceling long-running compression or extraction operations. Can be triggered from another thread.
HeartbeatMs Interval between abort-check callbacks. Default is 0, meaning abort callbacks are disabled.
PercentDoneScale Controls progress callback granularity. Default is 100. Larger values provide finer progress resolution in event-enabled environments.
TempDir Directory used for temporary files. Used during ZIP operations such as overwriting an existing ZIP safely.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected behavior.

Method Summary by Category

Category Members Purpose
Create / open / close NewZip, OpenZip, OpenFromMemory, OpenFromByteData, OpenBd, OpenEmbedded, CloseZip Initialize, open, or close ZIP archives from files, memory, or resources.
Add entries AddFile, AppendFiles, AppendFilesEx, AddString, AddData, AddBd, AddSb, AddEncoded, AddEmpty Add filesystem or in-memory content to the ZIP object.
Find / inspect entries EntryAt, EntryOf, EntryMatching, EntryById, GetDirectoryAsXML, GetMaxUncompressedSize Locate and inspect entries without extracting them.
Remove / merge / append DeleteEntry, QuickAppend, AppendZip Remove entries, append efficiently to existing ZIPs, or append entries from another ZIP.
Write output WriteZip, WriteZipAndClose, WriteToMemory, WriteBd Write the ZIP to disk, memory, or BinData.
Extract Unzip, UnzipInto, UnzipMatching, UnzipMatchingInto, UnzipNewer, ExtractExe Extract all files, selected files, newer files, or self-extracting EXEs.
Encryption Encryption, EncryptKeyLength, EncryptPassword, DecryptPassword, VerifyPassword Create or extract encrypted and password-protected archives.
Self-extracting EXE WriteExe, WriteExe2, WriteExeToMemory, ExeXmlConfig, SetExeConfigParam Create and configure Windows self-extracting executables.
Diagnostics / async LastErrorText, HasZipFormatErrors, LoadTaskCaller Inspect diagnostics, format warnings, and completed async task results.

Diagnostics and Troubleshooting

Problem Area Member What to Check
ZIP is modified in memory but file did not change WriteZip, WriteZipAndClose Add, delete, and append methods update the ZIP object. Call a Write* method to persist the archive.
Stored paths are wrong AppendFromDir, DiscardPaths, PathPrefix, saveExtraPath Review path-control settings before adding files.
Encrypted ZIP opens but extraction fails DecryptPassword, VerifyPassword Encrypted archives may be opened without a password, but entries cannot be extracted until the correct password is supplied.
Unexpected missing files during add or extract SetExclusions, ExcludeDir, MinDate, MaxDate, IgnoreAccessDenied Check exclusion patterns, date filters, and access-denied behavior.
Extraction overwrites files unexpectedly OverwriteExisting, UnzipInto, UnzipMatchingInto UnzipInto and UnzipMatchingInto flatten paths, so duplicate filenames may overwrite earlier extracted files.
Need to avoid oversized extraction MaxUncompressSize, GetMaxUncompressedSize Check or limit uncompressed sizes before extracting.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected open, add, write, extract, encrypt, or self-extracting EXE behavior.

Common Pitfalls

Pitfall Better Approach
Expecting AddFile to immediately read and compress the file. Remember that AddFile adds a reference; file contents are consumed when a Write* method is called.
Forgetting to call a Write* method. Call WriteZip, WriteZipAndClose, WriteBd, or WriteToMemory after changes.
Mixing legacy password protection and AES encryption settings. Use either legacy PasswordProtect behavior or AES Encryption, not both.
Using PathPrefix for in-memory entries. For AddString, AddData, AddBd, and AddSb, pass the desired ZIP path directly to the method.
Calling SetCompressionLevel before adding entries. Call it after entries have already been added to the ZIP object.
Flattening extraction paths without considering duplicate filenames. Be careful with UnzipInto and UnzipMatchingInto, because duplicate filenames may overwrite earlier extracted files.
Ignoring diagnostics after failed operations. Check LastErrorText for details.

Best Practices

Recommendation Reason
Decide path behavior before adding files. AppendFromDir, DiscardPaths, PathPrefix, and saveExtraPath affect stored ZIP paths.
Use WriteZipAndClose when finished with the archive. It writes the ZIP and resets the object to a clean state.
Use WriteToMemory or WriteBd for memory-only workflows. This avoids filesystem output when ZIP data is destined for HTTP, a database, or another in-memory consumer.
Use AES encryption for modern encrypted ZIPs. Set Encryption = 4, EncryptKeyLength, and EncryptPassword.
Use VerifyPassword before extracting encrypted archives. It allows password validation before attempting extraction.
Use no-compress extensions for already-compressed file types. This avoids wasting time compressing data that is unlikely to shrink.
Use MaxUncompressSize for safer extraction policies. It prevents extraction of entries larger than the configured uncompressed size.
Check LastErrorText after failures. It provides useful diagnostic detail for failed or unexpected behavior.

Summary

Chilkat.Zip is a comprehensive ZIP archive class for creating, opening, modifying, writing, and extracting ZIP files. It supports local files, in-memory data, ZIP64, ZIPX, AES encryption, legacy password protection, wildcard matching, filtering, selective extraction, path control, self-extracting Windows EXEs, and detailed diagnostics.

The most important practical guidance is to remember that most add/delete operations modify the ZIP object in memory until a Write* method is called; decide stored path behavior before adding files; use the correct encryption/password settings; validate passwords before extraction when needed; use memory write/open methods for memory-only workflows; and inspect LastErrorText whenever an operation fails or behaves unexpectedly.