FileSystemWatcher pitfalls

I am working on a C# program that needs to use the FileSystemWatcher class so it will be notified when new files are created. As part of the initialization, the program scans the directory so it can process any files that already exist in it. This is all working fine.

However, in a discussion with another developer, we started questioning whether this will always work. Are there conditions under which the FileSystemWatcher will miss the creation of files? If so, what are these conditions?

In order to handle this scenario, we would just run the code in our initialization process that scans the directory periodically, but how likely is it for the FileSystemWatcher to miss files?

Solution

FileSystemWatcher will not usually miss files. However:

since it's based on ReadDirectoryChangesW, it only detects changes to the file's directory entry, not changes to the file itself. Most changes to the file will update the directory entry, but there are a few exceptions (see this article).
the buffer for file change notifications has a limited size; if you don't process the events fast enough, the buffer will overflow, causing you to miss events. That's why you should not do any heavy processing in the event handler; if you can't handle the events fast enough, just add them to a queue that you process on another thread.

Other pitfalls:

The notifications don't arrive instantly; the delay between the actual change and the notification is usually very short, but I've seen it grow to as long as several seconds. This is not a major issue for most use cases, but depending on what you're trying to do, it could be a problem.
There is no event for Moved. If you move a file from a directory to another, you will receive two notifications : Deleted and Created
Sometimes, depending on the volume configuration, the paths in the notifications can be in the old 8.3 format (e.g. you can get SOMETH~1.TXT instead of Something.txt)
If you move an existing, non-empty directory into the watched directory, you will only get a notification for the directory itself, not its content. You will need to examine the content manually.
Changed events can occur several times for the same file; you need to handle the duplicates yourself