DotNetZip.Semverd

Repository archived

This repository was created before System.IO.Compression and the code is unmaintained at this point. Please transition to System.IO.Compression.

Introducing the DotNetZip Library and Tools

DotNetZip is the name of an open-source project that delivers a .NET library for handling ZIP files, and some associated tools.

• The library allows .NET programmers to build applications that read, create and modify ZIP files.

• The tools are .NET programs that rely on the library, and can be used by anyone on any Windows machine to build or extract ZIP files.

How to build?

bundle && rake

CI: https://ci.appveyor.com/project/haf/dotnetzip-semverd

Why DotNetZip?

The Microsoft .NET Framework base class library lacks a good set of built-in classes for creating and reading ZIP files, and Windows itself lacks full-powered built-in ZIP tools. DotNetZip fills those needs.

There are other ZIP libraries available, but some of them have licenses that may be unfriendly, some of them are too hard to use or not powerful enough, and some of them are too expensive (not free). DotNetZip provides one more alternative. The goals for this alternative:

• easy to adopt - low cost (Free), and a friendly license
• fully-featured
• good performance - in speed and compression
• easy to use.

DotNetZip background

Many people seem to think, incorrectly, that the classes in the System.IO.Compression namespace, like GZipStream or DeflateStream, can create or read zip files. Not true.

The System.IO.Compression namespace, available starting with .NET v2.0 for the desktop Framework and v3.5 for the Compact Framework, includes base class libraries supporting compression within streams - both the Deflate and Gzip formats are supported. But these classes are not directly useful for creating compressed ZIP archives. GZIP is not ZIP. Deflate is not ZIP. The GZipStream in System.IO.Compression is able to read and write GZIP streams, but that is not the same as reading or writing a zip file. Also, these classes deliver poor compression in practice, especially with binary data, or previously-compressed data.

Yes, it is possible to read and write zip files, using the classes in the .NET Framework.

• You can do it with the System.IO.Packaging.ZipPackage class, added in .NET v3.0. Actually this class lets you create a package file, which is a zipfile with a particular internal structure. It includes a manifest and some other things. But the interface is odd and confusing if all you want is a regular-old ZIP file. Also, the classes in this namespace do not provide control for things like passwords, comments, AES encryption, ZIP64, Unicode, and so on.

• You can also create and read zip files with the J# runtime. This also has its drawbacks. First, J# is going out of support, or may be out of support now. Second, the J# runtime is huge, and you have to swallow the whole thing, even if all you want is zip file capability. Also, the J# runtime is based on the java.util.zip classes from Java v1.4, dating from 1998. The runtime hasn't been updated in years and still includes bugs in zip file handling. It lacks support for AES, for ZIP64, and Unicode. It is not accessible from COM. Finally, the zip classes in the J# runtime are decidedly un-dotnet. There's no support for events, or enumerators to let you do things like For Each in VB, or foreach in C#. The interface is clunky. It does not feel like a .NET class library, because it isn't a .NET class library. So for all those reasons, J# isn't ideal.

• You can also rely on P/Invoke to the shell32.dll, and the ShellClass. This works in a limited fashion. The drawbacks here: it isn't documented. It isn't a very intuitive or powerful programming interface. There are no events, so embedding it into a Winforms app with a progress bar would be difficult. Again it lacks an easy way to use or access many ZIP features, like encryption or ZIP64 or self-extracting archives. Also, the shell32.dll is designed for use within Windows Explorer, and presumes a user interface. In fact in some cases, calling into this DLL to perform a ZIP extraction can display a dialog box, so it may not be suitable for use within server or "headless" applications.

There are other libraries out there than do zip files for .NET. But there are compromises with each one. Some are commercial and expensive. Some are slow. Some are complicated to use. Some of these options lack features. Some of them have more than one of these drawbacks.

DotNetZip provides another option. It's a very simple-to-use class library that provides good ZIP file support. Using this library, you can write .NET applications that read and write zip-format files, including files with passwords, Unicode filenames, ZIP64, AES encryption, and comments. The library also supports self-extracting archives. It is well documented and provides good performance.

Though DotNetZip is implemented in .NET and was originally intended to provide a managed-code library for ZIP files, you can now use it library from any COM environment, including Javascript, VBScript, VB6, VBA, PHP, Perl, and others. Using DotNetZip, you could generate an AES-encrypted zip file from within the code of a macro running in MS-Excel, for example.

DotNetZip works with applications running on PCs with Windows. There is a version of this library available for the .NET Compact Framework, too.

I have not tested DotNetZip for use with Mono, but I've heard reports that people use the binary releases with Mono successfully, without change.

License

This software is open source. It is released under the Microsoft Public License of October 2006. The use of the "Microsoft Public License" does not mean it is licensed by Microsoft. See the License.txt file for details.

DotNetZip is derived in part from ZLIB, the C-language library by Mark Adler and Jean-loup Gailly . See the License.ZLIB.txt file included in the DotNetZip download for details.

What is DotNetZip? and How is it packaged?

DotNetZip is primarily a managed library for dealing with ZIP files.

It is packaged as a DLL that your application must reference: Ionic.Zip.dll. In the "developer's kit" package, there is documentation, code examples, and debug versions of the DLL.

The ZIP library depends on a set of supporting classes for doing compression and decompression; these are exposed in other namespaces.

The classes in the ZIP library reside in these namespaces:

namespace interesting classes

Ionic.Zip ZipFile, ZipEntry, ZipOutputStream, and ZipInputStream.

Ionic.Zlib DeflateStream, GZipStream, ZlibStream

Ionic.BZip2 BZip2InputStream, BZip2OutputStream

Ionic.Crc CRC32

If you want only ZLIB (raw compression and decompression, RFC 1950, 1951, and 1952), the ZLIB classes are packaged independently, in Ionic.Zlib.dll. Likewise, if you want to do BZIP2 compression, outside the scope of a zip file, you can use the Ionic.BZip2.dll assembly.

If you want ZIP, or both ZIP and ZLIB, then your application should depend soly on Ionic.Zip.dll; this assembly includes a superset of the classes in Ionic.Zlib.dll and Ionic.BZip2.dll.

For each DLL, there is a version for the regular .NET Framework and another for the Compact Framework.

DotNetZip also includes command-line and GUI tools for manipulating zip files; these can be helpful to developers when building applications that create or manipulate zip files. They also can be helpful as end-user tools.

There are other downloads for DotNetZip - the source package, the runtime-only package (DLLs and no helpfile or tools), the documentation-only package, etc.

Using the Zip Class Library: The Basics

The examples here provide just the basics.

There are many other examples available: some are included in the source package, some in the class reference documentation in the help file, and others on the web. Those examples provide many illustrate how to read and write zip files, taking advantage of all the various features of zip files exposed by the library. For a full set of examples, your best bet is to see the documentation. Here's a basic primer:

The main type you will use to fiddle with zip files is the ZipFile class. Full name: Ionic.Zip.ZipFile. You use this to create, read, or update zip files. There is also a ZipOutputStream class, which offers a Stream metaphor, for those who want it. You should choose one or the other for your application.

The simplest way to create a ZIP file in C# looks like this:

  using(ZipFile zip= new ZipFile())
  {
    zip.AddFile(filename);
    zip.Save(NameOfZipFileTocreate);
  }

Or in VB.NET, like this:

 Using zip As ZipFile = New ZipFile
     zip.AddFile(filename)
     zip.Save("MyZipFile.zip")
 End Using

The using clause is important; don't leave it out.

The simplest way to Extract all the entries from a zipfile looks like this:

  using (ZipFile zip = ZipFile.Read(NameOfExistingZipFile))
  {
    zip.ExtractAll(args[1]);
  }

But you could also do something like this:

  using (ZipFile zip = ZipFile.Read(NameOfExistingZipFile))
  {
    foreach (ZipEntry e in zip)
    {
      e.Extract();
    }
  }

Or in VB, extraction w