Programming with the Xceed Zip Class Library

Introduction

This section of the manual is designed to show you how to program using the Xceed Zip class library once you have read the Introduction to the Xceed.Zip namespace topic. If you only need basic zip file operations, jump to the Programming with the QuickZip Class topic.

Topics

  • Copying items to a zipped folder

  • Listing the contents of a zipped folder

  • Removing items from a zipped folder

  • Encryption and decryption

  • Optimizing batch updates to a zipped folder

  • Handling exceptions

  • Case sensitivity

  • Handling events

  • Using filters


Copying items to a zipped folder

Introduction

This topic demonstrates how to add files and folders to a zipped folder. A zipped folder is a folder contained within a zip file and is represented by a ZippedFolder object.

Basic steps

To copy items to a zipped folder, the following steps must be performed:

  • Create a reference to a class that derives from the AbstractFolder class.

  • Call the CopyFilesTo method to copy the entire contents of the folder to the zipped folder. This method requires a AbstractFolder object as a parameter therefore, we create an instance of the ZipArchive object directly in the method call. Creating a ZipArchive object also requires you to create a reference to a DiskFile object. In this case, we created the DiskFile object directly in the constructor of the ZipArchive class.

C# demonstration

This example assumes that you are in a console application.

using Xceed.Zip;

using Xceed.FileSystem;

DiskFolder diskFolder = new DiskFolder( @"c:\temp" );

diskFolder.CopyFilesTo( new ZipArchive( new DiskFile( @"c:\test.zip" ) ), true, true );

VB.NET demonstration

This example assumes that you are in a Windows application.

Imports Xceed.Zip

Imports Xceed.FileSystem

Dim diskFolder As New DiskFolder( "c:\temp" )

diskFolder.CopyFilesTo( New ZipArchive( New DiskFile( "c:\test.zip" ) ), True, True )

Things you should consider

The main questions you should ask yourself when copying items to a zipped folder are:

  • Do you want to display the status of the operation? See the Handling events topic.

  • Do you want to add items into a specific folder within the zip file? Create an instance of a ZippedFolder object rather than a ZipArchive object.

  • Do you only want to copy a specific file or folder? Use the CopyTo method.

  • Do you only want to do basic zip file operations? Use the QuickZip class rather than the class library.


Listing the contents of a zipped folder

Introduction

This topic demonstrates how to get a listing of all of the files contained in a zipped folder. A zipped folder is a folder contained within a zip file and is represented by a ZippedFolder object.

Basic steps

To list the contents of a zipped folder, the following steps must be performed:

  • Create a reference to a ZipArchive object. Creating a ZipArchive object also requires you to create a reference to a DiskFile object. In this case, we created the DiskFile object directly in the constructor of the ZipArchive class.

  • Call the GetFiles method of the newly created ZipArchive object which will return an array of AbstractFile objects.

  • You can now loop through the array of files and extract the desired information. For the purposes of this example, we will only retrieve the complete name of the file.

C# demonstration

This example assumes that you are in a console application.

using Xceed.Zip;

using Xceed.FileSystem;

ZipArchive zip = new ZipArchive( new DiskFile( @"c:\test.zip" ) );

foreach( AbstractFile f in zip.GetFiles( true ) )

{

Console.WriteLine( f.FullName );

}

VB.NET demonstration

This example assumes that you are in a Windows application and that you have a listbox on the form.

Imports Xceed.Zip

Imports Xceed.FileSystem

Dim zip As New ZipArchive( New DiskFile( "c:\test.zip" ) )

Dim f As AbstractFile

For Each f In zip.GetFiles( True )

ListBox1.Items.Add( f.FullName )

Next

Things you should consider

The main questions you should ask yourself when listing the contents of a zipped folder are:

  • Do you also want to retrieve a listing of the zipped folders? Use the GetFolders method.

  • Do you want to retrieve a reference to a single zipped file or folder? Use the GetFile or GetFolder methods.

  • Do you want to display the status of the operation? See the Handling events topic.

  • Do you want to list the contents of a specific folder within the zip file? Create an instance of a ZippedFolder object rather than a ZipArchive object.

  • Do you want to filter your list of items? See the Using filters topic.

  • Do you only want to do basic zip file operations? Use the QuickZip class rather than the class library.


Removing items from a zipped folder

Introduction

This topic demonstrates how to remove items from a folder by retrieving a reference to a file within a zip file.

Basic steps

To remove an item from a zipped folder, the following steps must be performed:

  • Create a reference to a ZippedFile object. Creating a ZippedFile object also requires you to create a reference to a DiskFile object. In this case, we created the DiskFile object directly in the constructor of the ZippedFile class.

  • Once we have a reference to a ZippedFile object we verify the Exists property to make sure that the file actually exists.

  • Call the Delete method to delete the file.

C# demonstration

This example assumes that you are in a console application.

using Xceed.Zip;

using Xceed.FileSystem;

ZippedFile f = new ZippedFile( new DiskFile( @"c:\test.zip" ), @"file.txt" );

if( f.Exists )

{

f.Delete();

}

VB.NET demonstration

This example assumes that you are in a Windows application.

Imports Xceed.Zip

Imports Xceed.Disk

Dim f As New ZippedFile( New DiskFile( "c:\test.zip" ), "file.txt" )

If f.Exists Then

f.Delete()

End If

Things you should consider

The main questions you should ask yourself when removing items from a zipped folder are:

  • Do you want to display the status of the operation? See the Handling events topic.

  • Do you want to remove a specific folder? Create an instance of a ZippedFolder object rather than a ZippedFile object

  • Do you already have a reference on a folder? Use the GetFolder or GetFile method to retrieve a reference on the file or folder to remove.

  • Do you only want to do basic zip file operations? Use the QuickZip class rather than the class library.


Encryption and decryption

Introduction

The zip format supports a light encryption algorithm which uses a string password to encrypt it's data. This type of encryption can resist attacks by amateurs if the password is well chosen and long enough (at least 16 characters, maximum of 80) but it will probably not resist attacks by determined users or experts. Therefore, we suggest that you always use long passwords, and when possible, do not rely solely on this encryption system to protect sensitive data.

Encrypting files

In order to encrypt files you are copying to a zip file, the DefaultEncryptionPassword property of the corresponding ZipArchive object must be set. The ZipArchive class represents both the root folder of a zip file as well as the zip file itself. A reference on the corresponding ZipArchive object can be obtained using the RootFolder property of any ZippedFile or ZippedFolder object.

When files are added to the zip file, the DefaultEncryptionPassword property of the ZipArchive object is consulted and the password that is assigned to this property is used to encrypt the files. If the DefaultEncryptionPassword property is not set, then the files are not encrypted.

Decrypting files

In order to decrypt files you are extracting from a zip file, the DefaultDecryptionPassword property of the corresponding ZipArchive object must be set. The ZipArchive class represents both the root of a zip file as well as the zip file itself. A reference on the corresponding ZipArchive object can be obtained by using the RootFolder property of any ZippedFile or ZippedFolder object.

When extracting encrypted files, the DefaultDecryptionPassword property of the ZipArchive object is consulted and the password that is assigned to this property is used to decrypt the files. In the case where you are trying to extract an encrypted file without setting the DefaultDecryptionPassword of the ZipArchive object or with an invalid password, an exception will be thrown. In order to handle the exception and provide a new password, jump to the Handling exceptions topic.

Accessing the contents of an encrypted ZippedFile object

In order to access the contents of an encrypted ZippedFile object, an overload of the OpenWrite or OpenRead methods that takes a password as a parameter must be used.

Open an instance of a ZippedFile object for reading:

using Xceed.FileSystem;

using Xceed.Zip;

using Xceed.Compression;

using System.IO;

ZippedFile file = new ZippedFile( new DiskFile( @"c:\test.zip" ), @"file.txt" );

Stream s = file.OpenRead( FileShare.Read, "password" );

You can also use the default encryption password specified in the DefaultDecryptionPassword property of the corresponding ZipArchive object:

ZippedFile file = new ZippedFile( new DiskFile( @"c:\test.zip" ), @"file.txt" );

ZipArchive archive = ( ZipArchive )file.RootFolder;

Stream s = file.OpenRead( FileShare.Read, archive.DefaultDecryptionPassword );

Open an instance of a ZippedFile object for writing:

ZippedFile file = new ZippedFile( new DiskFile( @"c:\test.zip" ), @"file.txt" );

Stream s = file.OpenWrite( FileShare.Write, CompressionMethod.Deflated,

CompressionLevel.Normal, "password" );

You can also use the default compression method and level as well as the default encryption password of the corresponding ZipArchive object:

ZippedFile file = new ZippedFile( new DiskFile( @"c:\test.zip" ), @"file.txt" );

ZipArchive archive = ( ZipArchive )file.RootFolder;

archive.DefaultEncryptionPassword = "password";

Stream s = file.OpenWrite( FileShare.Write, archive.DefaultCompressionMethod,

archive.DefaultCompressionLevel, archive.DefaultEncryptionPassword );


Exceptions

Xceed.Zip Namespace

Handling exceptions

Introduction

An exception is any error condition or unexpected behavior encountered by an executing program. Whenever an error occurs, an Exception object is created to represent the exception.

Handling exceptions.

The exceptions that can be thrown by the Xceed.Zip namespace, are handled in the same manner as regular run-time exceptions using Try/Catch blocks. It is possible to intercept the exceptions before they are thrown using the ItemException event in order to try and recover from the exception before it is actually thrown.

The following table provides a listing of all the exceptions that can be thrown when an error occurs within the Xceed.Zip namespace:

Exception | Description
InvalidDecryptionPasswordException | Exception that is thrown when the data could not be decrypted with the supplied decryption password.
InvalidZipStructureException | Exception that is thrown when the internal structure of a ZIP file is invalid.
ZipException | Exception that is thrown when an error occurs in the Xceed.Zip namespace.
ZipIOException | Exception that is thrown when an IO exception occurs while reading from or writing to the ZIP file.

The ZipException class derives directly from the FileSystemException class. All of the other exception classes defined within the Xceed.Zip namespace derive from the ZipException class.

For more information regarding the exception classes native to the Xceed.FileSystem namespace, please refer to the Handling exceptions topic of this namespace.

C# demonstration

The following example demonstrates how to use a Try/Catch statement when calling the Delete method on a ZippedFile that is contained within a corrupted zip file:

try

{

ZippedFile f = new ZippedFile( new DiskFile( @"c:\test.zip" ), @"\file.txt" );

f.Delete();

}

catch( ZipException err )

{

Console.WriteLine( err.Message );

}

VB.NET demonstration

The following example demonstrates how to use a Try/Catch statement when calling the Delete method on a ZippedFile that is contained within a corrupted zip file:

Try

Dim f As New ZippedFile( New DiskFile( "c:\test.zip" ), "\file.txt" )

f.Delete()

Catch err As ZipException

ListBox1.Items.Add( err.Message )

End Try

Things you should consider

The main questions you should ask yourself when handling exceptions are:

  • Do you want to intercept the exceptions before they are thrown? See the ItemException event topic.


Handling events

Introduction

An event is a message raised by an object to signal the occurrence of an action. In order to receive event notifications, a caller must subscribe to the desired events.

The Xceed.Zip namespace defines four events that provide information about the status of an operation that deals with zip files. These events are the BuildingZipByteProgression event which is raised when the temporary zip file is being built, the BuildingZipItemProgression event which is raised each time a temporary file is about to be added to the temporary zip file, the ReadingZipItemProgression event which is raised is raised whenever an item in a zipped folder is about to be read, and the CopyingZipByteProgression event which is raised when the temporary zip file is written over an existing zip file. All these events are accessed through the ZipEvents class which is the class that dispatches the events that are raised to the subscribed callers.

Keep in mind that you should subscribe only to the necessary events to prevent a reduction in performance.

ZipEvents class

The ZipEvents class dispatches the events that are raised to the callers that are subscribed to receive event notifications. If you want to call a method and receive it's event notifications, it is important to use the method overload that takes a ZipEvents object as a parameter.

The BuildingZipByteProgressionEventHandler, BuildingZipItemProgressionEventHandler, ReadingZipItemProgressionEventHandler and the CopyingZipByteProgressionEventHandler classes are all delegate classes that are used to subscribe to the corresponding events. To subscribe to an event, a new instance of the appropriate delegate class must be created and assigned to the corresponding event of the ZipEvents object. In the constructor of the delegate class, we pass the name of the method that will handle the events raised by the event of the ZipEvents object we are subscribing to.

ZipEvents zEvents = new ZipEvents();

zEvents.CopyingZipByteProgression += new CopyingZipByteProgressionEsventHandler( OnCopyingZipByteProgression );

The following diagram represents the relationship between the event handlers and subscribers:

Keep in mind that since the ZipEvents class derives from the FileSystemEvents class, it is also possible to subscribe to the events that the FileSystem class implements. For more information regarding the events that are implemented within the Xceed.FileSystem namespace, please refer to the Handling events topic of this section.

FileSystemEventArgs class

The FileSystemEventArgs class is the root class for the classes that contain event data. The classes that derive from the FileSystemEventArgs class and are passed to the event handlers are the ByteProgressionEventArgs, ItemProgresssionEventArgs, ItemExceptionEventArgs and the ScanningFolderEventArgs classes.

The declaration of the event handler must have the same parameters as the EventHandler delegate declaration. The first parameter is the source of the event and the second is one of the classes that derive from the FileSystemEventArgs class.

public void OnBuildingZipByteProgression( object sender, ByteProgressionEventArgs e )

The following diagram represents the hierarchy of the FileSystemEventArgs classes:


BuildingZipByteProgression event

Introduction

The BuildingZipByteProgression event is raised when the temporary zip file is being built from the temporary files, for every 64 bytes processed.

Keep in mind that using the BuildingZipByteProgression event increases the time it takes to process the temporary files. The reason behind this is that the data associated with the file will be scanned twice. The first time the files are scanned, information regarding the files will be accumulated ( filename, size, etc.. ). This is to allow accurate progress information to be returned during the actual processing of the files.

Purpose

The main purpose of the BuildingZipByteProgression event is to provide feedback to the user during the process of moving the temporary files to the temporary zip file to prevent the application from appearing frozen.

Basic steps - C#

To subscribe to the BuildingZipByteProgression event, the following steps must be performed:

  • Create a reference to a ZipEvents object.

  • Subscribe to the BuildingZipByteProgression event of the ZipEvents object using the BuildingZipByteProgressionEventHandler delegate class.

  • Create a new method that will handle the events that are raised. For the purposes of this example, we will call the method OnBuildingZipByteProgression.

  • Place the desired code in the newly created event handler.

Basic steps - VB.NET

To subscribe to the BuildingZipByteProgression event, the following steps must be performed:

  • Create a reference to a ZipEvents object using the WithEvents keyword.

  • Select the BuildingZipByteProgression event from the list of available methods in the newly instantiated ZipEvents object. This is done in the same manner as, for example, adding the DoubleClick event of a ListBox.

  • Place the desired code in the newly added event handler.

C# demonstration

This example assumes that you are in a console application.

using Xceed.Zip;

using Xceed.FileSystem;

ZipEvents zEvents = new ZipEvents();

zEvents.BuildingZipByteProgression += new BuildingZipByteProgressionEventHandler( OnBuildingZipByteProgression );

ZippedFolder folder = new ZippedFolder( new DiskFile( @"c:\test.zip" ), @"\folder" );

folder.Delete( zEvents, null );

//This method will handle the BuildingZipByteProgression events that are raised.

public static void OnBuildingZipByteProgression( object sender, ByteProgressionEventArgs e )

{

Console.WriteLine( "Processed {0} bytes of {1} on {2}.",

e.CurrentFileBytes.Processed,

e.CurrentFileBytes.Total,

e.CurrentItem.Name );

}

//If you no longer wish to handle the events that are raised,

//you can unsubscribe from the event notifications by doing the following:

zEvents.BuildingZipByteProgression -= new BuildingZipByteProgressionEventHandler( OnBuildingZipByteProgression );

VB.NET demonstration

This example assumes that you are in a Windows application and that you have a listbox on the form.

Imports Xceed.Zip

Imports Xceed.FileSystem

Dim WithEvents zEvents As New ZipEvents()

Dim folder As New ZippedFolder( New DiskFile( "c:\test.zip" ), "\folder" )

folder.Delete( zEvents, Nothing )

Private Sub zEvents_BuildingZipByteProgression( ByVal sender As Object,

ByVal e As Xceed.FileSystem.ByteProgressionEventArgs )

Handles zEvents.BuildingZipByteProgression

ListBox1.Items.Add( "Processed " + e.CurrentFileBytes.Processed + _

" bytes of " + e.CurrentFileBytes.Total + _

" on " + e.CurrentItem.Name )

End Sub


BuildingZipItemProgression event

Introduction

The BuildingZipItemProgression event is raised each time a temporary file is about to be added to the temporary zip file.

Keep in mind that using the BuildingZipItemProgression event increases the time it takes to process the temporary files. The reason behind this is that the data will be scanned twice. The first time the files are scanned, information regarding the files will be accumulated ( filename, size, etc.. ). This is to allow accurate progress information to be returned during the second run.

Purpose

The main purpose of the BuildingZipItemProgression event is to provide feedback to the user during the process of moving the temporary files to the temporary zip file to prevent the application from appearing frozen.

Basic steps - C#

To subscribe to the BuildingZipItemProgression event, the following steps must be performed:

  • Create a reference to a ZipEvents object.

  • Subscribe to the BuildingZipItemProgression event of the ZipEvents object using the BuildingZipItemProgressionEventHandler delegate class.

  • Create a new method that will handle the events that are raised. For the purposes of this example, we will call the method OnBuildingZipItemProgression.

  • Place the desired code in the newly created event handler.

Basic steps - VB.NET

To subscribe to the BuildingZipItemProgression event, the following steps must be performed:

  • Create a reference to a ZipEvents object using the WithEvents keyword.

  • Select the BuildingZipItemProgression event from the list of available methods in the newly instantiated ZipEvents object. This is done in the same manner as, for example, adding the DoubleClick event of a ListBox.

  • Place the desired code in the newly added event handler.

C# demonstration

This example assumes that you are in a console application.

using Xceed.Zip;

using Xceed.FileSystem;

ZipEvents zEvents = new ZipEvents();

zEvents.BuildingZipItemProgression += new BuildingZipItemProgressionEventHandler( OnBuildingZipItemProgression );

ZippedFolder folder = new ZippedFolder( new DiskFile( @"c:\test.zip" ), "\folder" );

folder.Delete( zEvents, null );

//This method will handle the BuildingZipItemProgression events that are raised.

public static void OnBuildingZipItemProgression( object sender, ItemProgressionEventArgs e )

{

Console.WriteLine( "Processed {0} bytes of {1} on {2}.",

e.AllItems.Processed,

e.AllItems.Total,

e.CurrentItem.Name );

}

//If you no longer wish to handle the events that are raised,

//you can unsubscribe from the event notifications by doing the following:

zEvents.BuildingZipItemProgression -= new BuildingZipItemProgressionEventHandler( OnBuildingZipItemProgression );

VB.NET demonstration

This example assumes that you are in a Windows application and that you have a listbox on the form.

Imports Xceed.Zip

Imports Xceed.FileSystem

Dim WithEvents zEvents As New ZipEvents()

Dim folder As New ZippedFolder( New DiskFile( "c:\test.zip" ), "\folder" )

folder.Delete( zEvents, Nothing )

Private Sub zEvents_BuildingZipItemProgression( ByVal sender As Object,

ByVal e As Xceed.FileSystem.ItemProgressionEventArgs )

Handles zEvents.BuildingZipItemProgression

ListBox1.Items.Add( "Processed " + e.AllItems.Processed + _

" bytes of " + e.AllItems.Total + _

" on " + e.CurrentItem.Name )

End Sub


ReadingZipItemProgression event

Introduction

The ReadingZipItemProgression event is raised whenever an item in a zipped folder is about to be read.

Purpose

When reading the central directory of large zip file, your application can appear to be frozen. The ReadingZipItemProgression event allows you to provide feedback to your user during this possibly lengthy operation.

Basic steps - C#

To subscribe to the ReadingZipItemProgression event, the following steps must be performed:

  • Create a reference to a ZipEvents object.

  • Subscribe to the ReadingZipItemProgression event of the ZipEvents object using the ReadingZipItemProgressionEventHandler delegate class.

  • Create a new method that will handle the events that are raised. For the purposes of this example, we will call the method OnReadingZipItemProgression.

  • Place the desired code in the newly created event handler.

Basic steps - VB.NET

To subscribe to the ReadingZipItemProgression event, the following steps must be performed:

  • Create a reference to a ZipEvents object using the WithEvents keyword.

  • Select the ReadingZipItemProgression event from the list of available methods in the newly instantiated ZipEvents object. This is done in the same manner as, for example, adding the DoubleClick event of a ListBox.

  • Place the desired code in the newly added event handler.

C# demonstration

This example assumes that you are in a console application.

using Xceed.Zip;

using Xceed.FileSystem;

ZipEvents zEvents = new ZipEvents();

zEvents.ReadingZipItemProgression += new ReadingZipItemProgressionEventHandler( OnReadingZipItemProgression );

ZippedFolder folder = new ZippedFolder( new DiskFile( @"c:\test.zip" ), "\folder" );

folder.Delete( zEvents, null );

//This method will handle the ReadingZipItemProgression events that are raised.

public void OnReadingZipItemProgression( object sender, ItemProgressionEventArgs e )

{

Console.WriteLine( "Processed {0} bytes of {1} on {2}.",

e.AllItems.Processed,

e.AllItems.Total,

e.CurrentItem.Name );

}

//If you no longer wish to handle the events that are raised,

//you can unsubscribe from the event notifications by doing the following:

zEvents.ReadingZipItemProgression -= new ReadingZipItemProgressionEventHandler( OnReadingZipItemProgression );

VB.NET demonstration

This example assumes that you are in a Windows application and that you have a listbox on the form.

Imports Xceed.Zip

Imports Xceed.FileSystem

Dim WithEvents zEvents As New ZipEvents()

Dim folder As New ZippedFolder( New DiskFile( "c:\test.zip" ), "\folder" )

folder.Delete( zEvents, Nothing )

Private Sub zEvents_ReadingZipItemProgression( ByVal sender As Object,

ByVal e As Xceed.FileSystem.ItemProgressionEventArgs )

Handles zEvents.ReadingZipItemProgression

ListBox1.Items.Add( "Processed " + e.AllItems.Processed + _

" bytes of " + e.AllItems.Total + _

" on " + e.CurrentItem.Name )

End Sub


CopyingZipByteProgression event

Introduction

The CopyingZipByteProgression event is raised when the temporary zip file is written over the existing zip file. Keep in mind that this event will not always be raised. In some cases, like when there is no existing zip file, this event will not be raised.

Purpose

When the temporary zip file is written over the existing zip file, your application can appear to be frozen. The CopyingZipByteProgression event allows you to provide feedback to your user during this possibly lengthy operation.

Basic steps - C#

To subscribe to the CopyingZipByteProgression event, the following steps must be performed:

  • Create a reference to a ZipEvents object.

  • Subscribe to the CopyingZipByteProgression event of the ZipEvents object using the CopyingZipByteProgressionEventHandler delegate class.

  • Create a new method that will handle the events that are raised. For the purposes of this example, we will call the method OnCopyingZipByteProgression.

  • Place the desired code in the newly created event handler.

Basic steps - VB.NET

To subscribe to the CopyingZipByteProgression event, the following steps must be performed:

  • Create a reference to a ZipEvents object using the WithEvents keyword.

  • Select the CopyingZipByteProgression event from the list of available methods in the newly instantiated ZipEvents object. This is done in the same manner as, for example, adding the DoubleClick event of a ListBox.

  • Place the desired code in the newly added event handler.

C# demonstration

This example assumes that you are in a console application.

using Xceed.Zip;

using Xceed.FileSystem;

ZipEvents zEvents = new ZipEvents();

zEvents.CopyingZipByteProgression += new CopyingZipByteProgressionEventHandler( OnCopyingZipByteProgression );

ZippedFolder folder = new ZippedFolder( new DiskFile( @"c:\test.zip" ), @"\folder" );

folder.Delete( zEvents, null );

//This method will handle the CopyingZipByteProgression events that are raised.

public void OnCopyingZipByteProgression( object sender, ByteProgressionEventArgs e )

{

Console.WriteLine( "Processed {0} bytes of {1} on {2}.",

e.CurrentFileBytes.Processed,

e.CurrentFileBytes.Total,

e.CurrentItem.Name );

}

//If you no longer wish to handle the events that are raised,

//you can unsubscribe from the event notifications by doing the following:

zEvents.CopyingZipByteProgression -= new CopyingZipByteProgressionEventHandler( OnCopyingZipByteProgression );

VB.NET demonstration

This example assumes that you are in a Windows application and that you have a listbox on the form.

Imports Xceed.Zip

Imports Xceed.FileSystem

Dim WithEvents zEvents As New ZipEvents()

Dim folder As New ZippedFolder( New DiskFile( "c:\test.zip" ), "\folder" )

folder.Delete( zEvents, Nothing )

Private Sub zEvents_CopyingZipByteProgression( ByVal sender As Object,

ByVal e As Xceed.FileSystem.ByteProgressionEventArgs )

Handles zEvents.CopyingZipByteProgression

ListBox1.Items.Add( "Processed " + e.CurrentFileBytes.Processed + _

" bytes of " + e.CurrentFileBytes.Total + _

" on " + e.CurrentItem.Name )

End Sub


Programming with the QuickZip Class

Introduction

This section of the manual has but one goal: To show you, as fast as possible, how to start programming using the QuickZip class

The QuickZip class exposes static methods that allow quick and easy zip file operations. For more complex zip file operations, including the use of events, jump to the Programming with the Xceed Zip Class library topic.

If all else fails, use the "search" feature of the manual, or browse the sample applications. Feel free to contact Xceed Software at any time if you have questions.

Topics

  • Adding files to a zip file

  • Extracting files from a zip file

  • Listing the contents of a zip file

  • Removing files from a zip file

  • Handling exceptions


Adding files to a zip file

Introduction

This topic demonstrates how to add files to a zip file.

Examples

The Zip method has three overloads that can be used. The first overload only requires the path and file name of the zip file to add files to, as well as the path and name or filemask of the files to add to the zip file. Note that existing files will be replaced, files in sub-folders will be processed and the directory structure will be preserved within the zip file.

C# - Xceed.Zip.QuickZip.Zip( @"c:\test.zip", @"c:\temp\*" );

VB.NET - Xceed.Zip.QuickZip.Zip( "c:\test.zip", "c:\temp\*" )

With the second overload of the Zip method, you can specify whether or not you want to replace existing files, process files in sub-folders as well as preserve the directory structure in the zip file. This is done by setting the replaceExistingFiles, recursive and preservePaths parameters.

C# - Xceed.Zip.QuickZip.Zip( @"c:\test.zip", true, true, true, @"c:\temp\*" );

VB.NET - Xceed.Zip.QuickZip.Zip( "c:\test.zip", true, true, true, "c:\temp\*" )

The third overload of the Zip method, provides all the same options as the previous overloads as well as provides the opportunity to encrypt the files that are added to the zip file by setting the encryptionPassword parameter.

C# - Xceed.Zip.QuickZip.Zip( @"c:\test.zip", "password", true, true, true, @"c:\temp\*" );

VB.NET - Xceed.Zip.QuickZip.Zip( "c:\test.zip", "password", true, true, true, "c:\temp\*" )

Remarks

When using the first overload of the Zip method or when using one of the other two overloads with the recursive parameter set to true, you have to consider every filename you place in the filesToZip parameter as a filemask. For example, if you set the filesToZip parameter to "c:\file.txt", the entire "c:\" drive will be scanned and all the files that are named "file.txt" that are found will be included in the zip file.

Note that the filesToZip parameter of the Zip method cannot be null otherwise an ArgumentNullException exception will be thrown.

Things you should consider

The main questions you should ask yourself when adding files to a zip file are:

  • Do you want to do more complex zip file operations? Use the class library rather than the QuickZip class.


Extracting files from a zip file

Introduction

This topic demonstrates how to extract files from a zip file.

Examples

The Unzip method has three overloads that can be used. The first overload only requires the path and file name of the zip file, the destination folder to where the files will be extracted and the path and name or filemask of the files to extract. Note that existing files will be replaced, files in sub-folders will be processed and the directory structure will be restored in the destination folder.

C# - Xceed.Zip.QuickZip.Unzip( @"c:\test.zip", @"c:\temp", @"*" );

VB.NET - Xceed.Zip.QuickZip.Unzip( "c:\test.zip", "c:\temp", "*" )

With the second overload of the Unzip method, you can specify whether or not you want to replace existing files, process files in sub-folders as well as restore the directory structure by setting the replaceExistingFiles, recursive and preservePaths parameters.

C# - Xceed.Zip.QuickZip.Unzip( @"c:\test.zip", @"c:\temp", true, true, true, @"*" );

VB.NET - Xceed.Zip.QuickZip.Unzip( "c:\test.zip", "c:\temp", true, true, true, "*" )

The last overload of the Unzip method, provides all the same options as the previous overloads as well as provides the opportunity to provide a password to decrypt the files that are extracted from the zip file by setting the decryptionPassword parameter.

C# - Xceed.Zip.QuickZip.Unzip( @"c:\test.zip", @"c:\temp", "password", true, true, true, @"*" );

VB.NET - Xceed.Zip.QuickZip.Unzip( "c:\test.zip", "c:\temp", "password", true, true, true, "*" )

Handling paths

When extracting files from within a zip file, the directory structure can be restored fully or partially or it can be omitted altogether.

If the preservePaths parameter of the Unzip method is set to false, the files specified in the filesToUnzip parameter will be restored directly into the root of the destination folder without recreating the directory structure.

For example, if you have a zip file containing files in the "folder1" subfolder and files in the "folder1\folder2" subfolder, the following code will unzip all files right into "c:\temp", without creating any subfolders:

Xceed.Zip.QuickZip.Unzip( @"c:\test.zip", @"c:\temp", true, true, false, @"folder1\*" );

If the preservePaths parameter is set to true, the part of the path that is explicitly included in the filesToUnzip parameter will not be restored into the destination folder.

For example, for the same zip file as above, the following code will create the folder "folder2" into the "c:\temp" destination folder. Files that were in the "folder1" subfolder in the zip will be unzipped directly into the root of "c:\temp", and files that were in "folder1\folder2" will be unzipped into "c:\temp\folder2":

Xceed.Zip.QuickZip.Unzip( @"c:\test.zip", @"c:\temp", true, true, true, @"folder1\*" );

The following example will unzip files into "c:\temp\folder1" and "c:\temp\folder1\folder2":

Xceed.Zip.QuickZip.Unzip( @"c:\test.zip", @"c:\temp", true, true, true, @"*" );

Remarks

Zip files are case sensitive therefore the string passed in the filesToUnzip parameter, will be used "as-is". For example, if a zip file contains a file named "FILE.TXT" and "file.txt" is passed to the filesToUnzip parameter, "FILE.TXT" will not be extracted.

Note that the filesToUnzip parameter of the Unzip method cannot be null otherwise an ArgumentNullException exception will be thrown.

Things you should consider

The main questions you should ask yourself when extracting files from a zip file are:

  • Do you want to do more complex zip file operations? Use the class library rather than the QuickZip class.


Listing the contents of a zip file

Introduction

This topic demonstrates how to list the contents of a zip file.

Basic steps

To list the contents of a zip file, the following steps must be performed:

  • Declare an array of QuickZipItem objects that will contain the result of the call to the GetZipContents method.

  • Iterate through the array of QuickZipItem objects to retrieve information in regards to each QuickZipItem object it contains.

C# demonstration

This example assumes that you are in a console application.

using Xceed.Zip

QuickZipItem[] items = QuickZip.GetZipContents( @"c:\test.zip", @"*" );

foreach( QuickZipItem item in items)

{

Console.WriteLine( item.Name );

}

VB.NET demonstration

This example assumes that you are in a console application.

Imports Xceed.Zip

Dim items As QuickZipItem()

Dim item As QuickZipItem

items = QuickZip.GetZipContents( "c:\test.zip", "*" )

For Each item In items

Console.WriteLine( item.Name )

Next

Remarks

Zip files are case sensitive therefore the string passed in the fileMasks parameter, will be used "as-is". For example, if a zip file contains a file named "FILE.TXT" and "file.txt" is passed to the fileMasks parameter, "FILE.TXT" will not be retrieved.

Things you should consider

The main questions you should ask yourself when listing the contents of a zip file are:

  • Do you want to do more complex zip file operations? Use the class library rather than the QuickZip class.


Removing files from a zip file

Introduction

This topic demonstrates how to remove file(s) from within a zip file.

Examples

The Remove method has two overloads that can be used. The first overload only requires the path and file name of the zip file to remove files from as well as the path and name or filemask of the files to remove from the zip file. Note that files in sub-folders will also be removed from the zip file.

C# - Xceed.Zip.QuickZip.Remove( @"c:\test.zip", @"folder\file.txt" );

VB.NET - Xceed.Zip.QuickZip.Remove( "c:\test.zip", "folder\file.txt" )

With the second overload of the Remove method, you can specify whether or not you want to also remove files located in sub-folders by setting the recursive parameter.

C# - Xceed.Zip.QuickZip.Remove( @"c:\test.zip", true, @"folder\" );

VB.NET - Xceed.Zip.QuickZip.Remove( "c:\test.zip", True, "folder\" )

Remarks

Note that the filesToRemove parameter of the Remove method cannot be null otherwise an ArgumentNullException exception will be thrown.

Things you should consider

The main questions you should ask yourself when removing files from a zip file are:

  • Do you want to do more complex zip file operations? Use the class library rather than the QuickZip class.


Handling exceptions

Introduction

An exception is any error condition or unexpected behavior encountered by an executing program. Whenever an error occurs, an Exception object is created to represent the exception. The QuickZipException exception class that is thrown by the QuickZip class is handled in the same manner as regular run-time exceptions using Try/Catch blocks.

C# demonstration

This example assumes that you are in a console application.

try

{

Xceed.Zip.QuickZip.Unzip( @"c:\test.zip", @"c:\temp", @"*");

}

catch( Xceed.Zip.QuickZipException e )

{

Console.WriteLine( e.Message );

}

VB.NET demonstration

This example assumes that you are in a console application

Try

Xceed.Zip.QuickZip.Unzip("c:\test.zip", "c:\temp", "*")

Catch e As Xceed.Zip.QuickZipException

Console.WriteLine( e.Message )

End Try


Introduction to the Xceed.Zip namespace

Introduction

The Xceed.Zip namespace (represented in green) implements the QuickZip class which exposes static methods that allow quick and easy zip file operations in one line of code. It also provides classes that implement methods for handling zip files as well as files and folders contained within zip files.

The Xceed Zip class library regroups the ZippedFolder class which represents a zipped folder and the ZipArchive class which represents the root of a zip file. Both these classes derive from the AbstractFolder class. It also regroups the ZippedFile class, which derives from the AbstractFile class and represents a file contained within a zip file

For more information in regards to the abstract classes from which the ZippedFolder, ZipArchive and ZippedFile classes derive, please refer to the Introduction to the Xceed.FileSystem namespace.

The following diagram illustrates the class hierarchy of the Xceed.Zip namespace in regards to the Xceed.FileSystem namespace (represented in blue):

QuickZip class

The QuickZip class exposes static methods that allow quick and easy zip file operations for developers that do not wish to use the class library. It does not, however, provide as much flexibility as the class library. In cases where more complex zip file operations are required or in the cases where events are desired, developers will need to use the class library rather than the QuickZip class.

ZippedFolder class

The ZippedFolder class represents a folder contained within a zip file. This class derives and inherits methods from the AbstractFolder class of the Xceed.FileSystem namespace.

ZipArchive class

The ZipArchive class represents the root ("\") of a zip file. This class derives and inherits methods from the ZippedFolder class.

ZippedFile class

The ZippedFile class represents a file contained within a zip file. This class derives and inherits methods from the AbstractFile class of the Xceed.FileSystem namespace.


Full Template

Xceed.Zip Namespace

Header Example

Extra Information example

public Example {abstract get; abstract set;}

Property Value Example

Description of property.

Remarks

Remarks

Note: Note

Example Table Header

Example Type | Example Description
example1 | description example
example2 | description example

See Also