FileSystemWatcher 類別

定義

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

public ref class FileSystemWatcher : System::ComponentModel::Component, System::ComponentModel::ISupportInitialize
public ref class FileSystemWatcher : IDisposable
public ref class FileSystemWatcher : System::ComponentModel::Component, IDisposable, System::ComponentModel::ISupportInitialize
public class FileSystemWatcher : System.ComponentModel.Component, System.ComponentModel.ISupportInitialize
public class FileSystemWatcher : IDisposable
[System.IO.IODescription("FileSystemWatcherDesc")]
public class FileSystemWatcher : System.ComponentModel.Component, System.ComponentModel.ISupportInitialize
public class FileSystemWatcher : System.ComponentModel.Component, IDisposable, System.ComponentModel.ISupportInitialize
[System.IO.IODescription("")]
public class FileSystemWatcher : System.ComponentModel.Component, System.ComponentModel.ISupportInitialize
type FileSystemWatcher = class
    inherit Component
    interface ISupportInitialize
type FileSystemWatcher = class
    interface IDisposable
[<System.IO.IODescription("FileSystemWatcherDesc")>]
type FileSystemWatcher = class
    inherit Component
    interface ISupportInitialize
type FileSystemWatcher = class
    inherit Component
    interface IDisposable
    interface ISupportInitialize
[<System.IO.IODescription("")>]
type FileSystemWatcher = class
    inherit Component
    interface ISupportInitialize
Public Class FileSystemWatcher
Inherits Component
Implements ISupportInitialize
Public Class FileSystemWatcher
Implements IDisposable
Public Class FileSystemWatcher
Inherits Component
Implements IDisposable, ISupportInitialize
繼承
FileSystemWatcher
繼承
FileSystemWatcher
屬性
實作

範例

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

#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 監看指定目錄中的變更。 您可以監看指定目錄的檔案和子目錄中的變更。 您可以建立元件來監看本機電腦、網路磁碟機機或遠端電腦上的檔案。

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

您可以在目錄或檔案中監看數種類型的變更。 例如,您可以監看 、 LastWrite 日期和時間或 Size 檔案或目錄的 Attributes 變更。 這是藉由將 NotifyFilter 屬性設定為其中 NotifyFilters 一個值來完成。 如需您可以監看之變更類型的詳細資訊,請參閱 NotifyFilters

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

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

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

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

  • 不會忽略隱藏的檔案。

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

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

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

複製和移動資料夾

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

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

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

事件和緩衝區大小

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

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

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

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

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

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

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

建構函式

FileSystemWatcher()

初始化 FileSystemWatcher 類別的新執行個體。

FileSystemWatcher(String)

提供要監視的指定目錄,初始化 FileSystemWatcher 類別的新執行個體。

FileSystemWatcher(String, String)

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

屬性

CanRaiseEvents

取得值,指出元件是否能引發事件。

(繼承來源 Component)
Container

取得包含 IContainerComponent

(繼承來源 Component)
DesignMode

取得值,指出 Component 目前是否處於設計模式。

(繼承來源 Component)
EnableRaisingEvents

取得或設定數值,表示是否啟用元件。

Events

取得附加在這個 Component 上的事件處理常式清單。

(繼承來源 Component)
Filter

取得或設定篩選字串,用以判斷在目錄中監視什麼檔案。

Filters

取得用於決定要在目錄中監視哪些檔案的所有篩選器集合。

IncludeSubdirectories

取得或設定數值,表示是否應該監視指定路徑內的子目錄。

InternalBufferSize

取得或設定內部緩衝區的大小 (以位元組為單位)。

NotifyFilter

取得或設定要監看的變更類型。

Path

取得或設定要監看的目錄路徑。

Site

取得或設定 ISiteFileSystemWatcher

SynchronizingObject

取得或設定物件,用以封送處理因目錄變更而發出的事件處理常式呼叫。

方法

BeginInit()

開始初始化用於表單或為另一個元件所使用的 FileSystemWatcher。 初始化發生於執行階段。

CreateObjRef(Type)

建立包含所有相關資訊的物件,這些資訊是產生用來與遠端物件通訊的所需 Proxy。

(繼承來源 MarshalByRefObject)
Dispose()

釋放 FileSystemWatcher 使用的 Unmanaged 資源。

Dispose()

釋放 Component 所使用的所有資源。

(繼承來源 Component)
Dispose(Boolean)

釋放 FileSystemWatcher 所使用的 Unmanaged 資源,並選擇性地釋放 Managed 資源。

EndInit()

結束初始化用於表單或為另一個元件所使用的 FileSystemWatcher。 初始化發生於執行階段。

Equals(Object)

判斷指定的物件是否等於目前的物件。

(繼承來源 Object)
Finalize()

將目前執行個體所持有的資源釋出。

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)
ToString()

傳回代表目前物件的字串。

(繼承來源 Object)
WaitForChanged(WatcherChangeTypes)

提供想要監視的變更類型,同步方法會傳回含有發生的變更之特定資訊的結構。

WaitForChanged(WatcherChangeTypes, Int32)

提供您想要監視的變更類型和逾時前的等候時間 (以毫秒計),同步方法會傳回含有發生的變更之特定資訊的結構。

WaitForChanged(WatcherChangeTypes, TimeSpan)

根據要監視的變更類型,以同步方式傳回結構,其中包含所發生變更的特定資訊。

事件

Changed

發生在指定之 Path 內的檔案或目錄變更時。

Created

發生在指定之 Path 內的檔案或目錄建立時。

Deleted

發生在指定之 Path 內的檔案或目錄刪除時。

Disposed

Dispose() 方法的呼叫處置元件時,就會發生。

(繼承來源 Component)
Error

發生在 FileSystemWatcher 執行個體無法繼續執行監視變更時或在內部緩衝區溢位時。

Renamed

發生在指定之 Path 內的檔案或目錄重新命名時。

適用於

另請參閱