Net-Base Magazin

18.11.2026

Delphi: Robustes FileSystemWatcher-Polling ohne Doppel-Events – USN-Journal vs. FindFirstChangeNotification

Doppel-Events und verpasste Änderungen sind bei Directory-Notifications normal. Der Beitrag zeigt einen robusten Ansatz mit Entprellung, Snapshot-Abgleich und wann das NTFS-USN-Journal die bessere Basis ist.

18.11.2026

A magazintémától a projektgyakorlatig

A bejegyzéshez tartozó szolgáltatási és technikai oldalak

Der Irrtum begegnet einem schnell, sobald ein Import-Ordner „produktiv“ genutzt wird: „Ich hänge FindFirstChangeNotification an ein Verzeichnis, dann bekomme ich genau ein Event pro Dateiänderung. Also kann ich pro Event genau einmal verarbeiten.“ Die Realität kommt meistens schon am ersten Tag: Beim Speichern feuert es doppelt. Beim Entpacken eines ZIPs kommt ein Sturm. Und wenn der Server unter Last steht, fehlt später ausgerechnet die eine Änderung, die eigentlich nicht fehlen darf.

Genau hier entscheidet sich, ob du eine robuste Verarbeitung baust oder nur Symptome glättest. Delphi FileSystemWatcher Polling ohne Doppel-Events ist kein magisches Flag, sondern ein Architekturthema: Notifications sind Trigger, nicht die Wahrheit. Du brauchst Entprellung (Debounce), Deduplikation, einen Zustandsabgleich und eine klare Strategie für den Fall „zu viele“ und „zu wenige“ Ereignisse. Und je nach Risiko lohnt sich irgendwann der Sprung vom Verzeichnis-Watching zum NTFS-USN-Journal (Change Journal).

Irrtum-Check: „Doppel-Events sind ein Bug“

Arbeitsplatzfoto mit anonymisierten Logausdrucken und skizziertem Queue-Diagramm zur Diagnose von Datei-Events
Debugging im Alltag: strukturierte Logs und Queue-Längen als sichtbares Diagnose-Setup.
Grafik zeigt NTFS-Volume mit Journal-Logband und positionsbasiertem Lesezeiger
Detailmotiv für USN: Volume-Handle und Journal-Lesepfad als technische Visualisierung ohne Text.
Abstrakte Grafik eines Datenflusses von Dateisystem-Trigger über Queue zum Snapshot-Abgleich und zur Verarbeitung
Vergleich der Signalwege: Notification-Trigger vs. nachgelagerter Snapshot-Abgleich.

Windows liefert bei FindFirstChangeNotification bewusst keine Details darüber, was sich geändert hat. Microsoft formuliert das als Einschränkung und verweist für detaillierte Informationen direkt auf ReadDirectoryChangesW[Quelle]. Praktische Konsequenz: Wenn du aus einem „es hat sich etwas geändert“-Signal eine „genau einmal“-Semantik ableitest, baust du zwangsläufig Heuristiken, die bei Randfällen zerbrechen.

Der zweite Teil des Irrtums ist psychologisch nachvollziehbar: Mehrfach-Events sehen aus wie ein Fehler im Watcher. Raymond Chen zeigt aber am Beispiel Notepad, dass mehrere Benachrichtigungen beim Speichern erwartbar sind, weil „Speichern“ in der Praxis aus mehreren Dateisystemschritten besteht und die APIs keine 1:1-Abbildung versprechen[Quelle]. Die wichtigste Folgerung ist unbequem, aber befreiend: Du musst Mehrfach-Events als normales Eingangssignal behandeln und deine Verarbeitung darauf auslegen.

Die unangenehme Ausnahme: Es sind nicht nur zu viele Events – manchmal fehlen welche

Viele Teams investieren zuerst Zeit, um Doppel-Events „wegzufiltern“. Unter Last kippt das Bild: Plötzlich ist das Problem nicht die Doppelverarbeitung, sondern eine verpasste Änderung. Bei ReadDirectoryChangesW ist der Überlast-Fall dokumentiert: Wenn das System nicht alle Änderungen aufzeichnen konnte, kann der Fehler ERROR_NOTIFY_ENUM_DIR auftreten[Quelle]. Das ist kein exotisches Windows-Problem, sondern eine Folge begrenzter Puffer und eines Consumers, der nicht hinterherkommt.

Damit ist klar: Ein Watcher-Design muss zwei Ausfallklassen berücksichtigen. „Zu viel“ (Doppel/Mehrfach) und „zu wenig“ (Miss/Overflow). Wer nur eine Seite optimiert, bekommt im Betrieb die andere als Ticketlawine zurück.

FindFirstChangeNotification vs. ReadDirectoryChangesW: Signalqualität und Betriebsfolgen

FindFirstChangeNotification ist schnell erklärt und schnell implementiert: Handle holen, warten, „da ist etwas passiert“, erneut scharf schalten. Weil dir Details fehlen, musst du nach dem Trigger selbst scannen oder anderweitig feststellen, was relevant ist. Das macht die API als „Wecker“ erstaunlich brauchbar, wenn dein nächster Schritt ohnehin ein Abgleich ist (z. B. Import-Ordner: „finde neue Dateien“).

ReadDirectoryChangesW ist die detailliertere Variante: Du bekommst Dateinamen und Aktionstypen (Create/Delete/Modify/Rename). Das hilft, wenn du zielgerichtet reagieren willst, ohne jedes Mal alles zu scannen. Gleichzeitig steigt der Anspruch an Threading, Queueing und Backpressure: Die API liefert schneller, als du verarbeiten kannst, wenn du nicht bewusst begrenzt.

Wichtig für die Einordnung im Betrieb: Mehr Detail heißt nicht automatisch weniger „Doppel“. Mehr Detail heißt vor allem: Du siehst mehr von dem, was wirklich passiert.

Tabelle: Typische Anforderungen und welche Basis dazu passt

Anforderung FindFirstChangeNotification ReadDirectoryChangesW USN-Journal (NTFS)
„Aufwachen“, danach ohnehin Verzeichnis-Scan Gut (Trigger) Gut, aber mehr Aufwand Meist unnötig
Direkte Verarbeitung nach Dateiname/Aktion Schwach (keine Details) Gut (liefert Details) Gut, aber Pfad-Auflösung nötig
Hohe Änderungsraten, trotzdem robust Nur mit Rescan Mit Overflow-Handling und Rescan Stark (persistente Quelle)
Nach Neustart weiterarbeiten und nachholen Nicht geeignet Nicht geeignet ohne Zusatzlogik Stark (positionsbasiert)
Implementierungs- und Betriebsaufwand Niedrig Mittel Hoch

Warum „Doppel-Events“ entstehen: Speichern ist selten ein einzelner Schreibvorgang

Ein sauberer Watcher scheitert oft nicht an „Windows“, sondern an der falschen Annahme über Schreibmuster. Viele Anwendungen speichern nicht „in place“, sondern über mehrere Schritte, zum Beispiel:

  • Schreiben in eine temporäre Datei im selben Verzeichnis, danach Replace/Rename auf den Zielnamen.
  • Nachträgliches Setzen von Attributen, Security-Infos oder Zeitstempeln.
  • Zusätzliche Änderungen durch Dritte: Virenscanner, Indexer, DLP/EDR, Backup-Agenten.

Wenn du diese Sequenzen „wegfilterst“, filterst du im Zweifel echte Zustandsänderungen weg. Die robustere Sicht ist: Ein Event ist ein Hinweis, dass du deinen Wissensstand über Dateien aktualisieren solltest. Nicht mehr, nicht weniger.

Delphi FileSystemWatcher Polling ohne Doppel-Events: Ein Ansatz in vier Schichten

„Polling“ klingt nach sturem Scannen. Für robuste Watcher-Architektur ist Polling eher ein gezielter Abgleich, der durch Notifications angestoßen wird. Das spart Last und verhindert, dass du Events mit Semantik verwechselst.

1) Trigger-Schicht: Notifications als Wecker, nicht als Quelle der Wahrheit

Baue die Trigger-Schicht austauschbar. Heute FindFirstChangeNotification, morgen ReadDirectoryChangesW, später vielleicht USN. Die Verarbeitung dahinter sollte davon möglichst wenig wissen. Das ist nicht akademisch: Es reduziert Lock-in auf ein Verhalten, das Windows explizit nicht garantiert.

2) Entprellung (Debounce): pro Datei/Ordner stabilisieren und zu Batches bündeln

Ohne Debounce reagierst du während des Schreibens. Mit Debounce reagierst du auf einen stabilen Zustand. Bewährte Parameter, die du später pro Ordnerprofil variieren kannst:

  • Debounce-Fenster pro Datei oder Schlüssel (z. B. Pfad): 200–800 ms.
  • Maximalwartezeit: 2–5 s, damit Dauer-Events nicht alles blockieren.
  • Batch-Bildung: mehrere Pfade zusammen abarbeiten, statt pro Event einen Job zu starten.

Für Admins ist der Effekt sofort messbar: weniger konkurrierende Zugriffe auf dieselben Dateien, weniger „Datei ist gesperrt“-Fehler, weniger Support-Rauschen.

3) Snapshot-Abgleich: kleine, schnelle Zustandsdaten statt Event-Gläubigkeit

Der Snapshot ist dein Gegenmittel gegen Doppel und gegen Misses. Minimal sinnvoll sind:

  • Pfad (normalisiert, z. B. Groß/Klein konsistent)
  • Größe
  • LastWriteTime in UTC

Optional ergänzt du einen günstigen Hash (z. B. nur Teilbereiche) oder – wenn du ohnehin USN nutzt – die letzte bekannte USN-Position. Entscheidend ist, dass du pro Verarbeitungsvorgang eine klare Frage beantwortest: „Hat sich der relevante Zustand seit der letzten erfolgreichen Verarbeitung wirklich geändert?“

Grenze: LastWriteTime und Attribute können durch Tools verändert werden. Wenn du Nachvollziehbarkeit auf Inhaltsbasis brauchst, führt kein Weg an Hashing oder journalbasierten IDs vorbei.

4) Verarbeitungsschicht: idempotent, begrenzt parallel, sauber protokolliert

Robustheit kommt am Ende aus dem Consumer. Drei Eigenschaften zahlen sich im Betrieb aus:

  • Idempotenz: Mehrfaches Verarbeiten derselben Datei erzeugt keinen Schaden.
  • Queue mit Backpressure: begrenzte Queue-Länge, begrenzte Worker-Anzahl, definierte Drop-/Rescan-Strategie.
  • Entscheidungs-Logging: warum wurde verarbeitet, warum übersprungen, warum Rescan.

Schrittfolge: so baust du es debugbar statt „magisch stabil“

  1. Definiere die fachliche Wahrheit: Was heißt „Änderung“? Inhalt, Name, Metadaten, nur Neu-Dateien?
  2. Lege einen Schlüssel fest: pro Datei (Pfad) oder pro Ordner (Batch), der entprellt wird.
  3. Implementiere Debounce: Timer/Deadline pro Schlüssel, plus Maximalwartezeit.
  4. Snapshot holen: beim Debounce-Ablauf und optional kurz davor/danach (Stabilitätsprüfung).
  5. Deduplizieren: vergleiche gegen „zuletzt verarbeitet“ (Snapshot/Hash/USN-Position).
  6. Abarbeiten: begrenzt parallel, mit klaren Fehlerpfaden (Retry, Quarantäne, Failed-Ordner).
  7. Overflow-Fall behandeln: bei ERROR_NOTIFY_ENUM_DIR oder Queue-Überlauf: Rescan-Modus aktivieren.

USN-Journal als Alternative: wann das Mehr an Komplexität ein Gewinn ist

Das NTFS-USN-Change-Journal ist eine volumenweite, persistente Änderungsquelle. Ausgelesen wird es nicht über Directory-Handles, sondern über definierte FSCTL-Operationen via DeviceIoControl[Quelle]. Das ist der große Unterschied: Du liest nicht nur „ab jetzt“, sondern kannst eine Position merken und später wieder aufnehmen.

Für Betrieb und Administration ist das oft der eigentliche Mehrwert: Wenn ein Dienst neu startet, wenn ein Server rebootet oder wenn du bewusst später nachziehen willst, hast du eine datengetriebene Quelle, statt auf „Event kam damals hoffentlich“ zu setzen.

Was USN gut kann (und warum das für Polling attraktiv ist)

  • Positionsbasiertes Lesen: „Gib mir alles seit USN X“ – geeignet für Nachholen.
  • Reason-Flags: du bekommst Ursachen (Create/Delete/Rename etc.) als strukturierte Information.
  • Warten statt Busy-Wait: USN-Lesen kann so parametrisiert werden, dass bei „Ende erreicht“ nicht in einer engen Schleife gepollt wird, sondern gewartet wird, bis neue Daten vorliegen (Blocking-freundlich).

Wichtig: USN ist keine Garantie für „ein Record pro fachlicher Aktion“. Rename/Move kann mehrere Records erzeugen. Das ist korrektes, detailliertes Verhalten – aber du musst es semantisch zusammenfassen, wenn deine Prozesslogik „ein Ereignis“ erwartet.

Die zwei Hürden, die du vorher sauber klären solltest

1) Pfad-Auflösung und Mapping. USN-Records arbeiten mit File Reference Numbers (FRN) und Parent-Referenzen. Wenn du am Ende „Pfad + Aktion“ brauchst, musst du den Pfad aus diesen Referenzen ableiten oder cachen. Für klar abgegrenzte Ordnerbäume geht das pragmatisch, volumenweit wird es anspruchsvoller.

2) Rechte, EDR/AV-Policies, Volume-Zugriff. USN-Zugriff bedeutet: du öffnest das Volume (z. B. \.C:) und liest systemnahe Informationen. In Unternehmensumgebungen ist das häufig genehmigungspflichtig oder technisch eingeschränkt. Das ist kein Argument dagegen, aber ein Punkt für die Projektplanung: Wer USN „mal eben“ einbaut, scheitert nicht am Code, sondern an der Umgebung.

Entscheidung nach Risiko: „Best effort“ vs. „nachholbar“

Wenn du UI-Listen aktualisierst oder einen Cache invalidierst, sind doppelte Events lästig, aber meist nicht kritisch. Dann ist die wirtschaftliche Lösung: ReadDirectoryChangesW (oder FindFirstChangeNotification als Wecker) plus Debounce, plus periodischer Rescan als Sicherheitsnetz. Das bringt Ruhe in den Betrieb, ohne dass du Volume-Logik einführst.

Wenn du dagegen eine prozessnahe digitale Unternehmenslösung betreibst, in der ein verpasstes Event zu falschen Importen, Datenlücken oder wiederkehrenden Supportfällen führt, ist „best effort“ irgendwann zu teuer. Dann lohnt die Evaluation: USN für die kritischen Volumes, klar begrenzt auf die Prozesse, die Nachholbarkeit brauchen.

Ein realistischer Hybrid, der oft reicht

  • ReadDirectoryChangesW als schneller Trigger mit geringer Latenz.
  • Debounce + Batch, damit Schreibvorgänge erst stabil werden.
  • Rescan-Takt (z. B. alle 5–15 Minuten) für Misses und Overflow-Fälle.
  • Bei auffälligen Overflows oder hoher Änderungsrate: USN gezielt für genau dieses Volume/Ordnerprofil.

Debugging: Welche Daten du brauchst, um Watcher-Probleme sauber einzugrenzen

Watcher-Probleme wirken zufällig, weil sie von Fremdprozessen getrieben werden. Mit drei Log-Kategorien bekommst du Kontrolle:

  • Trigger-Log: Quelle (FindFirstChangeNotification/ReadDirectoryChangesW), gemeldete Aktion, Pfad, Timestamp, Thread, Queue-Länge.
  • Snapshot-Log: Größe/LastWriteTime bei Trigger und bei tatsächlichem Start der Verarbeitung.
  • Fehler- und Fallback-Log: ERROR_NOTIFY_ENUM_DIR, Queue-Overflow, Rescan aktiviert, Dedupe-Entscheidung.

Damit kannst du eine der wichtigsten Fragen schnell beantworten: „Verarbeiten wir doppelt, obwohl sich nichts geändert hat?“ oder „Verarbeiten wir mehrfach, weil der Schreibvorgang tatsächlich mehrere Zustände durchläuft?“ Erst dann ergibt eine Maßnahme Sinn.

Wann sich der Aufwand wirklich lohnt

Ein robuster Watcher ist mehr als ein Event-Handler. Du baust Threading, Queue, Backpressure, Debounce, Snapshot und Tests. Das lohnt sich, wenn mindestens einer dieser Punkte zutrifft:

  • Du automatisierst Imports/Exports, bei denen Fehler im Betrieb manuell nachgearbeitet werden müssen.
  • Du erwartest hohe Änderungsraten (viele kleine Dateien, Batch-Jobs, Scanner-Workflows).
  • Du brauchst Nachvollziehbarkeit („was ist seit Zeitpunkt X passiert?“) oder willst nach Reboots zuverlässig fortsetzen.
  • Du betreibst als Windows- und Linux-Services und musst Lastspitzen abfangen, ohne Events zu verlieren.

Wenn es nur um „UI aktualisieren“ geht, darf die Lösung einfacher sein: grob entprellen, bei Bedarf scannen, und nicht jede Mehrfachbenachrichtigung als Fehler interpretieren. „Genau einmal“ ist dann kein Ziel, sondern eine unnötige Kostenstelle.

Der Schlusspunkt: „Genau einmal“ ist ein Designziel – nicht die Eigenschaft einer API

Windows-Directory-Notifications liefern Signale. Mehrfach-Events sind häufig das sichtbare Ergebnis realer Mehrschritt-Operationen. Misses sind unter Last möglich. Wenn du das akzeptierst, kommst du zügig zu einer robusten Kette: Trigger → Debounce → Snapshot-Abgleich → idempotente Verarbeitung. Und wenn die Anforderungen „lückenarm und nachholbar“ heißen, ist das USN-Journal auf NTFS oft die konsistentere Basis – mit klaren Mehrkosten, die man bewusst einplant.

Wenn du das für eine bestehende Delphi-Anwendung oder einen Windows-Service sauber entscheiden möchtest, kannst du das Vorhaben mit Net-Base besprechen.

Quellen und weiterfuehrende Informationen

Die fachlichen Kernaussagen wurden anhand der folgenden externen Quellen redaktionell eingeordnet.

  1. Obtaining Directory Change Notifications – Win32 apps | Microsoft Learn (learn.microsoft.com)
    FindFirstChangeNotification liefert nur ein Änderungs-Signal und keine Information über die tatsächliche Änderung; für Details wird ReadDirectoryChangesW empfohlen.
  2. Why does saving a file in Notepad fire multiple FindFirstChangeNotification events? – The Old New Thing (devblogs.microsoft.com)
    Mehrfach-Events beim Speichern (z. B. Notepad) sind erwartbar, weil Speichern mehrere filesystem-relevante Schritte auslösen kann.
  3. ReadDirectoryChangesW-Funktion (winbase.h) – Win32 apps | Microsoft Learn (learn.microsoft.com)
    ReadDirectoryChangesW kann Änderungen nicht vollständig aufzeichnen; bei Überlast kann ERROR_NOTIFY_ENUM_DIR auftreten.
  4. Change journal operations – Win32 apps | Microsoft Learn (learn.microsoft.com)
    Das NTFS-USN-Change-Journal wird über definierte FSCTL-Operationen (DeviceIoControl) ausgelesen und ist eine volumenweite Änderungsquelle.

Projekt oder Modernisierungsvorhaben mit Net-Base besprechen.

Következő lépés

Ha a téma valós projektté válik, az architektúrát, a meglévő rendszert és az üzemeltetést már korán együtt kell értékelni.

Nemcsak egyedi kérdésekben támogatunk, hanem akkor is, amikor forráskódrészletekből, örökölt rendszerekkel kapcsolatos témákból vagy portálötletekből robusztus vállalati projektet kell kialakítani.

  • A jelenlegi állapotot, a célállapotot és a műszaki kockázatokat együttesen értékeljük.
  • REST, az adathozzáférés, a portálok és a Rollout nem kerülnek utólagos teendőkként elhalasztásra.
  • Már korán láthatja, melyik út gazdaságilag és üzemeltetési szempontból életképes.

Bejegyzés megosztása

Ezt a bejegyzést közvetlenül megosztani

LinkedIn, X, Facebook, WhatsApp und E-Mail sind sofort verfügbar. für Instagram bereiten wir Link und Kurztext direkt vor.

E-mail

Az Instagram egy új lapon nyílik meg. A link és a rövid szöveg előzetesen a vágólapra másolódik.

Hozzászólás írása

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert