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.
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.
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.
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
Tip You can enter this as a standard file path or a UNC path.
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 |
Creating FileSystemWatcher Component Instances | Introduction to File System Components