FileSystemWatcher 類別

定義

命名空間:

System.IO

組件:

System.IO.FileSystem.Watcher.dll

當目錄或目錄內的檔案變更時，接聽 (Listen) 檔案系統變更通知並引發事件。

public ref class FileSystemWatcher : System::ComponentModel::Component, System::ComponentModel::ISupportInitialize

public class FileSystemWatcher : System.ComponentModel.Component, System.ComponentModel.ISupportInitialize

type FileSystemWatcher = class
    inherit Component
    interface ISupportInitialize

Public Class FileSystemWatcher
Inherits Component
Implements ISupportInitialize

繼承

Object

MarshalByRefObject

Component

FileSystemWatcher

實作

ISupportInitialize

範例

下列範例會 FileSystemWatcher 建立 ，以watch執行時間指定的目錄。 元件會設定為watch，以取得和 LastAccess 時間中的 LastWrite 變更、建立、刪除或重新命名目錄中的文字檔。 如果檔案已變更、建立或刪除，檔案的路徑會列印至主控台。 重新命名檔案時，舊路徑和新路徑會列印到主控台。

#include "pch.h"

using namespace System;
using namespace System::IO;

class MyClassCPP
{
public:

    int static Run()
    {
        FileSystemWatcher^ watcher = gcnew FileSystemWatcher("C:\\path\\to\\folder");

        watcher->NotifyFilter = static_cast<NotifyFilters>(NotifyFilters::Attributes
                                                         | NotifyFilters::CreationTime
                                                         | NotifyFilters::DirectoryName
                                                         | NotifyFilters::FileName
                                                         | NotifyFilters::LastAccess
                                                         | NotifyFilters::LastWrite
                                                         | NotifyFilters::Security
                                                         | NotifyFilters::Size);

        watcher->Changed += gcnew FileSystemEventHandler(MyClassCPP::OnChanged);
        watcher->Created += gcnew FileSystemEventHandler(MyClassCPP::OnCreated);
        watcher->Deleted += gcnew FileSystemEventHandler(MyClassCPP::OnDeleted);
        watcher->Renamed += gcnew RenamedEventHandler(MyClassCPP::OnRenamed);
        watcher->Error   += gcnew ErrorEventHandler(MyClassCPP::OnError);

        watcher->Filter = "*.txt";
        watcher->IncludeSubdirectories = true;
        watcher->EnableRaisingEvents = true;

        Console::WriteLine("Press enter to exit.");
        Console::ReadLine();

        return 0;
    }

private:

    static void OnChanged(Object^ sender, FileSystemEventArgs^ e)
    {
        if (e->ChangeType != WatcherChangeTypes::Changed)
        {
            return;
        }
        Console::WriteLine("Changed: {0}", e->FullPath);
    }

    static void OnCreated(Object^ sender, FileSystemEventArgs^ e)
    {
        Console::WriteLine("Created: {0}", e->FullPath);
    }

    static void OnDeleted(Object^ sender, FileSystemEventArgs^ e)
    {
        Console::WriteLine("Deleted: {0}", e->FullPath);
    }

    static void OnRenamed(Object^ sender, RenamedEventArgs^ e)
    {
        Console::WriteLine("Renamed:");
        Console::WriteLine("    Old: {0}", e->OldFullPath);
        Console::WriteLine("    New: {0}", e->FullPath);
    }

    static void OnError(Object^ sender, ErrorEventArgs^ e)
    {
        PrintException(e->GetException());
    }

    static void PrintException(Exception^ ex)
    {
        if (ex != nullptr)
        {
            Console::WriteLine("Message: {0}", ex->Message);
            Console::WriteLine("Stacktrace:");
            Console::WriteLine(ex->StackTrace);
            Console::WriteLine();
            PrintException(ex->InnerException);
        }
    }
};


int main()
{
    MyClassCPP::Run();
}

using System;
using System.IO;

namespace MyNamespace
{
    class MyClassCS
    {
        static void Main()
        {
            using var watcher = new FileSystemWatcher(@"C:\path\to\folder");

            watcher.NotifyFilter = NotifyFilters.Attributes
                                 | NotifyFilters.CreationTime
                                 | NotifyFilters.DirectoryName
                                 | NotifyFilters.FileName
                                 | NotifyFilters.LastAccess
                                 | NotifyFilters.LastWrite
                                 | NotifyFilters.Security
                                 | NotifyFilters.Size;

            watcher.Changed += OnChanged;
            watcher.Created += OnCreated;
            watcher.Deleted += OnDeleted;
            watcher.Renamed += OnRenamed;
            watcher.Error += OnError;

            watcher.Filter = "*.txt";
            watcher.IncludeSubdirectories = true;
            watcher.EnableRaisingEvents = true;

            Console.WriteLine("Press enter to exit.");
            Console.ReadLine();
        }

        private static void OnChanged(object sender, FileSystemEventArgs e)
        {
            if (e.ChangeType != WatcherChangeTypes.Changed)
            {
                return;
            }
            Console.WriteLine($"Changed: {e.FullPath}");
        }

        private static void OnCreated(object sender, FileSystemEventArgs e)
        {
            string value = $"Created: {e.FullPath}";
            Console.WriteLine(value);
        }

        private static void OnDeleted(object sender, FileSystemEventArgs e) =>
            Console.WriteLine($"Deleted: {e.FullPath}");

        private static void OnRenamed(object sender, RenamedEventArgs e)
        {
            Console.WriteLine($"Renamed:");
            Console.WriteLine($"    Old: {e.OldFullPath}");
            Console.WriteLine($"    New: {e.FullPath}");
        }

        private static void OnError(object sender, ErrorEventArgs e) =>
            PrintException(e.GetException());

        private static void PrintException(Exception? ex)
        {
            if (ex != null)
            {
                Console.WriteLine($"Message: {ex.Message}");
                Console.WriteLine("Stacktrace:");
                Console.WriteLine(ex.StackTrace);
                Console.WriteLine();
                PrintException(ex.InnerException);
            }
        }
    }
}

Imports System.IO

Namespace MyNamespace

    Class MyClassVB

        Shared Sub Main()
            Using watcher = New FileSystemWatcher("C:\path\to\folder")
                watcher.NotifyFilter = NotifyFilters.Attributes Or
                                       NotifyFilters.CreationTime Or
                                       NotifyFilters.DirectoryName Or
                                       NotifyFilters.FileName Or
                                       NotifyFilters.LastAccess Or
                                       NotifyFilters.LastWrite Or
                                       NotifyFilters.Security Or
                                       NotifyFilters.Size

                AddHandler watcher.Changed, AddressOf OnChanged
                AddHandler watcher.Created, AddressOf OnCreated
                AddHandler watcher.Deleted, AddressOf OnDeleted
                AddHandler watcher.Renamed, AddressOf OnRenamed
                AddHandler watcher.Error, AddressOf OnError

                watcher.Filter = "*.txt"
                watcher.IncludeSubdirectories = True
                watcher.EnableRaisingEvents = True

                Console.WriteLine("Press enter to exit.")
                Console.ReadLine()
            End Using
        End Sub

        Private Shared Sub OnChanged(sender As Object, e As FileSystemEventArgs)
            If e.ChangeType <> WatcherChangeTypes.Changed Then
                Return
            End If
            Console.WriteLine($"Changed: {e.FullPath}")
        End Sub

        Private Shared Sub OnCreated(sender As Object, e As FileSystemEventArgs)
            Dim value As String = $"Created: {e.FullPath}"
            Console.WriteLine(value)
        End Sub

        Private Shared Sub OnDeleted(sender As Object, e As FileSystemEventArgs)
            Console.WriteLine($"Deleted: {e.FullPath}")
        End Sub

        Private Shared Sub OnRenamed(sender As Object, e As RenamedEventArgs)
            Console.WriteLine($"Renamed:")
            Console.WriteLine($"    Old: {e.OldFullPath}")
            Console.WriteLine($"    New: {e.FullPath}")
        End Sub

        Private Shared Sub OnError(sender As Object, e As ErrorEventArgs)
            PrintException(e.GetException())
        End Sub

        Private Shared Sub PrintException(ex As Exception)
            If ex IsNot Nothing Then
                Console.WriteLine($"Message: {ex.Message}")
                Console.WriteLine("Stacktrace:")
                Console.WriteLine(ex.StackTrace)
                Console.WriteLine()
                PrintException(ex.InnerException)
            End If
        End Sub

    End Class

End Namespace

備註

用於 FileSystemWatcher watch指定目錄中的變更。 您可以watch指定目錄的檔案和子目錄中的變更。 您可以建立元件來watch本機電腦、網路磁碟機機或遠端電腦上的檔案。

若要watch所有檔案中的變更，請將 Filter 屬性設定為空字串 (「」) 或使用萬用字元 (「*.*」) 。 若要watch特定檔案，請將 Filter 屬性設定為檔案名。 例如，若要watch檔案MyDoc.txt變更，請將 Filter 屬性設定為 「MyDoc.txt」。 您也可以watch特定類型的檔案變更。 例如，若要watch文字檔中的變更，請將 Filter 屬性設定為 「*.txt」。

您可以在目錄或檔案中watch數種類型的變更。 例如，您可以watch 、 LastWrite 日期和時間或 Size 檔案或目錄的 變更 Attributes 。 做法是將 NotifyFilter 屬性設定為其中 NotifyFilters 一個值。 如需您可以watch之變更類型的詳細資訊，請參閱 NotifyFilters 。

您可以watch重新命名、刪除或建立檔案或目錄。 例如，若要watch重新命名文字檔，請將 Filter 屬性設定為 「*.txt」，並使用為其參數指定的 呼叫 WaitForChanged 方法 Renamed 。

Windows 作業系統會在 所 FileSystemWatcher 建立的緩衝區中通知您的檔案變更。 如果短時間內有許多變更，緩衝區可能會溢位。 這會導致元件無法追蹤目錄中的變更，而且只會提供通知。 使用 InternalBufferSize 屬性增加緩衝區的大小相當昂貴，因為其來自無法交換至磁片的非分頁式記憶體，因此讓緩衝區保持小到足以遺漏任何檔案變更事件。 若要避免緩衝區溢位，請使用 NotifyFilter 和 IncludeSubdirectories 屬性，以便篩選掉不必要的變更通知。

如需 實例 FileSystemWatcher 的初始屬性值清單，請參閱 建 FileSystemWatcher 構函式。

使用 FileSystemWatcher 類別時，請注意下列事項。

• 不會忽略隱藏的檔案。

• 在某些系統中， FileSystemWatcher 會使用簡短的 8.3 檔案名格式來報告檔案的變更。 例如，「LongFileName.LongExtension」 的變更可能會回報為 「LongFil~」。Lon」。

• 這個類別包含套用至所有成員之類別層級的連結需求和繼承需求。 SecurityException當立即呼叫端或衍生類別沒有完全信任許可權時，就會擲回 。 如需安全性需求的詳細資訊，請參閱 連結需求。

• 您可以為 InternalBufferSize 屬性設定的大小上限，以透過網路監視目錄為 64 KB。

複製和移動資料夾

作業系統和 FileSystemWatcher 物件會將剪貼動作或移動動作解譯為資料夾及其內容的重新命名動作。 如果您剪下並貼上含有檔案的資料夾到所監看的資料夾，物件 FileSystemWatcher 只會將資料夾報告為新資料夾，但不會報告其內容，因為它們基本上只會重新命名。

若要收到已移動或複製到受監看資料夾之資料夾內容的通知，請提供 OnChanged 和 OnRenamed 事件處理常式方法，如下表所示。

事件處理常式	已處理的事件	執行
OnChanged	Changed, Created, Deleted	報告檔案屬性、已建立的檔案和已刪除檔案中的變更。
OnRenamed	Renamed	列出重新命名檔案和資料夾的舊路徑和新路徑，視需要以遞迴方式展開。

事件和緩衝區大小

請注意，數個因素可能會影響引發哪些檔案系統變更事件，如下所述：

• 常見的檔案系統作業可能會引發一個以上的事件。 例如，當檔案從一個目錄移到另一個目錄時，可能會引發數 OnChanged 個和一些 OnCreated 和 OnDeleted 事件。 移動檔案是包含多個簡單作業的複雜作業，因此引發多個事件。 同樣地，某些應用程式 (例如，防毒軟體) 可能會導致 偵測 FileSystemWatcher 到的其他檔案系統事件。

• FileSystemWatcher只要磁片未切換或移除，就可以watch磁片。 FileSystemWatcher不會引發 CD 和 DVD 的事件，因為時間戳記和屬性無法變更。 遠端電腦必須安裝其中一個必要的平臺，元件才能正常運作。

請注意， FileSystemWatcher 當超過緩衝區大小時，可能會遺漏 事件。 若要避免遺漏事件，請遵循下列指導方針：

• 藉由設定 屬性來 InternalBufferSize 增加緩衝區大小。

• 避免監看具有長檔名的檔案，因為長檔名有助於填滿緩衝區。 請考慮使用較短的名稱重新命名這些檔案。

• 盡可能縮短您的事件處理常式代碼。

建構函式

FileSystemWatcher()	初始化 FileSystemWatcher 類別的新執行個體。
FileSystemWatcher(String)	提供要監視的指定目錄，初始化 FileSystemWatcher 類別的新執行個體。
FileSystemWatcher(String, String)	提供要監視的指定目錄和檔案類型，初始化 FileSystemWatcher 類別的新執行個體。

屬性

CanRaiseEvents	取得值，指出元件是否能引發事件。 (繼承來源 Component)
Container	取得包含 IContainer 的 Component。 (繼承來源 Component)
DesignMode	取得值，指出 Component 目前是否處於設計模式。 (繼承來源 Component)
EnableRaisingEvents	取得或設定數值，表示是否啟用元件。
Events	取得附加在這個 Component 上的事件處理常式清單。 (繼承來源 Component)
Filter	取得或設定篩選字串，用以判斷在目錄中監視什麼檔案。
Filters	取得用於決定要在目錄中監視哪些檔案的所有篩選器集合。
IncludeSubdirectories	取得或設定數值，表示是否應該監視指定路徑內的子目錄。
InternalBufferSize	取得或設定內部緩衝區的大小 (以位元組為單位)。
NotifyFilter	取得或設定要監看的變更類型。
Path	取得或設定要監看的目錄路徑。
Site	取得或設定 ISite 的 FileSystemWatcher。
SynchronizingObject	取得或設定物件，用以封送處理因目錄變更而發出的事件處理常式呼叫。

方法

BeginInit()	開始初始化用於表單或為另一個元件所使用的 FileSystemWatcher。 初始化發生於執行階段。
CreateObjRef(Type)	建立包含所有相關資訊的物件，這些資訊是產生用來與遠端物件通訊的所需 Proxy。 (繼承來源 MarshalByRefObject)
Dispose()	釋放 Component 所使用的所有資源。 (繼承來源 Component)
Dispose(Boolean)	釋放 FileSystemWatcher 所使用的 Unmanaged 資源，並選擇性地釋放 Managed 資源。
EndInit()	結束初始化用於表單或為另一個元件所使用的 FileSystemWatcher。 初始化發生於執行階段。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
GetHashCode()	做為預設雜湊函式。 (繼承來源 Object)
GetLifetimeService()	已過時。 擷取控制這個執行個體存留期 (Lifetime) 原則的目前存留期服務物件。 (繼承來源 MarshalByRefObject)
GetService(Type)	傳回表示 Component 或其 Container 所提供之服務的物件。 (繼承來源 Component)
GetType()	取得目前執行個體的 Type。 (繼承來源 Object)
InitializeLifetimeService()	已過時。 取得存留期服務物件，以控制這個執行個體的存留期原則。 (繼承來源 MarshalByRefObject)
MemberwiseClone()	建立目前 Object 的淺層複製。 (繼承來源 Object)
MemberwiseClone(Boolean)	建立目前 MarshalByRefObject 物件的淺層複本。 (繼承來源 MarshalByRefObject)
OnChanged(FileSystemEventArgs)	引發 Changed 事件。
OnCreated(FileSystemEventArgs)	引發 Created 事件。
OnDeleted(FileSystemEventArgs)	引發 Deleted 事件。
OnError(ErrorEventArgs)	引發 Error 事件。
OnRenamed(RenamedEventArgs)	引發 Renamed 事件。
ToString()	傳回任何包含 Component 名稱的 String。 不應覆寫此方法。 (繼承來源 Component)
WaitForChanged(WatcherChangeTypes)	提供想要監視的變更類型，同步方法會傳回含有發生的變更之特定資訊的結構。
WaitForChanged(WatcherChangeTypes, Int32)	提供您想要監視的變更類型和逾時前的等候時間 (以毫秒計)，同步方法會傳回含有發生的變更之特定資訊的結構。
WaitForChanged(WatcherChangeTypes, TimeSpan)	根據要監視的變更類型，以同步方式傳回結構，其中包含所發生變更的特定資訊。

事件

Changed	發生在指定之 Path 內的檔案或目錄變更時。
Created	發生在指定之 Path 內的檔案或目錄建立時。
Deleted	發生在指定之 Path 內的檔案或目錄刪除時。
Disposed	當 Dispose() 方法的呼叫處置元件時，就會發生。 (繼承來源 Component)
Error	發生在 FileSystemWatcher 執行個體無法繼續執行監視變更時或在內部緩衝區溢位時。
Renamed	發生在指定之 Path 內的檔案或目錄重新命名時。

另請參閱

• NotifyFilter
• NotifyFilters
• FileSystemEventArgs
• FileSystemEventHandler
• Filter
• IncludeSubdirectories
• InternalBufferOverflowException
• RenamedEventArgs
• RenamedEventHandler
• WaitForChangedResult
• WatcherChangeTypes
• 在 Windows Form 中使用 FileSystemWatcher 元件