FileSystemWatcher.txt

----------
20191220

FileSystemWatcher Class

Namespace:  System.IO 
Assemblies: System.IO.FileSystem.Watcher.dll, System.dll, netstandard.dll
Listens to the file system change notifications and raises events when a directory, or file in a directory, changes.


Examples

The following example creates a FileSystemWatcher to watch the directory specified at run time. The component is set to watch for changes in LastWrite and LastAccess time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console.
以下範例可監視指定目錄中所有的文字檔案, 變更 LastWrite 或 LastAccess 時間, 新增, 刪除, 改名時的異動. 若檔案修改、新建、或刪除時, 會顯示檔案路徑. 若檔名修改時, 則會顯示新舊檔案路徑.

using System;
using System.IO;
using System.Security.Permissions;

public class Watcher
{
    public static void Main()
    {
        Run();
    }

    [PermissionSet(SecurityAction.Demand, Name = "FullTrust")]
    private static void Run()
    {
        string[] args = Environment.GetCommandLineArgs();

        // If a directory is not specified, exit program.
        if (args.Length != 2)
        {
            // Display the proper way to call the program.
            Console.WriteLine("Usage: Watcher.exe (directory)");
            return;
        }

        // Create a new FileSystemWatcher and set its properties.
        using (FileSystemWatcher watcher = new FileSystemWatcher())
        {
            watcher.Path = args[1];

            // Watch for changes in LastAccess and LastWrite times, and
            // the renaming of files or directories.
            watcher.NotifyFilter = NotifyFilters.LastAccess
                                 | NotifyFilters.LastWrite
                                 | NotifyFilters.FileName
                                 | NotifyFilters.DirectoryName;

            // Only watch text files.
            watcher.Filter = "*.txt";

            // Add event handlers.
            watcher.Changed += OnChanged;
            watcher.Created += OnChanged;
            watcher.Deleted += OnChanged;
            watcher.Renamed += OnRenamed;

            // Begin watching.
            watcher.EnableRaisingEvents = true;

            // Wait for the user to quit the program.
            Console.WriteLine("Press 'q' to quit the sample.");
            while (Console.Read() != 'q') ;
        }
    }

    // Define the event handlers.
    private static void OnChanged(object source, FileSystemEventArgs e) =>
        // Specify what is done when a file is changed, created, or deleted.
        Console.WriteLine($"File: {e.FullPath} {e.ChangeType}");

    private static void OnRenamed(object source, RenamedEventArgs e) =>
        // Specify what is done when a file is renamed.
        Console.WriteLine($"File: {e.OldFullPath} renamed to {e.FullPath}");
}

Remarks

Use FileSystemWatcher to watch for changes in a specified directory. You can watch for changes in files and subdirectories of the specified directory. You can create a component to watch files on a local computer, a network drive, or a remote computer.
透過 FileSystemWatcher 可監視指定檔案目錄中的變更. 可監視檔案或子目錄. 可監視本機、網路磁碟機、或遠端電腦. 

To watch for changes in all files, set the Filter property to an empty string ("") or use wildcards ("*.*"). To watch a specific file, set the Filter property to the file name. For example, to watch for changes in the file MyDoc.txt, set the Filter property to "MyDoc.txt". You can also watch for changes in a certain type of file. For example, to watch for changes in text files, set the Filter property to "*.txt".
可透過設定 Filter 屬性為 ""空白字串或 "*.*" 選擇監視檔案. 例如: "MyDoc.txt", "*.txt"...


There are several types of changes you can watch for in a directory or file. For example, you can watch for changes in Attributes, the LastWrite date and time, or the Size of files or directories. This is done by setting the NotifyFilter property to one of the NotifyFilters values. For more information on the type of changes you can watch, see NotifyFilters.
可以監視不同屬性的檔案. 例如: LastWrite 最後寫入時間, size 檔案大小. 
都是經由設定 NotifyFilter 屬性指定監視的範圍.

You can watch for renaming, deletion, or creation of files or directories. For example, to watch for renaming of text files, set the Filter property to "*.txt" and call the WaitForChanged method with a Renamed specified for its parameter.
可以監視 改名、刪除、或新建(檔案或目錄). 例如, 若要監視文字檔案改名, 則可設定 Filter 屬性為 "*.txt" 再以呼叫 WaitForChanged 方法

The Windows operating system notifies your component of file changes in a buffer created by the FileSystemWatcher. If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer with the InternalBufferSize property is expensive, as it comes from non-paged memory that cannot be swapped out to disk, so keep the buffer as small yet large enough to not miss any file change events. To avoid a buffer overflow, use the NotifyFilter and IncludeSubdirectories properties so you can filter out unwanted change notifications.
Windows 作業系統會經由 FileSystemWatcher 建立的緩衝區通知你的元件. 若短時間內有太多異動, 則緩衝區將會溢位, 這會造成元件漏接變更的訊息, 僅送出空白訊息. 加大緩衝區 InternalBufferSize 屬性大小是昂貴的. 因為緩衝區是 non-paged 記憶體, 無法交換到磁碟機, 必須保持緩衝區盡量小且夠大不會遺失訊息. 要避免緩衝區溢位, 可利用 NotifyFilter 及 IncludeSubdirectories 屬性來過濾不需要的通知.

For a list of initial property values for an instance of FileSystemWatcher, see the FileSystemWatcher constructor.
Please note the following when using the FileSystemWatcher class.
Hidden files are not ignored.
In some systems, FileSystemWatcher reports changes to files using the short 8.3 file name format. For example, a change to "LongFileName.LongExtension" could be reported as "LongFil~.Lon".
This class contains a link demand and an inheritance demand at the class level that applies to all members. A SecurityException is thrown when either the immediate caller or the derived class does not have full-trust permission. For details about security demands, see Link Demands.
The maximum size you can set for the InternalBufferSize property for monitoring a directory over the network is 64 KB.
 Note
以下為使用 FileSystemWatcher 元件需要注意:
1. 隱藏檔案仍會監視.
2. 某些系統, 會以8.3的檔案名稱格式通知. 例如: "LongFileName.LongExtension" 檔案名稱會變成 "LongFil~.Lon".
3. 元件包含一個連結需求 以及 繼承需求 將運行於全部的成員. 當無法取得檔案授權時, 會拋出 SecurityException.
4. 監視網路目錄可設定緩衝區上限為 64 KB.


 
Running FileSystemWatcher on Windows 98 is not supported.


Copying and moving folders
複製及搬移目錄

The operating system and FileSystemWatcher object interpret a cut-and-paste action or a move action as a rename action for a folder and its contents. If you cut and paste a folder with files into a folder being watched, the FileSystemWatcher object reports only the folder as new, but not its contents because they are essentially only renamed.
作業系統 及 FileSystemWatcher 會將(剪貼檔案 或 搬移檔案) 視為 (檔案名稱變更). 若從其他位置 (剪貼檔案) 到監視的目錄中, 則 FileSystemWatcher 會通知為新建, 而非目錄內容, 因為本質上這只是檔案名稱變更.

To be notified that the contents of folders have been moved or copied into a watched folder, provide OnChanged and OnRenamed event handler methods as suggested in the following table.
為了要接收監視目錄中的檔案是否(被移出 或 複製進來), 可利用 (OnChanged 及 OnRenamed) 事件如下建議表:
Event Handler  Events Handled             Performs
OnChanged      Changed, Created, Deleted  Report changes in file attributes, created files, and deleted files.
OnRenamed      Renamed                    List the old and new paths of renamed files and folders, expanding recursively if needed.


Events and Buffer Sizes
通知事件及緩衝區大小

Note that several factors can affect which file system change events are raised, as described by the following:
以下為影響檔案異動訊息的因素:

Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several OnChanged and some OnCreated and OnDeleted events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by FileSystemWatcher.
共用檔案系統可能會發出多訊息. 例如當檔案從不同目錄搬移時, 會發出好幾個 OnChanged, OnCreated, OnDeleted 訊息. 搬移檔案是複雜的作業, 由多個單一作業組成, 因此會發出多個事件通知. 此外, 有些程式(例如防毒軟體), 也會導致額外的檔案變更異動通知訊息. 

The FileSystemWatcher can watch disks as long as they are not switched or removed. The FileSystemWatcher does not raise events for CDs and DVDs, because time stamps and properties cannot change. Remote computers must have one of the required platforms installed for the component to function properly.
FileSystemWatcher 可以監視磁碟機直到被切換或被移除為止. 因為 CD 跟 DVD 的檔案屬性不會變動, 因此也不會發出通知. 遠端電腦則需要也安裝相同的元件才能作業.

If multiple FileSystemWatcher objects are watching the same UNC path in Windows XP prior to Service Pack 1, or Windows 2000 SP2 or earlier, then only one of the objects will raise an event. On machines running Windows XP SP1 and newer, Windows 2000 SP3 or newer or Windows Server 2003, all FileSystemWatcher objects will raise the appropriate events.
若多個 FileSystemWatcher 監視相同的 UNC 路徑時, 在早期的版本(XP等系統)只有其中一個會發出通知. 新的版本則都會發出通知.

Note that a FileSystemWatcher may miss an event when the buffer size is exceeded. To avoid missing events, follow these guidelines:
注意 FileSystemWatcher 在緩衝區大小超出時, 可能會遺失接收訊息. 可以下面的原則解決:

Increase the buffer size by setting the InternalBufferSize property.
經由 InternalBufferSize 加大緩衝區大小

Avoid watching files with long file names, because a long file name contributes to filling up the buffer. Consider renaming these files using shorter names.
避免監視太長的檔案名稱. 長檔名會占用緩衝區較多. 可評估改名為較小的檔案名稱.

Keep your event handling code as short as possible.
盡快處理完你的 Event.