How to: Configure FileSystemWatcher Component Instances

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

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.

Specifying the Directories to Watch

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

To indicate the fully qualified path of the root directory to watch

• Set the Path property on an existing component instance, as shown in the following code:

  Dim MyWatcher As New System.IO.FileSystemWatcher()
  MyWatcher.Path = "c:\"
  

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

  This setting can be in standard directory path notation (c:\directory) or in UNC format (\\server\directory).

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 subdirectories as it does within the main directory the component is watching.

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 are interested in watching for. In part, you determine the changes to watch for by defining handlers for only those events in which you are 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 particular file or 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 set the filter to any value, including all valid files extensions. The default value "*.*" returns everything; "" (an empty string) also returns all files or directories. However, you can only set one filter string at a time. If you need to, you can change the filter after the FileSystemWatcher has started to receive events.

You can also use the NotifyFilter property to further restrict the changes that are reacted to. You can set the NotifyFilter property to watch for changes to directory names, files names, or both. In addition, the NotifyFilter property contains a series of values that restrict the Changed event. 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 copying 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 NotifyFilter property limits the number of file or directory changes for which the component instance will raise events. You can set up your component so that it will raise events only when a file or directory name changes, when the attributes of an item in the main directory change, when a file's size changes, when its last write or last access time changes, or when security access to a file or directory rights change. These values are all part of the NotifyFilters enumeration. You can set multiple changes to watch for by using a BitOr (for Visual Basic) or | (for Visual C#) operator, as shown in the example below.

To configure an instance of the FileSystemWatcher component

1. Create an instance of the FileSystemWatcher component. For more information, see How to: Create FileSystemWatcher Component Instances.

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 to a specific file or subdirectory name within the root	Filter	A wildcard filter expression that restricts the monitoring activities of the instance
   To watch for changes within any subdirectories the root directory contains	IncludeSubdirectories	true or false
   To watch for only specific changes to a file or subdirectory when handling the Changed, Renamed, Deleted, or Created event	NotifyFilter	Any of the available values in the NotifyFilters enumeration

4. Enable your component instance by setting the EnableRaisingEvents property to true.

   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:

   ' This needs to be declared in a place where it will not go out of scope.
   ' For example, it would be a class variable in a form class.
   Dim MyWatcher As New System.IO.FileSystemWatcher()
   ' This code would go in one of the initialization methods of the class.
   MyWatcher.Path = "c:\"
   ' Watch only for changes to *.txt files.
   MyWatcher.Filter = "*.txt"
   MyWatcher.IncludeSubdirectories = False
   ' Filter for Last Write changes.
   MyWatcher.NotifyFilter = System.IO.NotifyFilters.LastWrite
   ' Example of watching more than one type of change.
   MyWatcher.NotifyFilter =
      System.IO.NotifyFilters.LastAccess Or System.IO.NotifyFilters.Size
   ' Enable the component to begin watching for changes.
   MyWatcher.EnableRaisingEvents = True
   

           // This needs to be declared in a place where it will not go out of scope.
           // For example, it would be a class variable in a form class.
           System.IO.FileSystemWatcher MyWatcher = new System.IO.FileSystemWatcher();
           // This code would go in one of the initialization methods of the class.
           MyWatcher.Path = "c:\\";
           // Watch only for changes to *.txt files.
           MyWatcher.Filter = "*.txt";
           MyWatcher.IncludeSubdirectories = false;
           // Enable the component to begin watching for changes.
           MyWatcher.EnableRaisingEvents = true;
           // Filter for Last Write changes.
           MyWatcher.NotifyFilter = System.IO.NotifyFilters.LastWrite;
           // Example of watching more than one type of change.
           MyWatcher.NotifyFilter =
              System.IO.NotifyFilters.LastWrite | System.IO.NotifyFilters.Size;
   

See Also

Tasks

How to: Create FileSystemWatcher Component Instances

Concepts

Introduction to Monitoring File System Events