The .NET FileSystemWatcher class

A few that spring to mind include:

• Automatically processing or indexing newly created content
• Automatically updating a web site to incorporate new pages (e.g. adding them to an index page or product list)
• Automatically updating a database with information on files in particular locations
• Creating a UI that works like explorer and updates automatically when the filesystem is updated by another application
• Allowing collaborative working by detecting and acting appropriately when another user updates a file

Photo library application

Figure 1: The manual process

Using FileSystemWatcher and the .NET Image class, this process can be automated. We’ll create a command line application for simplicity, but the same code could be used in a Windows Service (or in a Forms application, perhaps with a status display). This service could run on a server and implement the process seamlessly in the background, and while write access to the library could be disabled for normal users, the account running the service would have it enabled. This would prevent users circumventing the correct procedure!

All we need to do is detect the arrival of a file in the “Submit” folder, create copies of it at the appropriate resolutions in the “Presentation” and “Print” folders, and remove the original from the submission folder. To detect the file arriving in “Submit”, we first create a FileSystemWatcher:

static void Main(string[] args)
	{
	FileSystemWatcher f =
		new FileSystemWatcher(
		@”C:\PhotoLibrary\Submit”,
		“*.jpg” );

For this application the Created event is the only one that is of interest, so we need to hook up an event handler. Once we’ve done this, we must set the EnableRaisingEvents property to true to tell the object that we’ve configured it, hooked up our event handlers, and are ready to receive events:

	f.Created += new
		FileSystemEventHandler(
		f_Created);
	f.EnableRaisingEvents = true;

	Console.WriteLine(“Waiting...
		Hit return to quit” );
	Console.Read();
	f.Dispose();
}

Image i = Image.FromFile(e.FullPath);

SaveImageMaxRes(
	@”C:\PhotoLibrary\Presentation\”
	+ e.Name, i, new Size(100, 100));
SaveImageMaxRes(
	@”C:\PhotoLibrary\Print\”
	+ e.Name, i, new Size(200, 200));

i.Dispose();
File.Delete( e.FullPath );
Console.WriteLine(“Completed: “
	+ e.Name);

static void Main(string[] args)
{
	FileSystemWatcher f = new FileSystemWatcher(@”C:\PhotoLibrary\Submit”,
		“*.jpg”);
	f.Created+=new FileSystemEventHandler(f_Created);
	f.EnableRaisingEvents = true;
	Console.WriteLine(“Waiting... Hit return to quit.”);
	Console.Read();
	f.Dispose();
}

private static void f_Created(object sender, FileSystemEventArgs e)
{
	Image i = Image.FromFile(e.FullPath);
	SaveImageMaxRes(@”C:\PhotoLibrary\Presentation\” + e.Name, i,
		new Size(100, 100));
	SaveImageMaxRes(@”C:\PhotoLibrary\Print\” + e.Name, i, new Size(200, 200));
	i.Dispose();
	File.Delete(e.FullPath);
	Console.WriteLine(“Completed: “ + e.Name);
}

static void SaveImageMaxRes(String Path, Image ImageObject, Size MaxSize)
{
	// Calculate the correct sizes for the output image
	Size OutputSize = ImageObject.Size;
	float AspectImage = (float)OutputSize.Height/(float)OutputSize.Width;
	float AspectMax = (float)MaxSize.Height/(float)MaxSize.Width;
	if (AspectMax < AspectImage)
	{
		// Image is TALLER
		OutputSize.Height = MaxSize.Height;
		OutputSize.Width = (int)((float)MaxSize.Height/AspectImage);
	}
	else
	{
		// Image is WIDER
		OutputSize.Width = MaxSize.Width;
		OutputSize.Height = (int)((float)MaxSize.Width * AspectImage);
	}

	// Never scale an image UP in size
	if ((OutputSize.Width > ImageObject.Width) ||
	(OutputSize.Height > ImageObject.Height))
	{
		OutputSize = ImageObject.Size;
	}

	// Create the render canvas
	Bitmap b = new Bitmap(OutputSize.Width, OutputSize.Height, 
		PixelFormat.Format32bppArgb);
	Graphics g = Graphics.FromImage(b);

	// Render
	g.DrawImage(ImageObject, new Rectangle(new Point(0, 0), OutputSize));

	// Output the result as a JPEG
	b.Save(Path, ImageFormat.Jpeg);

	// Tidy Up
	g.Dispose();
	b.Dispose();
}

Figure 2: The command window

This application is a simple example showing how FileSystemWatcher can enable utilities and applications that would have taken a lot of code to develop under Win32. I wrote this application in a single code file with 84 lines – and half of those are whitespace or comments.

Interpreting the notifications received from the FileSystemWatcher is pretty straightforward for an application like this, but some operations may result in more than one notification. For example, if you are monitoring a directory tree and a file is moved from one folder to another, you can expect to see a Deleted notification on the source file, a Created on the destination file, and Changed notification on both the source and destination directories. This can make figuring out what events represent which “user” operation quite complicated.

Change notifications and synchronisation

The most obvious example of a representation of the filesystem would be the visual one – the explorer type view. There are plenty of applications where it is desirable to display lists or trees of files in the application style rather than explorer style, and for these views to update just like explorer does. There are other applications where you might want to keep an HTML page or database updated with information relating to files such as product description pages or photos. It may even be useful to store information about files in a database, and have a server application update the file location in the database when the user moves the file in explorer.

Look at the first snippets of code in Table 2, showing the intuitive approaches to synchronising an in-memory list of files (this.Files) with the filesystem.

FileSystemWatcher f;
DirectoryInfo d;
// Initialise f and d
this.Files = d.GetFiles();
// File "Foo" deleted
f.EnableRaisingEvents = true;

FileSystemWatcher f;
DirectoryInfo d;
// Initialise f and d
f.EnableRaisingEvents = true;
// File "Foo" deleted
this.Files = d.GetFiles();	
// File “Bar” deleted

This list could be databound to a UI control, or used to update an XML database, HTML file, or even a SQL Server database.

The first code snippet will never detect the deletion of the file “Foo” because the change notification is never raised – events have not yet been enabled when the trigger happens. The second snippet shows the obvious way to correct this mistake, but is also flawed. FileSystemWatcher event handlers are called on threads from the System Thread Pool. This means that the event handler for the deletion of file “Foo” could execute before the this.Files property was populated, leaving it with nothing to update! The mechanism for fixing this depends in part on whether the application is a UI application or not.

If this is a UI application, then the event handler calls can be marshalled to the UI thread, as long as the FileSystemWatcher was itself created on the UI thread. To enable this functionality, the SynchronizationObject property must be set to reference the relevant Windows form. Since in this case both the initialisation code and the event handler run on the UI thread, we can guarantee that this.Files will be populated before the event handler runs. FileSystemWatcher appears in the “Components” palette of the Windows Forms editor, and inserting it from there automatically sets SynchronizationObject.

In cases where the application isn’t Windows Forms based (e.g. a Windows Service), we will have to ensure that the initialisation code and event handlers run sequentially on our own.

Even though these methods guarantee that this.Files will have been initialised, there is no way of being sure of whether it contains a reference to the deleted files or not. In the case shown above, the event handler for the deletion of file “Foo” would not find it in the list to be removed, but the handler for file “Bar” will. This means that update logic must take account of the fact that it doesn’t know whether updates are already reflected in the data to be synchronised or not. One possible response to this would be to simply refresh by calling d.GetFiles() again on each change notification as shown here:

void Init()
{
	this.f.Deleted += new
		FileSystemEventHandler(
		f_Deleted);
	lock(this.Files)
	{
		this.f.EnableRaisingEvents
			= true;
		this.Files = d.GetFiles();
	}
}

private void f_Deleted(object sender,
	FileSystemEventArgs e)
{
	lock(this.Files)
	{
		this.Files = d.GetFiles();
		// Update UI, Database etc here
	}
}

The solution shown above will keep the this.Files up to date, but if the file list was very large, or was a tree structure representing a large number of directories, doing a complete refresh could be very inefficient. It may also have negative side effects such as causing display flicker as controls are redrawn, or losing information in a database. In many applications it will therefore be necessary to write code to apply the change manually, e.g. by deleting just the relevant item from the tree control or database. This will tend to result in complex code, and anywhere there is complexity there is scope for bugs to creep in.

Under the hood

In addition to potential overflows caused by inadequate buffer size, the application developer should consider how many notifications their application is likely to receive. In the photo library application above, only a few photos are added to the library each week, but if you want to design an application that monitors the whole of a network drive shared amongst hundreds of users, you could face hundreds or even thousands of notifications each minute. You must ensure that your application can cope with the volume of notifications!

The ReadDirectoryChangesW API is used by Windows Explorer to monitor for directory changes, and is designed not to create huge quantities of network traffic. As such, it uses notifications of change rather than polling to identify when changes occur, and so can safely be used across a network.

Conclusions

It turns out, however, that or applications such as keeping a user interface up to date, or synchronising database information with the filesystem, the code needed to interpret information from the FileSystemWatcher correctly will be complex. In an ideal world the System.IO namespace would support a mechanism for automatically keeping UI up to date with filesystem information, perhaps through data binding. It would also be nice to have a mechanism that allowed you to snapshot a view of a file or directory at the point that the EnableRaisingEvents was turned on, so that your own code knew that changes received subsequently applied to the returned data. Finally, it would be great if the class supported synchronisation in non-UI cases, perhaps by using Monitor itself! With the addition of these features, I believe that the usefulness of FileSystemWatcher would be substantially improved._