NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Configuring FileSystemWatcher Component Instances

There are several properties you set for your FileSystemWatcher component instances to determine how they behave. These properties determine what directories and subdirectories the component instance will monitor and the exact occurrences within those directories that will raise events.

Indicating the Directories to Watch

You use two properties to determine what directories the FileSystemWatcher component should watch: Path, and IncludeSubdirectories.

Path indicates the fully qualified path of the root directory you want to watch. This can be in standard directory path notation (c:\directory) or in UNC format (\\server\directory). You can set the Path property on an existing component instance, as shown in the following code:

[Visual Basic]

Dim MyWatcher as New System.IO.FileSystemWatcher
MyWatcher.Path = "c:\"

[C#]

System.IO.FileSystemWatcher MyWatcher = new System.IO.FileSystemWatcher("c:\\");

Or you can use a special constructor for the FileSystemWatcher component that takes the path as a parameter. In that case, your code would look like this:

[Visual Basic]
Dim MyWatcher as New System.IO.FileSystemWatcher("c:\")
[C#]
System.IO.FileSystemWatcher MyWatcher = new System.IO.FileSystemWatcher();
MyWatcher.Path = "c:\\";

The IncludeSubdirectories property indicates whether subdirectories within the root directory should be monitored. If the property is set to true, the component watches for the same changes in the subdirectory as it does in the root.

Specifying the Changes to Watch

In addition to specifying the directories and subdirectories to watch, you can indicate what specific files and types of changes you’re interested in watching for. In part, you determine the changes to watch for by defining handlers for only those events in which you’re interested. For example, if you only want to be notified when files are created, you would only handle the Created event. However, you can set a series of properties that restrict the component’s activities even further.

You can use the Filter property to indicate a wildcard matching pattern that restricts the component to watching only certain files or directories within the root directory. For example, if you want to watch for the creation of text files within the root, you could set the Filter property to “*.txt” and then create a handler for the Created event.

You can use the Target property to indicate whether the component should watch for changes to files within the root, files and directories within the root, or directories only. This narrows the scope of events that the component raises. By default, the Target property is set to watch for changes to both directory and file-level items.

Note   Whenever the FileSystemWatcher component records a change in the root directory, it raises an event that is stored in an internal buffer. This buffer has a size limit and might overflow. You can use the Target property to reduce the number of events that are stored in the buffer. The Filter property does not affect the number of events stored in the buffer as it is applied after events are recorded. For more information, see Managing File Changes on High-Volume Systems.

Limiting the Scope of the Changed Event Handler

If one of the events you are handling in your code is the Changed event, you can use the ChangedFilter property to further limit the number of events the component instance will raise. The Changed event has the potential to raise a large number of events, because it will raise an event each time any change is made to the file in question; some standard operations like creating and moving files will actually cause several file change events to be raised as various attributes such as size, last write, and last access are altered.

The ChangedFilter property limits the number of file or directory changes for which the component will raise events. You can set up your component so that it will raise events only when an item in the root directory has its attributes change, when its size changes, when its last write or last access time changes, or when security changes. These values are all part of the ChangedFilter enumeration.

These properties all work together to determine how the FileSystemWatcher component behaves. For example, suppose you want to create a FileSystemWatcher instance that watches a drop directory called “reports” for the creation of new .txt files. You also want to monitor changes to existing reports that rerun dynamically when data changes. You would set up your component as follows:

[Visual Basic]
'Create a component instance and set its root path to the local c:\ drive.
Dim MyWatcher as New FileSystemWatcher
MyWatcher.Path = "c:\"
'Watch for changes only to *.txt files or directories
MyWatcher.Filter = "*.txt"
'Only pay attention to files, not directories or subdirectories
MyWatcher.Target = "File"
MyWatcher.IncludeSubdirectories = "False"
'Filter for Last Write changes
MyWatcher.ChangedFilter = ChangedFilters.LastWrite
[C#]
// Create a component instance and set its root path to the local c:\ drive.
FileSystemWatcher MyWatcher = new FileSystemWatcher();
MyWatcher.Path = "c:\\";
// Watch for changes only to *.txt files or directories
MyWatcher.Filter = "*.txt";
// Only pay attention to files, not directories or subdirectories
MyWatcher.Target = "File";
MyWatcher.IncludeSubdirectories = "False";
// Filter for Last Write changes
MyWatcher.ChangedFilter = ChangedFilters.LastWrite;

To configure an instance of the FileSystemWatcher component

  1. Create an instance of the FileSystemWatcher component. For details, see Creating FileSystemWatcher Components.
  2. Set the Path property to the fully qualified path of the root directory you want to watch.
    Tip   You can enter this as a standard file path or a UNC path.
  3. Set any of the optional properties for your instance.
    Scenario Property Value
    To watch for changes of a specific file or directory type Filter A wildcard filter expression that restricts the monitoring activities of the instance
    To watch for changes to files only, directories only, or both Target File, Directory, or Both
    To watch for changes within any subdirectories the root director contains IncludeSubdirectories true or false
    To watch for only specific changes to a file or directory when handling the Changed event ChangedFilter Attributes, LastAccess, LastWrite, Security, or Size
  4. Enable your component instance by setting the Enabled property to true.

See Also

Creating FileSystemWatcher Component Instances | Introduction to File System Components