Events

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.FileSystem namespace defines four events that provide information about the status of an operation. These events are the ByteProgression event which provides information on the item being processed, the ItemProgression event which provides information on the item that is about to be processed, the ItemException event which is raised whenever an exception is caught during the processing of a list of items and the ScanningFolder event which is raised whenever a folder is scanned for matching items.

All these events are accessed through the FileSystemEvents class which dispatches the events that are raised to the subscribed callers.

The Xceed.Zip namespace defines five 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 target zip file is being built, the BuildingZipItemProgression event which is raised each time a file is about to be added to the target zip file, the ReadingZipItemProgression event which is raised is raised whenever an item in a zipped folder is about to be read, the GatheringZipContentByteProgression event which is raised during the step preceding the actual creation of the target zip file, where files to keep from the original zip file (the ones that were not modified) are gathered to a temporary location before overwriting the zip file and the DiskRequired event which is raised when a new disk or split part is required.

All these events are accessed through the ZipEvents class which derives from the FileSystemEvents class and 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.

FileSystemEvents class

The FileSystemEvents and ZipEvents classes dispatch the events that are raised to the callers that are subscribed to receive event notifications. If you want to call a method and receive its event notifications, it is important to use the method overload that takes a FileSystemEvents object as a parameter.

Each event has a corresponding delegate class that is used to subscribe to the event. To subscribe to an event, a new instance of the appropriate delegate class must be created and assigned to the corresponding event of the FileSystemEvents or 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 FileSystemEvents or ZipEvents object we are subscribing to.

C#
VB.NET

void Example1()
{
  // Setup a source and destination for a copy operation
  AbstractFolder source = new DiskFolder( @"D:\Folder1" );
  AbstractFolder destination = new DiskFolder( @"D:\Folder1_Copy" );

  // Create an events objects
  FileSystemEvents events = new FileSystemEvents();

  // Subscribe to the events we want to track
  events.ItemProgression += OnItemProgression;
  events.ItemCompletion += OnItemCompletion;

  // Optional: setup user-specific data to be passed to the event handlers
  object userData = 13;

  /* It is not enough to simply create the events object and subscribe to the events.
     The event object must be supplied as a parameter to the FileSystem methods.

     When the event object is supplied to the methods, the events will be triggered.
     Otherwise, the events will not be triggered. */

  // Copy the files in the source folder to the destination folder
  source.CopyFilesTo( events, userData, destination, true, true );
}

private void OnItemCompletion( object sender, ItemProgressionEventArgs e )
{
  throw new NotImplementedException();
}

private void OnItemProgression( object sender, ItemProgressionEventArgs e )
{
  throw new NotImplementedException();
}

    Private Sub Example1()
      ' Setup a source and destination for a copy operation
      Dim source As AbstractFolder = New DiskFolder("D:\Folder1")
      Dim destination As AbstractFolder = New DiskFolder("D:\Folder1_Copy")

      ' Create an events objects
      Dim events As New FileSystemEvents()

      ' Subscribe to the events we want to track
      AddHandler events.ItemProgression, AddressOf OnItemProgression
      AddHandler events.ItemCompletion, AddressOf OnItemCompletion

      ' Optional: setup user-specific data to be passed to the event handlers
      Dim userData As Object = 13

'       It is not enough to simply create the events object and subscribe to the events.
'         The event object must be supplied as a parameter to the FileSystem methods.
'
'         When the event object is supplied to the methods, the events will be triggered.
'         Otherwise, the events will not be triggered. 

      ' Copy the files in the source folder to the destination folder
      source.CopyFilesTo(events, userData, destination, True, True)
    End Sub

    Private Sub OnItemCompletion(ByVal sender As Object, ByVal e As ItemProgressionEventArgs)
      Throw New NotImplementedException()
    End Sub

    Private Sub OnItemProgression(ByVal sender As Object, ByVal e As ItemProgressionEventArgs)
      Throw New NotImplementedException()
    End Sub

ZipEvents class

Keep in mind that since the ZipEvents class derives from the FileSystemEvents class, it is also possible to subscribe to the events that the FileSystemEvents class implements.

C#
VB.NET

void ZipEventsExample1()
{
  // Create an events objects
  ZipEvents zipEvents = new ZipEvents();

  /* ZipEvents derives from FileSystemEvents. So the class can be used to subscribe
     to both FileSystem and Zip-related events. */

  // Subscribe to the events we want to track
  zipEvents.ItemProgression += OnItemProgression;
  zipEvents.ReadingZipItemProgression += ZipEvents_ReadingZipItemProgression;

  // Optional: setup user-specific data to be passed to the event handlers
  object userData = 13;

  // Locate a zip file we assume already exists and contains a lot of items
  AbstractFile zipFile = new DiskFile( "MyZipFile.zip" );

  /* Existing zip files that contain a lot of items can take some time to process all
     the metadata. It can be useful to track the progression of the operation. */

  // Wrap a logical zip archive around the zip file, tracking the progress
  ZipArchive zip = new ZipArchive( zipEvents, userData, zipFile );

  // Setup a source for a zip operation
  AbstractFolder source = new DiskFolder( @"D:\Folder1" );

  /* You can use the same event object for different operations. We don't expect the
     ReadingZipItemProgression event to be triggered during a zip operation. But that's
     fine, there is no penalty. */

  // Copy the files in the source folder to the destination folder
  source.CopyFilesTo( zipEvents, userData, zip, true, true );
}

private void ZipEvents_ReadingZipItemProgression( object sender, ItemProgressionEventArgs e )
{
  throw new NotImplementedException();
}

private void OnItemProgression( object sender, ItemProgressionEventArgs e )
{
  throw new NotImplementedException();
}

    Private Sub ZipEventsExample1()
      ' Create an events objects
      Dim zipEvents As New ZipEvents()

'       ZipEvents derives from FileSystemEvents. So the class can be used to subscribe
'         to both FileSystem and Zip-related events. 

      ' Subscribe to the events we want to track
      AddHandler zipEvents.ItemProgression, AddressOf OnItemProgression
      AddHandler zipEvents.ReadingZipItemProgression, AddressOf ZipEvents_ReadingZipItemProgression

      ' Optional: setup user-specific data to be passed to the event handlers
      Dim userData As Object = 13

      ' Locate a zip file we assume already exists and contains a lot of items
      Dim zipFile As AbstractFile = New DiskFile("MyZipFile.zip")

'       Existing zip files that contain a lot of items can take some time to process all
'         the metadata. It can be useful to track the progression of the operation. 

      ' Wrap a logical zip archive around the zip file, tracking the progress
      Dim zip As New ZipArchive(zipEvents, userData, zipFile)

      ' Setup a source for a zip operation
      Dim source As AbstractFolder = New DiskFolder("D:\Folder1")

'       You can use the same event object for different operations. We don't expect the
'         ReadingZipItemProgression event to be triggered during a zip operation. But that's
'         fine, there is no penalty. 

      ' Copy the files in the source folder to the destination folder
      source.CopyFilesTo(zipEvents, userData, zip, True, True)
    End Sub

    Private Sub ZipEvents_ReadingZipItemProgression(ByVal sender As Object, ByVal e As ItemProgressionEventArgs)
      Throw New NotImplementedException()
    End Sub

    Private Sub OnItemProgression(ByVal sender As Object, ByVal e As ItemProgressionEventArgs)
      Throw New NotImplementedException()
    End Sub

Events and ZipMultiThreadManager

Main article: Zipping items using multiple threads

Events of the FtpConnection class

Contrary to other events which are subscribed to by creating an instance of a FileSystemEvents class, the ParsingListingLine, CertificateRequired, and CertificateReceived events can only be subscribed to via the FtpConnection instance. If any other events are required, an instance of the FileSystemEvents class must be created and the desired events subscribed to.

The WaitingForAsyncOperation event is obsolete. The SynchronizingObject property should be used instead.