Programming with the Xceed FileSystem Class Library

Introduction

This section of the manual is designed to show you how to program using the Xceed FileSystem class library once you have read the Introduction to the Xceed.FileSystem namespace.

Topics

  • Copying items to a folder

  • Listing the contents of a folder

  • Removing items from a folder

  • Optimizing batch updates to a folder

  • Handling exceptions

  • Case sensitivity

  • Handling events

  • Using filters


Copying items to a folder

Introduction

This topic demonstrates how to copy items to a folder. Since the AbstractFolder class cannot be instantiated, it is necessary to use classes that derive from the AbstractFolder class for both the source and destination folders.

Basic steps

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

  • Create a reference to an object that derives from the AbstractFolder class. For example, the ZippedFolder, ZipArchive or DiskFolder classes.

  • Call the CopyFilesTo method to copy the files from the source folder (including subfolders that contain files) to the destination folder. This method requires an object that derives from the AbstractFolder class as a parameter therefore, we create an instance of the appropriate object in the method call.

C# demonstration

This example assumes that you are in a console application and that you are working with disk folders:

using Xceed.FileSystem;

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

diskFolder.CopyFilesTo( new DiskFolder( @"c:\destination" ), true, true );

VB.NET demonstration

This example assumes that you are in a Windows application and that you are working with disk folders:

Imports Xceed.FileSystem

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

diskFolder.CopyFilesTo( New DiskFolder( "c:\destination" ), True, True )

Things you should consider

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

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

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


Listing the contents of a folder

Introduction

This topic demonstrates how to list the contents of a folder. Since the AbstractFolder class cannot be instantiated, it is necessary to use a class that derives from the AbstractFolder class as the source folder.

Basic steps

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

  • Create a reference to an object that derives from the AbstractFolder class. For example, the ZippedFolder, ZipArchive or DiskFolder classes.

  • Call the GetFiles method to retrieve an array of AbstractFile objects.

  • You can now loop through the array of files and extract the desired information.

C# demonstration

This example assumes that you are in a console application and that you are working with disk folders:

using Xceed.FileSystem;

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

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

{

Console.WriteLine( f.FullName );

}

VB.NET demonstration

This example assumes that you are in a Windows application, that you have a listbox on the form and that you are working with disk folders:

Imports Xceed.FileSystem

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

Dim f As AbstractFile

For Each f In folder.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 folder are:

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

  • Do you want to retrieve a reference to a single 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 filter your list of files or folders? See the Using filters topic.


Removing items from a folder

Introduction

This topic demonstrates how to remove items from a folder by retrieving a reference to a file. Since the AbstractFile class cannot be instantiated, it is necessary to use a class that derives from the AbstractFile class as the target file.

Basic steps

To remove items from a folder, the following steps must be performed:

  • Create a reference to an object that derives from the AbstractFile class. For example, the ZippedFile or DiskFile classes.

  • Once we have a reference to a file 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 and that you are working with disk folders:

using Xceed.FileSystem;

DiskFile f = new DiskFile( @"c:\test.txt" );

if( f.Exists )

{

f.Delete();

}

VB.NET demonstration

This example assumes that you are in a Windows application and that you are working with disk folders:

Imports Xceed.FileSystem

Dim f As New DiskFile( "c:\test.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 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 class that derives from the AbstractFolder class rather than the AbstractFile class.

  • 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.


Optimizing batch updates to a folder

Introduction

When performing multiple operations on a folder, the process can take a while to complete. Although events can provide feedback during these lengthy operations, it is also possible to reduce the time it takes to accomplish all the operations if the folder class being used implements the IBatchUpdateable interface.

The IBatchUpdateable interface is defined within the Xceed.FileSystem namespace and is implemented by the ZipArchive class of the Xceed.Zip namespace.

IBatchUpdateable interface

The IBatchUpdateable interface implements the BeginUpdate and EndUpdate methods which allow you to determine a scope at the end of which all the modifications made to a folder will be committed. Using this interface increases the speed at which the operations on the folder are accomplished since the modifications are not committed to the folder each time a method is called but rather only once for all the operations when the EndUpdate method is called.

If a class implements the IBatchUpdateable interface, the BeginUpdate and EndUpdate methods can be called directly on the class. For example:

using Xceed.FileSystem;

using Xceed.Zip;

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

archive.BeginUpdate();

//Code

archive.EndUpdate();

Classes that implement the IBatchUpdateable interface

Although for the moment only the ZipArchive class implements the IBatchUpdateable interface, in the future, other classes might also implement this interface. This is where, in C#, the AutoBatchUpdate class becomes useful.

The AutoBatchUpdate class will verify to see that the folder class passed in its constructor implements the IBatchUpdateable interface and will automatically call the BeginUpdate and EndUpdate methods if it does. If the folder class does not implement the IBatchUpdateable interface, the code will be executed normally.

Basic steps

To perform batch updates, the following steps must be performed:

  • Verify if the folder class implements the IBatchUpdateable interface. This can only be done via the root of the folder. Keep in mind that for the moment, only the ZipArchive class implements this interface.

  • If the IBatchUpdateable interface is implemented, call the BeginUpdate method to mark the begin of your scope.

  • Do the various operations on the folder.

  • To commit the modifications made to the folder, call the EndUpdate method. It is important to make sure that the EndUpdate method is always called otherwise the modifications will not be committed.

C# demonstration

This example demonstrates how to use the IBatchUpdateable interface directly:

using Xceed.FileSystem

//folder represents any type of folder

IBatchUpdateable batch = folder.RootFolder as IBatchUpdateable;

//Check if our folder class implements the IBatchUpdateable interface via it's root

//If it does, call the BeginUpdate method.

if( batch != null )

batch.BeginUpdate();

try

{

//Perform the various operations.

}

finally

{

if( batch != null )

batch.EndUpdate();

}

This example demonstrates how to use the AutoBatchUpdate class rather than manually calling the BeginUpdate and EndUpdate methods manually:

//folder represents any type of folder

using( AutoBatchUpdate batch = new AutoBatchUpdate( folder.RootFolder ) )

{

//Perform the various operations.

//Once the scope of the using statement is exited, if the folder class implemented

//the IBatchUpdateable interface, the changes to the folder will be committed.

}

VB.NET demonstration

Imports Xceed.FileSystem

Dim batch As IBatchUpdateable = Nothing

If TypeOf folder.RootFolder Is IBatchUpdateable Then

batch = folder.RootFolder

batch.BeginUpdate()

End If

Try

'Perform the various operations

Finally

If Not batch Is Nothing Then

batch.EndUpdate()

End If

End Try


Exceptions

Xceed.FileSystem 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 FileSystem namespace, are handled in the same manner as regular run-time exceptions using Try/Catch blocks. Xceed FileSystem provides you with the possibility 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 FileSystem namespace:

Exception | Description
FileSystemException | Exception that is thrown when an error occurs in the Xceed.FileSystem namespace.
FileSystemInternalException | Exception that is thrown when something unexpected occurs in the Xceed.FileSystem namespace.
FileSystemIOException | Exception that is thrown when an IO error occurs while reading from or writing to an AbstractFile object.
FileSystemNotSupportedException | Exception that is thrown when calling a method or accessing a property that is not supported by a FileSystemItem object.
ItemAlreadyExistsException | Exception that is thrown when performing an operation on a FileSystemItem object that already exists.
ItemDoesNotExistException | Exception that is thrown when performing an operation on a FileSystemItem object that does not yet exist.
ItemIsReadOnlyException | Exception that is thrown when performing an operation on a FileSystemItem object that is read only.
ItemIsRootFolderException | Exception that is thrown when performing an operation on a FileSystemItem object that is a root folder that does not permit that operation.

C# demonstration

The following example demonstrates how to use a Try/Catch statement when calling the Delete method on a non-existing file.

try

{

DiskFile f = new DiskFile( @"c:\test.txt" );

f.Delete();

}

catch( FileSystemException err )

{

Console.WriteLine( err.Message );

}

Of course, this type of exception can be avoided altogether if we simply check the Exists property to see of the file actually exists before we try to delete it:

try

{

DiskFile f = new DiskFile( @"c:\test.txt" );

if( f.Exists )

{

f.Delete();

}

}

catch( FileSystemException 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 non-existing file.

Try

Dim f As New DiskFile( "c:\test.txt" )

f.Delete()

Catch err As FileSystemException

ListBox1.Items.Add( err.Message )

End Try

Of course, this type of exception can be avoided altogether if we simply check the Exists property to see of the file actually exists before we try to delete it:

Try

Dim f As New DiskFile( "c:\test.txt" )

If f.Exists Then

f.Delete()

End If

Catch err As FileSystemException

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.


Case sensitivity

Introduction

The classes defined within the Xceed.FileSystem namespace and other derived classes, do not enforce case sensitivity. When a string is passed to a method call, for example, the GetFile method, the string is not manipulated in any way and is used "as is".

Case sensitive source or destination

When dealing with case sensitive sources or destinations such as UNIX FTP servers or zip files, it is up to the user to pass a valid string to the method. For example, if you were to use the GetFile method to retrieve a reference to a file within a zip file and the filename exists in both lower case and uppercase, it is up to you to pass the filename in the appropriate case in order to retrieve a reference to the desired file. This is necessary because the GetFile method does not create a NameFilter class around the string passed in the method call.

For example, if we wanted to retrieve a reference to file.txt located in a zip file but FILE.TXT also exists, the following code would be used:

GetFile( "file.txt" );

To retrieve a reference to FILE.TXT rather than file.txt, the following code would be used:

GetFile( "FILE.TXT" );

NameFilter classes

When using NameFilter classes, by default, case sensitivity is not enforced. In order to enforce case sensitivity, a greater-than symbol (>) must be used as the first character of the string.

For example, if we were to use the following code, all files that have the TXT extension would be returned regardless of the case:

GetFiles( true, "*.TXT" );

In order to return only the TXT files that have an extension in upper case, it is necessary to add the greater-than symbol:

GetFiles( true, ">*.TXT" );

The greater-then symbol affects the entire string passed to the name filter. Therefore, if you were to use the following code, all the files that have the TXT extension in lower case and all the files that have the EXE extension in lower case will be returned:

GetFiles( true, ">*.txt|*.exe" ) );

If you wanted to retrieve all the files that have the TXT extension in lower case or all the files that have the EXE extension in upper case, you would need to create a NameFilter around each one:

GetFiles( true, new OrFilter( new NameFilter( ">*.txt" ), new NameFilter( ">*.EXE" ) ) );


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.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 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.

FileSystemEvents class

The FileSystemEvents 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 FileSystemEvents object as a parameter.

The ByteProgressionEventHandler, ItemProgressionEventHandler, ItemExceptionEventHandler and the ScanningFolderEventHandler 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 FileSystemEvents 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 object we are subscribing to.

FileSystemEvents fiEvents = new FileSystemEvents();

fiEvents.ScanningFolder += new ScanningFolderEventHandler( OnScanningFolder );

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

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 OnScanningFolder( object sender, ScanningFolderEventArgs e )

The following diagram represents the hierarchy of the FileSystemEventArgs classes:


ByteProgression event

Introduction

The ByteProgression event is raised while a list of FileSystemItem objects is being processed, for every 64k of bytes processed.

Keep in mind that using the ByteProgression event increases the time it takes to process the 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 ByteProgression event is to provide feedback to the user during lengthy operations. For example, if we wanted to delete a folder and all it's sub-directories, the process could take a while and the application could appear to be frozen. To prevent this behavior, you can update a progress bar in the event handler for the ByteProgression event.

Basic steps - C#

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

  • Create a reference to a FileSystemEvents object.

  • Subscribe to the ByteProgression event of the FileSystemEvents object using the ByteProgressionEventHandler 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 OnByteProgression.

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

Basic steps - VB.NET

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

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

  • Select the ByteProgression event from the list of available methods in the newly instantiated FileSystemEvents 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

using Xceed.FileSystem;

FileSystemEvents fiEvents = new FileSystemEvents();

fiEvents.ByteProgression += new ByteProgressionEventHandler( OnByteProgression );

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

folder.Delete( fiEvents, null );

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

public static void OnByteProgression( 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:

fiEvents.ByteProgression -= new ByteProgressionEventHandler( OnByteProgression );

VB.NET demonstration

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

Imports Xceed.FileSystem

Dim WithEvents fiEvents As New FileSystemEvents()

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

folder.Delete( fiEvents, Nothing )

Private Sub fiEvents_ByteProgression( ByVal sender As Object,

ByVal e As Xceed.FileSystem.ByteProgressionEventArgs )

Handles fiEvents.ByteProgression

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

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

" on " + e.CurrentItem.Name )

End Sub


ItemProgression event

Introduction

The ItemProgression event is raised each time a FileSystemItem object is about to be processed by a method call, providing progression information to the handler.

Keep in mind that using the ItemProgression event increases the time it takes to process the 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 ItemProgression event is to provide feedback to the user during lengthy operations. For example, if we wanted to delete a folder and all it's sub-directories, the process could take a while and the application could appear to be frozen. To notify the user that the application is still in the process of completing the operation, you can update a progress bar in the event handler for the ItemProgression event.

Basic steps - C#

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

  • Create a reference to a FileSystemEvents object.

  • Subscribe to the ItemProgression event of the FileSystemEvents object using the ItemProgressionEventHandler 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 OnItemProgression.

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

Basic steps - VB.NET

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

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

  • Select the ItemProgression event from the list of available methods in the newly instantiated FileSystemEvents 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.FileSystem;

FileSystemEvents fiEvents = new FileSystemEvents();

fiEvents.ItemProgression += new ItemProgressionEventHandler( OnItemProgression );

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

folder.Delete( fiEvents, null );

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

public static void OnItemProgression( 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:

fiEvents.ItemProgression -= new ItemProgressionEventHandler( OnItemProgression );

VB.NET demonstration

Imports Xceed.FileSystem

Dim WithEvents fiEvents As New FileSystemEvents()

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

folder.Delete( fiEvents, Nothing )

Private Sub fiEvents_ItemProgression( ByVal sender As Object,

ByVal e As Xceed.FileSystem.ItemProgressionEventArgs )

Handles fiEvents.ItemProgression

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

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

" on " + e.CurrentItem.Name )

End Sub


ItemException event

Introduction

The ItemException event is raised when an exception is caught during the processing of a list of FileSystemItem objects, allowing the handler to decide if the process should be aborted and the exception be thrown, if the process should continue with the next item in the list or if the same item should be retried.

Purpose

The ItemException event is used to intercept exceptions before they are thrown. This can be useful in the case where you are copying a large number of files and an error occurs on one of the files or if you are trying to access a file that is password protected. In both of these cases, custom handling of the exception can be added to the event handler, or if no special handling is required, a message could be displayed explaining the reason why the exception was thrown.

The following methods can raise the ItemException event:

Method | Description
FileSystemItem.CopyTo | Copies the item to another folder.
FileSystemItem.Delete | Permanently deletes the physical item.
FileSystemItem.MoveTo | Moves the item to another folder.
AbstractFile.CopyTo | Copies the file's data to another file.
AbstractFolder.CopyFilesTo | Copies the folder's content to another folder.
AbstractFolder.GetFiles | Returns a filtered list of files contained in the folder.
AbstractFolder.GetFolders | Returns a filtered list of folders contained in the folder.
AbstractFolder.GetItems | Returns a list of items contained in the folder.
AbstractFolder.MoveFilesTo | Moves the folder's content to another folder.

Basic steps - C#

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

  • Create a reference to a FileSystemEvents object.

  • Subscribe to the ItemException event of the FileSystemEvents object using the ItemExceptionEventHandler 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 OnItemException.

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

Basic steps - VB.NET

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

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

  • Select the ItemException event from the list of available methods in the newly instantiated FileSystemEvents 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.FileSystem;

FileSystemEvents fiEvents = new FileSystemEvents();

fiEvents.ItemException += new ItemExceptionEventHandler( OnItemException );

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

folder.CopyFilesTo( new DiskFolder( @"c:\destination" ), true, false, fiEvents );

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

public static void OnItemException( object sender, ItemExceptionEventArgs e )

{

if( e.Exception is ItemAlreadyExistsException )

{

e.TargetItem.Delete();

e.Action = ItemExceptionAction.Retry;

}

}

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

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

fiEvents.ItemException -= new ItemExceptionEventHandler( OnItemException );

VB.NET demonstration

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

Imports Xceed.FileSystem

Dim WithEvents fiEvents As New FileSystemEvents()

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

folder.CopyFilesTo( New DiskFolder( "c:\destination" ), True, False, fiEvents )

Private Sub fiEvents_ItemException( ByVal sender As Object,

ByVal e As Xceed.FileSystem.ItemExceptionEventArgs )

Handles fiEvents.ItemException

If e.Exception Is ItemAlreadyExistsException Then

e.TargetItem.Delete()

e.Action = ItemExceptionAction.Retry

End If

End Sub


ScanningFolder event

Introduction

The ScanningFolder event is raised whenever a folder is scanned for matching items while building a list of items to process.

Purpose

The main purpose of the ScanningFolder event is to prevent your application from appearing frozen during long operations. For example, if you were to handle the ByteProgression event in conjunction with the ScanningFolder event, the ScanningFolder event could return information on the folders being scanned during the first pass of the ByteProgression event.

Basic steps - C#

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

  • Create a reference to a FileSystemEvents object.

  • Subscribe to the ScanningFolder event of the FileSystemEvents object using the ScanningFolderEventHandler 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 OnScanningFolder.

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

Basic steps - VB.NET

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

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

  • Select the ScanningFolder event from the list of available methods in the newly instantiated FileSystemEvents 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.FileSystem;

FileSystemEvents fiEvents = new FileSystemEvents();

fiEvents.ScanningFolder += new ScanningFolderEventHandler( OnScanningFolder );

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

folder.CopyFilesTo( new DiskFolder( @"c:\destination" ), true, true, fiEvents );

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

public static void OnScanningFolder( object sender, ScanningFolderEventArgs e )

{

Console.WriteLine( "Scanning " + 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:

fiEvents.ScanningFolder -= new ScanningFolderEventHandler( OnItemException );

VB.NET demonstration

Imports Xceed.FileSystem

Dim WithEvents fiEvents As New FileSystemEvents()

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

folder.CopyFilesTo( New DiskFolder( "c:\destination" ), True, True, fiEvents )

Private Sub fiEvents_ScanningFolder( ByVal sender As Object,

ByVal e As Xceed.FileSystem.ScanningFolderEventArgs )

Handles fiEvents.ScanningFolder

ListBox1.Items.Add( "Scanning " + e.CurrentItem.Name )

End Sub


Using filters

Introduction

Filters are used to target specific files and folders to process using either basic filters or Filter classes.

Basic filters

A basic filter is a filter that is constructed from a string or a filter built using a file attribute. The most common example of a basic filter would be a name mask on a group of files.

For example, if you wanted to process only the TXT files found in a folder, you could simply use "*.txt" as a filter without needing to create a Filter class around the string.

GetFiles( true, "*.txt" );

You could also process all files that have the read-only attribute without creating a filter class:

GetFiles( true, System.IO.FileAttributes.ReadOnly)

Filter class?

The Xceed.FileSystem namespace regroups seven Filter classes: the AttributeFilter class which filters files and folders according to their attributes, the DateTimeFilter class which filters files and folders according to their dates and times, the NameFilter class which filters files and folders according to their names and the SizeFilter class which filters files according to their size. It also regroups three logical Filter classes: the AndFilter class which allows logical-and operations, the NotFilter class which serves to negate filters and the OrFilter class which allows logical-or operations. All of these classes derive from the base Filter class.

The following diagram represents the class hierarchy of the Filter classes:

If we revisit the basic filter example and want to process only the TXT files found in a folder, but this time using a Filter class, you would need to create an instance of the NameFilter class and pass it the name mask in it's constructor. This is the same thing that happens underneath when using basic filters.

GetFiles( true, new NameFilter( "*.txt" ) );

When using the AttributeFilter, the DateTimeFilter and the NameFilter classes, it is also possible to specify if the filters will apply to files, folders or both. This is done by using the FilterScope enumeration in the constructor of the Filter class.

For example:

GetFiles( true, new NameFilter( "doc*", FilterScope.File ) );

It is also possible to derive from the base Filter class to create customized Filter classes if needed.

Logical filters

The AndFilter, NotFilter and OrFilter classes are used to create custom logic operations around multiple filters. When more than one filter is used, they are combined by default with an AndFilter. This means that for an item to be processed, it must match all of the filters provided.

For example, if we wanted to process all files that have the TXT or the EXE extension and that have a size greater than 5k, the following code could be used:

SizeFilter sizeFilter = new SizeFilter();

sizeFilter.MinSize = 5120;

GetFiles( true, new AndFilter( new NameFilter( "*.txt|*.exe" ), sizeFilter ) );

The pipe (|) used in the constructor of the NameFilter class serves the same purpose as an OrFilter class.

Since the AndFilter class is used by default, the creation of a new AndFilter class around the NameFilter and the SizeFilter can be omitted:

SizeFilter sizeFilter = new SizeFilter();

sizeFilter.MinSize = 5120;

GetFiles( true, new NameFilter( "*.txt|*.exe" ), sizeFilter );

Since the NameFilter class is used by default when using a basic string filter, the creation of a new NameFilter class around the string can be omitted:

Dim sizeFilter = new SizeFilter();

sizeFilter.MinSize = 5120;

GetFiles( true, "*.txt|*.exe", sizeFilter );


AttributeFilter

Xceed.FileSystem Namespace

AttributeFilter Class

Introduction

The AttributeFilter class can be used to filter files and folders according to their attributes. The attributes are specified by using the FileAttributes enumeration of the System.IO namespace

Demonstrations

Process all files that have the readonly attribute.

GetFiles( true, new AttributeFilter( System.IO.FileAttributes.ReadOnly ) );

Process all files that have both the readonly and the hidden attribute.

GetFiles( true, new AttributeFilter( System.IO.FileAttributes.ReadOnly ),

new AttributeFilter( System.IO.FileAttributes.Hidden ) );

Process all files that have either the readonly or hidden attribute.

GetFiles( true, new AttributeFilter( System.IO.FileAttributes.ReadOnly|System.IO.FileAttributes.Hidden ) );

The pipe (|) used in the constructor of the AttributeFilter class serves the same purpose as an OrFilter class.

Things you should consider

  • Do you only want to target specific types of folder items? Use the FilterScope enumeration in the constructor of the AttributeFilter class.


DateTimeFilter

Xceed.FileSystem Namespace

DateTimeFilter Class

Introduction

The DateTimeFilter class can be used to filter files and folder according to their dates. By default, if a specific type of date is not specified (last accessed, creation, etc...), the last write date is consulted.

Demonstration

Process all files that have a last write date between January 1st 1999 and January 1st 2001.

GetFiles( true, new DateTimeFilter( new System.DateTime( 1999, 01, 01 ),

new System.DateTime( 2001, 01, 01 ) ) );

Process all files that have a last accessed date between January 1st 1999 and January 1st 2001.

GetFiles( true, new DateTimeFilter( new System.DateTime( 1999, 01, 01 ),

new System.DateTime( 2001, 01, 01 ),

DateTimeFilter.ApplicableDateTime.LastAccess ) );

Things you should consider

  • Do you only want to target specific types of folder items? Use the FilterScope enumeration in the constructor of the DateTimeFilter class.

  • Do you want to filter according to a specific type of date? Use the ApplicableDateTime enumeration in the constructor of the DateTimeFilter class.


NameFilter

Xceed.FileSystem Namespace

NameFilter Class

Introduction

The NameFilter class can be used to filter files and folders according to their names.

Case sensitivity

When using NameFilter classes, by default, case sensitivity is not enforced. In order to enforce case sensitivity, a greater-than symbol (>) must be used as the first character of the string. For example:

GetFiles( true, ">*.TXT" );

GetFiles( true, ">*.txt|*.exe" ) );

Demonstrations

Process all files that have the TXT extension. Since, by default, the FilterScope enumeration is set to File and we are using "*.txt" as the filter, there is no need to implicitly set the FilterScope enumeration in the constructor of the NameFilter class.

GetFiles( true, new NameFilter( "*.txt" ) );

Since we are using a basic string filter, the NameFilter class is used by default, therefore we can omit the creation of a new NameFilter class and simply use a basic filter.

GetFiles( true, "*.txt" );

Process all files that have either the TXT or EXE extension.

GetFiles( true, new OrFilter( new NameFilter( "*.txt" ), new NameFilter( "*.exe" ) ) );

It is possible to simplify the above example by using the pipe (|) character to separate the two strings. The pipe character servers the same purpose as the OrFilter class and removes the necessity of creating two instances of the NameFilter class and regrouping them within an OrFilter class.

GetFiles( true, new NameFilter( "*.txt|*.exe" ) );

Things you should consider

  • Do you only want to target specific types of folder items? Use the FilterScope enumeration in the constructor of the NameFilter class.


SizeFilter

Xceed.FileSystem Namespace

SizeFilter Class

Introduction

The SizeFilter class can be used to filter files according to their size.

C# demonstration

Retrieve all the files in a folder that are between 5k and 10k in size.

SizeFilter filter = new SizeFilter();

filter.MaxSize = 10240;

filter.MinSize = 5120;

GetFiles( true, filter );

VB.NET demonstration

Retrieve all the files in a folder that are between 5k and 10k in size.

Dim filter As New SizeFilter()

filter.MaxSize = 10240

filter.MinSize = 5120

GetFiles( true, filter )


AndFilter

Xceed.FileSystem Namespace

AndFilter Class

Introduction

The AndFilter class serves the same purpose as a logical-and operator. It states that the items must match all the filters regrouped within the AndFilter class in order to be processed.

C# demonstration

Process all the files in folder that contain the TXT extension and that are between 5k and 10k size.

SizeFilter filter = new SizeFilter();

filter.MaxSize = 10240;

filter.MinSize = 5120;

GetFiles( true, new AndFilter( new NameFilter( "*.txt" ), filter ) );

Since the AndFilter is used by default when combining multiple filters, it is not necessary to create an instance of the AndFilter class. Therefore, we can omit the creation of the class. We can also omit creating a NameFilter class since we are using a basic string filter and the NameFilter class is constructed underneath.

SizeFilter filter = new SizeFilter();

filter.MaxSize = 10240;

filter.MinSize = 5120;

GetFiles( true, "*.txt", filter );

VB.NET demonstration

Process all the files in folder that contain the TXT extension and that are between 5k and 10k size.

Dim filter As New SizeFilter()

filter.MaxSize = 10240

filter.MinSize = 5120

GetFiles( true, New AndFilter( New NameFilter( "*.txt" ), filter ) )

Since the AndFilter is used by default when combining multiple filters, it is not necessary to create an instance of the AndFilter class. Therefore, we can omit the creation of the class. We can also omit creating a NameFilter class since we are using a basic string filter and the NameFilter class is constructed underneath.

Dim filter As New SizeFilter()

filter.MaxSize = 10240

filter.MinSize = 5120

GetFiles( true, "*.txt", filter )


NotFilter

Xceed.FileSystem Namespace

NotFilter Class

Introduction

The NotFilter class serves to negate filters. It states that in order for the items to be processed they must not match the encompassed filters.

Demonstrations

Process all the files that do not have the TXT extension. We will omit the creation of the NameFilter class around the name mask since it is being created underneath.

GetFiles( true, NotFilter( "*.txt" ) );


OrFilter

Xceed.FileSystem Namespace

OrFilter Class

Introduction

The OrFilter class serves the same purpose as a logical-or operator. It states the items must match at least one of the filters it regroups in order to be processed.

C# demonstrations

This example processes all the files that have the TXT or the EXE extension.

GetFiles( new OrFilter( new NameFilter( "*.txt" ), new NameFilter( "*.exe" ) ) );

Since using a pipe (|) in the constructor of a NameFilter class accomplishes the same thing as regrouping multiple NameFilter classes within an OrFilter class, the following code would be simpler.

GetFiles( "*.txt|*.exe" );

This example processes all the files that have the TXT extension or are greater than 10k in size. Again, we omit the creation of the NameFilter class around the name mask since it is already being created underneath.

SizeFilter filter = new SizeFilter();

filter.MinSize = 10240;

GetFiles( OrFilter( "*.txt", filter ) );

VB.NET demonstration

This example processes all the files that have the TXT or the EXE extension.

GetFiles( new OrFilter( new NameFilter( "*.txt" ), new NameFilter( "*.exe" ) ) )

Since using a pipe (|) in the constructor of a NameFilter class accomplishes the same as regrouping multiple NameFilter classes within an OrFilter class, the following code would be simpler.

GetFiles( "*.txt|*.exe" )

This example processes all the files that have the TXT extension or are greater than 10k in size. Again, we omit the creation of the NameFilter class around the name mask since it is already being created underneath.

Dim filter As New SizeFilter()

filter.MinSize = 10240

GetFiles( OrFilter( "*.txt", filter ) )


Extending the Xceed FileSystem object model

Introduction

The Xceed FileSystem object model was created in such a way as to allow other classes to easily derive from it's base classes in order to implement custom file and folder manipulation classes. These bases classes are the FileSystemItem, AbstractFolder and AbstractFile classes.

When deriving from the Xceed FileSystem object model, all the abstract methods and properties of the FileSystemItem and AbstractFolder or AbstractFile classes must be overridden. It is not necessary, however, to implement each override. In the case where there is no implementation, a NotImplementedException exception should be thrown.

Each of the overridden abstract "Do" methods and properties are called by their corresponding public counterparts and are responsible for executing the actual operation. The public method simply validates the parameters. It is the "Do" implementation that must make sure that the required conditions are met. For example, in order to call delete on an item, it must first exist. This means that your implementation of DoDelete must throw an ItemDoesNotExistException if the item does not exist.

Templates of classes that derive from the AbstractFolder and AbstractFile classes a available here.

The following tables provide a list of all the abstract methods and properties that must be overridden:

FileSystemItem class

Abstract method/property | Description
DoName | Gets or sets the short name of the item.
DoFullName | Gets the full name of the item.
DoAttributes | Gets or sets the attributes of the item.
DoCreationDateTime | Gets or sets the creation date and time of the item.
DoLastWriteDateTime | Gets or sets the modification date and time of the item.
DoLastAccessDateTime | Gets or sets the last access date and time of the item.
DoParentFolder | Gets a reference to the parent folder of this item.
DoRootFolder | Gets a reference to the root folder of this item.
DoExists | Gets a boolean value indicating if the item physically exists.
DoRefresh | Re-reads the information from the physical item.
DoCreate | Creates the physical item.
DoDelete | Permanently deletes the physical item.
DoCopyTo | Copies the item to another folder.
IsSameAs | Returns a boolean value indicating if the source and target items are the same.
IsPathRooted | Returns a boolean value indicating if the path passed is rooted in the environment of the item we are dealing with.

AbstractFolder class

Method/Property | Description
DoGetFile | Retrieves a reference to an AbstractFile object by it's name.
DoGetFolder | Retrieves a reference to an AbstractFolder object by it's name.
DoGetChildItems | Retrieves an array of FileSystemItem objects representing each item ( file or folder ) in the folder.

AbstractFile class

Method/Property | Description
DoSize | Gets the size of the file in bytes.
DoOpenRead | Opens the file for reading.
DoOpenWrite | Opens the file for writing.


Defining new events

Introduction

When creating custom file and folder manipulation classes that derive from the base classes of the Xceed FileSystem object model, it is also possible to define new events that will be raised from within the derived classes.

Basic steps

In order to define new events, the following steps must be taken:

  • Declare a new public delegate for each event you want to define.

  • Create a class that derives from the FileSystemEvents class. The FileSystemEvents class serves as a central point of access to associate event handlers with events.

  • Add a new event for each delegate.

  • Override the CreateSession method of the FileSystemEvents class. The overridded CreateSession method must return an instance of the new events session class (see next step).

  • Implement a new method, for each delegate, that will raise the actual events.

  • Create a class that derives from the FileSystemEventsSession class.

    The FileSystemEventsSession class is responsible for building the argument structure and calling the corresponding FileSystemEvents' methods to raise events when appropriate. The session class can also hold method specific information. You can see a FileSystemEventsSession object as being a per method FileSystemEvents instance. For example, if Delete is called, a new session will be created by the Delete method that will be used only for this method call.

  • Implement a new method that will call the corresponding method in the event class.

A basic template of a class that defines new events can be found here.


Defining new exceptions

Introduction

When creating custom file and folder manipulation classes that derive from the base classes of the Xceed FileSystem object model, it is also possible to define new exceptions that will be thrown from within the derived classes.

Implementation

In order to define new exceptions, a class that derives from the FileSystemException class must be created and within this class the new exceptions implemented.

The Xceed FileSystem object model allows the following exceptions to be thrown from within derived classes. Any exceptions other than the ones that derive from the FileSystemException class, or the ones in the list below, will be wrapped in a FileSystemInternalException before they are thrown.

Exception | Description
ExecutionEngineException | The exception that is thrown when there is an internal error in the execution engine of the common language runtime.
OutOfMemoryException | The exception that is thrown when there is not enough memory to continue the execution of a program.
System.Security.SecurityException | The exception that is thrown when a security error is detected.
UnauthorizedAccessException | The exception that is thrown when the operating system denies access because of an I/O error or a specific type of security error.
ArgumentException | The exception that is thrown when one of the arguments provided to a method is not valid.

The following code provides a basic template for implementing custom exceptions.

using System;

using Xceed.FileSystem;

namespace ClassLibrary1

{

public class MyException : FileSystemException

{

public MyException( string message ) : base( message )

{

}

}

}


Class templates

Introduction

In order to help you get started in creating your own derived classes, we have provided templates that implement all of the necessary methods, properties, etc...

Index

  • AbstractFolder derived class

  • AbstractFile derived class

  • Event class

Sample

The ExtendingDemo sample included in the package demonstrates how to create classes that derive from the AbstractFolder and AbstractFile classes to handle files and folders located in Isolated Storage. The UsingExtendingDemo sample, also included in the samples folder, demonstrates the classes in action.

C# - <Installation Folder>\Xceed Zip for .NET\Samples\C#\ExtendingDemo\

C# - <Installation Folder>\Xceed Zip for .NET\Samples\C#\UsingExtendingDemo\


AbstractFolder derived class

Introduction

The following code provides a template of all the methods and properties that need to be overridden when creating a class that derives from the AbstractFolder class.

C# template

using System;

using System.IO;

using Xceed.FileSystem;

namespace ClassLibrary1

{

public class Class1 : AbstractFolder

{

public Class1()

{

//

// TODO: Add constructor logic here

//

}

#region FileSystemItem overrides

protected override string DoName

{

get

{

throw new NotImplementedException();

}

set

{

throw new NotImplementedException();

}

}

protected override string DoFullName

{

get

{

throw new NotImplementedException();

}

}

protected override FileAttributes DoAttributes

{

get

{

throw new NotImplementedException();

}

set

{

throw new NotImplementedException();

}

}

protected override DateTime DoCreationDateTime

{

get

{

throw new NotImplementedException();

}

set

{

throw new NotImplementedException();

}

}

protected override DateTime DoLastWriteDateTime

{

get

{

throw new NotImplementedException();

}

set

{

throw new NotImplementedException();

}

}

protected override DateTime DoLastAccessDateTime

{

get

{

throw new NotImplementedException();

}

set

{

throw new NotImplementedException();

}

}

protected override AbstractFolder DoParentFolder

{

get

{

throw new NotImplementedException();

}

}

protected override AbstractFolder DoRootFolder

{

get

{

throw new NotImplementedException();

}

}

protected override bool DoExists

{

get

{

throw new NotImplementedException();

}

}

protected override void DoRefresh( FileSystemEventsSession session )

{

throw new NotImplementedException();

}

protected override void DoCreate( FileSystemEventsSession session )

{

throw new NotImplementedException();

}

protected override void DoDelete( FileSystemEventsSession session )

{

throw new NotImplementedException();

}

protected override void DoCopyTo( FileSystemEventsSession session, FileSystemItem destination, bool replaceExistingFiles )

{

throw new NotImplementedException();

}

protected override bool IsSameAs( FileSystemItem target )

{

throw new NotImplementedException();

}

protected override bool IsPathRooted( string path )

{

throw new NotImplementedException();

}

#endregion FileSystemItem overrides

#region AbstractFolder override

protected override AbstractFile DoGetFile( FileSystemEventsSession session, string fileName )

{

throw new NotImplementedException();

}

protected override AbstractFolder DoGetFolder( FileSystemEventsSession session, string folderName )

{

throw new NotImplementedException();

}

protected override FileSystemItem[] DoGetChildItems( FileSystemEventsSession session )

{

throw new NotImplementedException();

}

#endregion AbstractFolder overrides

}

}

VB.NET template

Imports System

Imports System.IO

Imports Xceed.FileSystem

Public Class Class1

Inherits AbstractFolder

'-----------------FileSystemItem overrides-----------------

Protected Overrides Property DoName() As String

Get

Throw New NotImplementedException()

End Get

Set(ByVal Value As String)

Throw New NotImplementedException()

End Set

End Property

Protected Overrides ReadOnly Property DoFullName() As String

Get

Throw New NotImplementedException()

End Get

End Property

Protected Overrides Property DoAttributes() As FileAttributes

Get

Throw New NotImplementedException()

End Get

Set(ByVal Value As FileAttributes)

Throw New NotImplementedException()

End Set

End Property

Protected Overrides Property DoCreationDateTime() As Date

Get

Throw New NotImplementedException()

End Get

Set(ByVal Value As Date)

Throw New NotImplementedException()

End Set

End Property

Protected Overrides Property DoLastWriteDateTime() As Date

Get

Throw New NotImplementedException()

End Get

Set(ByVal Value As Date)

Throw New NotImplementedException()

End Set

End Property

Protected Overrides Property DoLastAccessDateTime() As Date

Get

Throw New NotImplementedException()

End Get

Set(ByVal Value As Date)

Throw New NotImplementedException()

End Set

End Property

Protected Overrides ReadOnly Property DoParentFolder() As AbstractFolder

Get

Throw New NotImplementedException()

End Get

End Property

Protected Overrides ReadOnly Property DoRootFolder() As AbstractFolder

Get

Throw New NotImplementedException()

End Get

End Property

Protected Overrides ReadOnly Property DoExists() As Boolean

Get

Throw New NotImplementedException()

End Get

End Property

Protected Overrides Sub DoRefresh(ByVal session As FileSystemEventsSession)

Throw New NotImplementedException()

End Sub

Protected Overrides Sub DoCreate(ByVal session As FileSystemEventsSession)

Throw New NotImplementedException()

End Sub

Protected Overrides Sub DoDelete(ByVal session As FileSystemEventsSession)

Throw New NotImplementedException()

End Sub

Protected Overrides Sub DoCopyTo(ByVal session As FileSystemEventsSession, ByVal destination As FileSystemItem, ByVal replaceExistingFiles As Boolean)

Throw New NotImplementedException()

End Sub

Protected Overrides Function IsSameAs(ByVal target As FileSystemItem) As Boolean

Throw New NotImplementedException()

End Function

Protected Overrides Function IsPathRooted(ByVal path As String) As Boolean

Throw New NotImplementedException()

End Function

'-----------------FileSystemItem overrides-----------------

'-----------------AbstractFolder overrides-----------------

Protected Overrides Function DoGetFile(ByVal session As FileSystemEventsSession, ByVal fileName As String) As AbstractFile

Throw New NotImplementedException()

End Function

Protected Overrides Function DoGetFolder(ByVal session As FileSystemEventsSession, ByVal folderName As String) As AbstractFolder

Throw New NotImplementedException()

End Function

Protected Overrides Function DoGetChildItems(ByVal session As FileSystemEventsSession) As FileSystemItem()

Throw New NotImplementedException()

End Function

'-----------------AbstractFolder overrides-----------------

End Class


AbstractFile derived class

Introduction

The following code provides a template of all the methods and properties that need to be overridden when creating a class that derives from the AbstractFile class.

C# template

using System;

using System.IO;

using Xceed.FileSystem;

namespace ClassLibrary1

{

public class Class2 : AbstractFile

{

public Class2()

{

//

// TODO: Add constructor logic here

//

}

#region FileSystemItem overrides

protected override string DoName

{

get

{

throw new NotImplementedException();

}

set

{

throw new NotImplementedException();

}

}

protected override string DoFullName

{

get

{

throw new NotImplementedException();

}

}

protected override FileAttributes DoAttributes

{

get

{

throw new NotImplementedException();

}

set

{

throw new NotImplementedException();

}

}

protected override DateTime DoCreationDateTime

{

get

{

throw new NotImplementedException();

}

set

{

throw new NotImplementedException();

}

}

protected override DateTime DoLastWriteDateTime

{

get

{

throw new NotImplementedException();

}

set

{

throw new NotImplementedException();

}

}

protected override DateTime DoLastAccessDateTime

{

get

{

throw new NotImplementedException();

}

set

{

throw new NotImplementedException();

}

}

protected override AbstractFolder DoParentFolder

{

get

{

throw new NotImplementedException();

}

}

protected override AbstractFolder DoRootFolder

{

get

{

throw new NotImplementedException();

}

}

protected override bool DoExists

{

get

{

throw new NotImplementedException();

}

}

protected override void DoRefresh( FileSystemEventsSession session )

{

throw new NotImplementedException();

}

protected override void DoCreate( FileSystemEventsSession session )

{

throw new NotImplementedException();

}

protected override void DoDelete( FileSystemEventsSession session )

{

throw new NotImplementedException();

}

protected override void DoCopyTo( FileSystemEventsSession session, FileSystemItem destination, bool replaceExistingFiles )

{

throw new NotImplementedException();

}

protected override bool IsSameAs( FileSystemItem target )

{

throw new NotImplementedException();

}

protected override bool IsPathRooted( string path )

{

throw new NotImplementedException();

}

#endregion FileSystemItem overrides

#region AbstractFile overrides

protected override long DoSize

{

get

{

throw new NotImplementedException();

}

}

protected override Stream DoOpenRead( FileSystemEventsSession session, FileShare share )

{

throw new NotImplementedException();

}

protected override Stream DoOpenWrite( FileSystemEventsSession session, bool overwrite, FileShare share )

{

throw new NotImplementedException();

}

#endregion AbstractFile overrides

}

}

VB.NET template

Imports System

Imports System.IO

Imports Xceed.FileSystem

Public Class Class2

Inherits AbstractFile

'-----------------FileSystemItem overrides-----------------

Protected Overrides Property DoName() As String

Get

Throw New NotImplementedException()

End Get

Set(ByVal Value As String)

Throw New NotImplementedException()

End Set

End Property

Protected Overrides ReadOnly Property DoFullName() As String

Get

Throw New NotImplementedException()

End Get

End Property

Protected Overrides Property DoAttributes() As FileAttributes

Get

Throw New NotImplementedException()

End Get

Set(ByVal Value As FileAttributes)

Throw New NotImplementedException()

End Set

End Property

Protected Overrides Property DoCreationDateTime() As Date

Get

Throw New NotImplementedException()

End Get

Set(ByVal Value As Date)

Throw New NotImplementedException()

End Set

End Property

Protected Overrides Property DoLastWriteDateTime() As Date

Get

Throw New NotImplementedException()

End Get

Set(ByVal Value As Date)

Throw New NotImplementedException()

End Set

End Property

Protected Overrides Property DoLastAccessDateTime() As Date

Get

Throw New NotImplementedException()

End Get

Set(ByVal Value As Date)

Throw New NotImplementedException()

End Set

End Property

Protected Overrides ReadOnly Property DoParentFolder() As AbstractFolder

Get

Throw New NotImplementedException()

End Get

End Property

Protected Overrides ReadOnly Property DoRootFolder() As AbstractFolder

Get

Throw New NotImplementedException()

End Get

End Property

Protected Overrides ReadOnly Property DoExists() As Boolean

Get

Throw New NotImplementedException()

End Get

End Property

Protected Overrides Sub DoRefresh(ByVal session As FileSystemEventsSession)

Throw New NotImplementedException()

End Sub

Protected Overrides Sub DoCreate(ByVal session As FileSystemEventsSession)

Throw New NotImplementedException()

End Sub

Protected Overrides Sub DoDelete(ByVal session As FileSystemEventsSession)

Throw New NotImplementedException()

End Sub

Protected Overrides Sub DoCopyTo(ByVal session As FileSystemEventsSession, ByVal destination As FileSystemItem, ByVal replaceExistingFiles As Boolean)

Throw New NotImplementedException()

End Sub

Protected Overrides Function IsSameAs(ByVal target As FileSystemItem) As Boolean

Throw New NotImplementedException()

End Function

Protected Overrides Function IsPathRooted(ByVal path As String) As Boolean

Throw New NotImplementedException()

End Function

'-----------------FileSystemItem overrides-----------------

'-----------------AbstractFile overrides-----------------

Protected Overrides ReadOnly Property DoSize() As Long

Get

Throw New NotImplementedException()

End Get

End Property

Protected Overrides Function DoOpenRead(ByVal session As FileSystemEventsSession, ByVal share As FileShare) As Stream

Throw New NotImplementedException()

End Function

Protected Overrides Function DoOpenWrite(ByVal session As FileSystemEventsSession, ByVal overwrite As Boolean, ByVal share As FileShare) As Stream

Throw New NotImplementedException()

End Function

'-----------------AbstractFile overrides-----------------

End Class


Event class

Introduction

The following code provides a basic template for implementing custom events.

C# template

using System;

using Xceed.FileSystem;

namespace ClassLibrary1

{

public delegate void MyProgressionEventHandler( object sender, ItemProgressionEventArgs e );

public class MyEvents : FileSystemEvents

{

public event MyProgressionEventHandler MyProgression;

public override FileSystemEventsSession CreateSession( object sender, object userData )

{

return new MyEventsSession( this, sender, userData );

}

protected internal virtual bool WantsMyProgression

{

get { return ( this.MyProgression != null ); }

}

protected internal virtual void OnMyProgression( object sender, ItemProgressionEventArgs e )

{

this.ValidateParams( sender, e );

if( this.MyProgression != null )

this.MyProgression( sender, e );

}

}

public class MyEventsSession : FileSystemEventsSession

{

protected internal MyEventsSession( MyEvents events, object sender, object userData )

: base( ( FileSystemEvents )events, sender, userData )

{

}

public void OnMyProgression( ItemProgressionEventArgs e )

{

MyEvents events = ( MyEvents )m_events;

if( events.WantsMyProgression )

{

events.OnMyProgression( m_sender, e );

}

}

}

}


Introduction to the Xceed FileSystem namespace

Xceed.FileSystem Namespace

Introduction to the Xceed.FileSystem Namespace

Introduction

The Xceed.FileSystem namespace (represented in blue) provides classes that implement generic methods for handling abstract files and folders as well as methods to handle files and folders located on disk. The class library regroups the FileSystemItem abstract class which represents the root class for all types of files and folders, the AbstractFile abstract class which represents a generic file and the AbstractFolder abstract class which represents a generic folder. It also includes the DiskFile class which represents a disk file and the DiskFolder class which represents disk folder.

The FileSystemItem, AbstractFile and AbstractFolder classes, by themselves cannot be instantiated. In order to actually create an instance of a file or folder, a class that derives from one of these base classes must be used. Since these bases classes are abstract and do not know the kind of files and folders being manipulated, it becomes very easy to derive from these classes and extend the possibilities in regards to file and folder manipulation. For example, a class could derive from the AbstractFile class to handle files in Visual SourceSafe™ or SharePoint Server™.

Xceed currently provides classes to manipulate items contained within zip files and classes to manipulate items located on disk. Plans are also under way to provide classes that can manipulate items located on FTP servers.

The following diagram illustrates the class hierarchy of the Xceed.FileSystem namespace:

FileSystemItem class

The FileSystemItem class is the root class for all types of items (file or folder) that can exist in a generic folder. It exposes, via properties and methods, what a file and a folder have in common (attributes, date, name, etc...). Both the AbstractFile and AbstractFolder classes derive and inherit methods from this class.

AbstractFile class

The AbstractFile class represents a generic file. It exposes properties and methods that are common only to files, namely reading data from and writing data to files. The DiskFile class and the ZippedFile class of the Xceed.Zip namespace both derive and inherit methods from this abstract class.

AbstractFolder class

The AbstractFolder class represents a generic folder, which can contain FileSystemItem objects. It exposes properties and methods that are common to all types of folders. The DiskFolder class as well as the ZipArchive and ZippedFolder classes of the Xceed.Zip namespace (represented in green) all derive and inherit methods from this abstract class.

DiskFile class

The DiskFile class is a specialization of the AbstractFile class that represents a disk file and exposes properties and methods that provide access to a disk file.

DiskFolder class

The DiskFolder class is a specialization of the AbstractFolder that represents a disk folder and exposes properties and methods that provide access to a disk folder.


Full Template

Xceed.FileSystem 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