FileSystemWatcher実務ガイド - 取りこぼしと重複対策

2026年03月10日 01:00 · 小村豪 · FileSystemWatcher, C#, .NET, Windows開発, ファイル連携, 設計

FileSystemWatcher は、Windows 上の .NET でファイル変更を監視するときにまず候補になる API です。ファイルやディレクトリの作成、変更、削除、名前変更をイベントで受け取れるので便利なのですが、Created や Changed をそのまま完了通知だと思って使うと、取りこぼし、重複通知、途中ファイルの誤読でかなり普通に事故ります。

この記事では、FileSystemWatcher の使い方と注意点を、主に Windows 上の .NET によるファイル連携を前提に整理します。あわせて、前提となる排他制御の考え方はファイル連携の排他制御の基礎知識 - ファイルロックと原子的 claim のベストプラクティスも参照できる形にしています。

実際、ファイルのコピー中に Created が先に飛ぶことはありますし、Changed も 1 回で済むとは限りません。短時間に変更が集中すると内部バッファがあふれて、個別の変更を取りこぼすこともあります。

なので、設計の芯はこうです。

通知はきっかけ
真実はディレクトリ再スキャン
所有権は原子的な claim
最後は idempotency で受け止める

本文では、この考え方で FileSystemWatcher をファイル連携に組み込むときのはまりどころを順に見ていきます。

なお、この記事に登場するコードは、ビルド・実行できるサンプル一式（ライブラリ、一時ディレクトリ上で動くコンソールデモ、実際にファイルを作成・変更してイベントを検証するユニットテスト）として GitHub で公開しています。

filesystemwatcher-safe-basics - komurasoft-blog-samples (GitHub)

まず結論（ひとことで）
FileSystemWatcher で起きる勘違いパターン（図）
- 2.1. Created を完了通知だと思う
- 2.2. Changed の回数と順序を信じる
- 2.3. 内部バッファあふれで変更を失う
アンチパターン
- 3.1. イベントハンドラの中でそのまま処理する
- 3.2. イベント列から真実の状態を復元しようとする
- 3.3. Changed が止まったら完了扱い
- 3.4. InternalBufferSize を上げれば解決したと思う
- 3.5. Error をログだけ出して無視する
ベストプラクティス
- 4.1. 通知は「再スキャン要求」に畳む
- 4.2. 完了条件は送信側で明示する
- 4.3. 受信側は claim を原子的に取る
- 4.4. startup / overflow / 再接続時は full rescan する
- 4.5. idempotency を前提にする
擬似コード（抜粋）
- 5.1. 典型的な失敗パターン
- 5.2. 正しい方向の例（雑に書くとこう）
ざっくり使い分け
まとめ
参考資料

1. まず結論（ひとことで）

FileSystemWatcher のイベントは、完了通知ではなく変化の気配です
Created / Changed / Renamed は、重複したり、想像と違う順序で来たり、overflow 時には取りこぼしたりします
イベントハンドラでは重い処理をせず、再スキャン要求を積むだけにした方が安定します
完了判定は temp -> close -> rename / replace や done / manifest で明示するのが基本です
複数ワーカーがいるなら、読む前に claim を原子的に取る必要があります
InternalBufferSize の調整は補助です。最後は full rescan と idempotency が効きます

要するに、FileSystemWatcher を「真実の履歴ストリーム」として扱わないことです。通知はあくまで、「そろそろ見に行け」の合図に留めた方が壊れにくくなります。

2. `FileSystemWatcher` の使い方で起きやすい勘違いパターン（図）

2.1. `Created` を完了通知だと思う

これがいちばん分かりやすい地雷です。コピーや転送では、ファイルが作られた瞬間に Created が飛び、そのあとに 1 回以上の Changed が続くことがあります。

sequenceDiagram
    participant 送信 as 送信側
    participant 共有 as watched dir
    participant W as FileSystemWatcher
    participant 受信 as 受信側

    送信->>共有: orders.csv を作成
    共有-->>W: Created
    W-->>受信: OnCreated
    受信->>共有: orders.csv を開いて読む
    Note over 受信: まだコピー途中
    送信->>共有: 残りを書き込む
    共有-->>W: Changed
    共有-->>W: Changed
    Note over 受信: 行数不足 / JSON破損 / ZIP破損

Created は「名前が見えた」を表しても、「もう読んでよい」を保証しません。ここを同じ意味にすると、前回の記事の 2.1 を別ルートで踏むことになります。

2.2. `Changed` の回数と順序を信じる

Changed は 1 回だけ来るとは限りません。移動や保存のような普通の操作でも、複数のイベントに分かれて見えることがあります。さらに、ウイルス対策ソフトやインデクサが触った分まで拾うこともあります。

sequenceDiagram
    participant App as 保存するアプリ
    participant Dir as watched dir
    participant AV as AV / indexer
    participant W as FileSystemWatcher

    App->>Dir: report.xlsx を保存開始
    Dir-->>W: Created
    Dir-->>W: Changed
    App->>Dir: 一時ファイルから rename
    Dir-->>W: Renamed
    Dir-->>W: Changed
    AV->>Dir: スキャン / 属性参照
    Dir-->>W: Changed
    Note over W: 1回だけ・この順番とは限らない

「Changed が 1 回来たら完了」「Renamed の次はもう触られない」という期待は、だいぶ危ういです。

補足:

ファイル rename で Changed が飛ぶことがあります
RenamedEventArgs.Name は、OS 側で old/new の対応が取れないと null になりえます
hidden file も無視されません。隠し temp 名だから見えないだろう、は通りません
監視しているディレクトリそのものを rename しても、その変更は通知されません

2.3. 内部バッファあふれで変更を失う

FileSystemWatcher には内部バッファがあります。短時間に変更が集中すると、ここがあふれて個別通知を取りこぼします。

flowchart LR
    A[短時間に大量の変更] --> B[内部バッファに通知が溜まる]
    B --> C{処理が追いつく?}
    C -- はい --> D[個別イベントを順に処理]
    C -- いいえ --> E[overflow]
    E --> F[Error イベント]
    F --> G[個別履歴の完全性を信用しない]
    G --> H[ディレクトリを full rescan]

ここで大事なのは、「overflow が起きたら 1 件だけ失う」とは限らないことです。個別イベント列の完全性そのものが怪しくなるので、素直に全体を見直したほうがよいです。

3. アンチパターン

3.1. イベントハンドラの中でそのまま処理する

これは、完了判定と所有権取得をイベントに背負わせすぎです。

watcher.Created += (_, e) =>
{
    using var stream = File.OpenRead(e.FullPath);
    Import(stream); // まだコピー中かもしれない
};

watcher.Error += (_, e) =>
{
    Console.WriteLine(e.GetException()); // 出すだけ
};

問題は 2 つあります。

Created の時点では内容が未完成かもしれない
失敗や overflow の回復が無い

イベントハンドラは、再スキャン要求を立ててすぐ返すくらいがちょうどよいです。ここで重い I/O や DB 更新まで始めると、バースト時に自分で自分の首を絞めます。

3.2. イベント列から真実の状態を復元しようとする

「Created で辞書に追加、Changed で更新、Deleted で削除、Renamed でキー差し替え」という設計は、一見きれいです。ただ、重複、分割、overflow、外乱が入ると、だんだん辻褄が怪しくなります。

switch (e.ChangeType)
{
    case WatcherChangeTypes.Created:
        state[e.FullPath] = Pending;
        break;
    case WatcherChangeTypes.Changed:
        state[e.FullPath] = Modified;
        break;
    case WatcherChangeTypes.Deleted:
        state.Remove(e.FullPath);
        break;
}

この方向で頑張るより、その都度ディスク上の現物を再確認した方が強いです。ファイル連携で重要なのは、今この瞬間に処理してよい対象を正しく見つけることであって、イベント履歴をきれいに再現することではないからです。

3.3. `Changed` が止まったら完了扱い

前回の「ファイルサイズが止まったら完了」と同じ匂いのする設計です。便利そうですが、推測で完了を決めています。

if (lastChangedAt + TimeSpan.FromSeconds(10) < DateTime.UtcNow)
{
    return Ready;
}

これで困るのは、たとえばこういうケースです。

大きいファイルのコピーが途中で一時停止する
送信側アプリが複数段階で保存する
ネットワーク共有で通知が遅れて見える
外部プロセスがあとから属性や時刻を書き換える

完了は推測ではなく明示した方が安定します。

3.4. `InternalBufferSize` を上げれば解決したと思う

InternalBufferSize の調整は大事ですが、これは設計の本体ではありません。

既定値は 8192 バイト
4096 バイト未満にはできず、64 KB を超えることもできない
バッファは non-paged memory を使うので、増やせば増やすほど気軽とは言えない

つまり、64 KB まで上げても、通知バーストがそれを超えたら終わりです。しかも、完了通知かどうかの問題は 1 ミリも解決しません。

バッファを増やす前に、まず手を付けるべきことがあります。

Filter / Filters で監視対象を絞る
NotifyFilter を必要最小限にする
IncludeSubdirectories をむやみに true にしない
イベントハンドラを軽くする
full rescan と idempotency を入れる

3.5. `Error` をログだけ出して無視する

Error は「たまに出るけど気にしない」種類の通知ではありません。 buffer overflow や、監視継続に失敗した状況がここに出ます。

watcher.Error += (_, e) =>
{
    _logger.LogError(e.GetException(), "watcher error");
    // ここで終わると、取りこぼしに気づいたのに回復しない
};

最低限、ここまではやっておきたいところです。

full rescan を要求する
監視継続が怪しいなら watcher の再生成も検討する
取りこぼし前提で idempotent に再処理できるようにする

4. ベストプラクティス

4.1. 通知は「再スキャン要求」に畳む

Created / Changed / Deleted / Renamed / Error を、それぞれ別々の業務処理に直結させると見通しが悪くなります。まずは全部「見に行け」という 1 種類の信号に畳みます。

flowchart LR
    A[Created / Changed / Deleted / Renamed] --> Q[scan request]
    B[Error / overflow] --> Q
    C[startup] --> Q
    Q --> D[ディレクトリ再スキャン]
    D --> E[ready な候補を列挙]
    E --> F[claim を試す]

実装上のポイント:

イベントハンドラでは dirty = true にして signal を出す程度にする
走査は 1 本の worker に寄せる
バースト時は 100〜300ms ほどまとめてから 1 回走査する
走査中に追加通知が来たら、終わったあとにもう 1 回走査する

こうすると、イベントが 5 回来ても 50 回来ても、最終的にやることは「現物を見て ready なものを探す」に統一できます。

4.2. 完了条件は送信側で明示する

自分が送信側も握れるなら、FileSystemWatcher 側で完了判定を頑張るより、公開プロトコルを直した方が効きます。

王道は、やはりこれです。

temp 名に全内容を書く
close する
同一ファイルシステム上で rename / replace する
必要なら done / manifest を最後に置く

flowchart TD
    A[data.tmp に全内容を書く] --> B[flush / close]
    B --> C[data.csv に rename / replace]
    C --> D[data.done / manifest.json を置く]
    D --> E[受信側は final 名や done だけを見る]

前回の記事と同じですが、ここが本当に効きます。 FileSystemWatcher は完了を発明する道具ではなく、明示された完了を早めに見つける道具と捉えるのがしっくりきます。

4.3. 受信側は claim を原子的に取る

再スキャンで ready な候補が見つかっても、そのまま読みに行くと複数ワーカーが同時に掴めます。なので、処理前に claim を原子的に取ります。

sequenceDiagram
    participant Scan as scanner
    participant IN as incoming
    participant P1 as processing/worker1
    participant P2 as processing/worker2

    Scan->>IN: order-123 を発見
    Scan->>P1: rename order-123
    Scan->>P2: rename order-123
    Note over P1,P2: 先に成功した方だけが所有権を持つ

前回の記事でも触れた通り、incoming -> processing/<worker>/ の rename が分かりやすいです。特に本体 + manifest + 補助ファイルを 1 つのディレクトリにまとめておくと、bundle 単位で claim できるので楽です。

incoming/
  order-123/
    payload.csv
    manifest.json

これなら、bundle directory を 1 回 rename するだけで所有権を取れます。

4.4. startup / overflow / 再接続時は full rescan する

これはかなり大事です。

アプリ起動前から置かれていたファイルは、イベントでは拾えません
overflow が起きたら、個別イベント列は信用しにくくなります
ネットワーク共有や一時切断が絡むと、「その間の何か」が抜ける前提で見た方が安全です

なので、少なくとも次のタイミングでは full rescan を入れた方がよいです。

起動時
Error 受信時
watcher を作り直した直後
定期的な保険として一定間隔ごと

ここでの思想は、「watcher は差分のヒント、再スキャンは整合性の回復」です。

4.5. idempotency を前提にする

FileSystemWatcher を使うと、同じ対象を複数回見に行くことになります。これはバグではなく、設計として受け入れた方が安定します。

具体的には、こんな具合です。

manifest に IdempotencyKey を入れる
すでに処理済みなら副作用を再実行しない
archive 済み / DB 記録済み / 送信済みを照合できるようにする
full rescan しても「同じものをもう一度安全に見る」だけにする

exactly-once をイベントだけで作ろうとすると、だいぶ苦しくなります。 at-least-once を受け入れて、最後を idempotency で締めた方が実務では強いです。

5. 擬似コード（抜粋）

5.1. 典型的な失敗パターン

using var watcher = new FileSystemWatcher(incomingDir)
{
    Filter = "*.csv",
    IncludeSubdirectories = false,
    EnableRaisingEvents = true,
    InternalBufferSize = 64 * 1024
};

watcher.Created += (_, e) =>
{
    // Created = 完了通知、と思い込んでいる
    ProcessFile(e.FullPath);
};

watcher.Changed += (_, e) =>
{
    // 何度も来るので、とりあえずもう一回処理
    ProcessFile(e.FullPath);
};

watcher.Error += (_, e) =>
{
    Console.WriteLine(e.GetException());
    // 回復しない
};

問題点は 4 つあります。

Created / Changed をそのまま業務処理に結びつけている
完了判定が無い
overflow 時に full rescan しない
同じファイルを何回処理しても止める仕組みが無い

5.2. 正しい方向の例（雑に書くとこう）

private readonly SemaphoreSlim _scanSignal = new(0, int.MaxValue);
private int _scanRequested = 0;
private int _fullRescanRequested = 0;

void OnAnyChange(object? sender, FileSystemEventArgs e)
{
    RequestScan(full: false);
}

void OnRenamed(object? sender, RenamedEventArgs e)
{
    RequestScan(full: false);
}

void OnError(object? sender, ErrorEventArgs e)
{
    Log(e.GetException());
    RequestScan(full: true);
}

void RequestScan(bool full)
{
    if (full)
    {
        Interlocked.Exchange(ref _fullRescanRequested, 1);
    }

    if (Interlocked.Exchange(ref _scanRequested, 1) == 0)
    {
        _scanSignal.Release();
    }
}

async Task ScannerLoopAsync(CancellationToken cancellationToken)
{
    RequestScan(full: true); // startup scan

    while (!cancellationToken.IsCancellationRequested)
    {
        await _scanSignal.WaitAsync(cancellationToken);

        // 通知バーストを少しまとめる
        await Task.Delay(TimeSpan.FromMilliseconds(200), cancellationToken);

        Interlocked.Exchange(ref _scanRequested, 0);
        bool full = Interlocked.Exchange(ref _fullRescanRequested, 0) == 1;

        foreach (var bundle in EnumerateReadyBundles(incomingDir, full))
        {
            var claimedPath = Path.Combine(processingDir, bundle.Name);

            if (!TryClaimByRename(bundle.Path, claimedPath))
            {
                continue; // 他ワーカーが先に取得
            }

            var manifest = ReadManifest(Path.Combine(claimedPath, "manifest.json"));

            if (AlreadyProcessed(manifest.IdempotencyKey))
            {
                MoveToArchive(claimedPath, archiveDir);
                continue;
            }

            ProcessBundle(claimedPath);
            RecordProcessed(manifest.IdempotencyKey);
            MoveToArchive(claimedPath, archiveDir);
        }

        if (Volatile.Read(ref _scanRequested) == 1)
        {
            _scanSignal.Release(); // 走査中に来た通知を取りこぼさない
        }
    }
}

この例で大事なのは、細かい API ではなく流れです。

通知は scan request に畳む
走査で ready を見つける
claim を取る
idempotency を確認する
処理して記録し、archive に動かす

FileSystemWatcher のイベントは、ここでは trigger でしかありません。

6. ざっくり使い分け

単一受信ワーカー / 自分で送信側も直せるまずは temp -> close -> rename と startup scan。これだけでもかなり安定します。
複数受信ワーカーがいる上に加えて incoming -> processing の claim rename を入れた方がよいです。
高頻度で通知が多い Filter / NotifyFilter / IncludeSubdirectories を絞り、イベントハンドラを極小化します。InternalBufferSize の調整はそのあとです。
overflow して困る / 取りこぼしが許されない full rescan を前提にし、それでも厳しいなら FileSystemWatcher 単体に賭けない方がよいです。Windows 限定なら USN change journal も選択肢になります。
相手システムの書き方を制御できない完了条件を推測で補うより、公開プロトコルを交渉できないかを先に考えた方が安全です。無理なら、保証水準を下げた上で idempotent に受ける設計に寄せます。

最後の 2 項目は、わりと大事な撤退判断です。 FileSystemWatcher は便利ですが、万能の真実検出器ではありません。

7. まとめ

FileSystemWatcher は完了通知の代わりにはなりません。真実はイベント列ではなく、いまディスク上に見えている状態にあります。完了は temp -> close -> rename / replace や done / manifest で明示し、所有権は claim を原子的に取って決める。設計の本体はここにあります。

Created で即処理する、Changed の回数や順序を信じる、Changed が止まったら完了扱いにする、InternalBufferSize だけで安心する、Error を見たのに回復しない――どれも避けたい設計です。代わりに、通知は再スキャン要求に畳み、startup / overflow / 再接続では full rescan を入れ、claim rename で所有権を取り、重複と再走査は idempotency で受け止めます。

つまり、FileSystemWatcher では「イベントを受けたこと」と「処理してよいこと」を同じにしないのがコツです。ここを分けるだけで、たまにだけ壊れるタイプの監視処理がかなり減ります。

8. 参考資料

この記事のサンプルコード一式（ライブラリ、デモ、ユニットテスト） https://github.com/gomurin0428/komurasoft-blog-samples/tree/main/filesystemwatcher-safe-basics
関連記事: ファイル連携の排他制御の基礎知識 - ファイルロックと原子的 claim のベストプラクティス
FileSystemWatcher Class (System.IO)
System.IO.FileSystemWatcher class - .NET
FileSystemWatcher.InternalBufferSize Property (System.IO)
FileSystemWatcher.Error Event (System.IO)
FileSystemWatcher.Created Event (System.IO)
FileSystemWatcher.Changed Event (System.IO)
FileSystemWatcher.Renamed Event (System.IO)
Change Journals - Win32 apps

同じタグを共有する最新の記事です。さらに近い話題で知識を深められます。

このテーマがつながるサービス

この記事は次のサービスページにつながります。近い入口からご覧ください。

Windowsアプリ開発

FileSystemWatcher を使うファイル連携や監視ツールは、Windowsアプリ開発の中でも実務でよく出るテーマです。

サービスを見るお問い合わせ

技術相談・設計レビュー

取りこぼし対策、再スキャン、完了判定を設計として整理したい場合は、技術相談・設計レビューとして相性がよいです。

サービスを見るお問い合わせ

著者プロフィール

記事の著者プロフィールページです。

小村豪

合同会社小村ソフト代表

Windows ソフト開発、技術相談、不具合調査を中心に、既存資産が残る案件や原因が見えにくい障害調査に強みがあります。

プロフィールを見るお問い合わせ

公開リンク

GitHub LinkedIn X COM_BLAS COM_BigDecimal

ブログ一覧に戻る

FileSystemWatcher実務ガイド - 取りこぼしと重複対策

目次

1. まず結論（ひとことで）

2. `FileSystemWatcher` の使い方で起きやすい勘違いパターン（図）

2.1. `Created` を完了通知だと思う

2.2. `Changed` の回数と順序を信じる

2.3. 内部バッファあふれで変更を失う

3. アンチパターン

3.1. イベントハンドラの中でそのまま処理する

3.2. イベント列から真実の状態を復元しようとする

3.3. `Changed` が止まったら完了扱い

3.4. `InternalBufferSize` を上げれば解決したと思う

3.5. `Error` をログだけ出して無視する

4. ベストプラクティス

4.1. 通知は「再スキャン要求」に畳む

4.2. 完了条件は送信側で明示する

4.3. 受信側は claim を原子的に取る

4.4. startup / overflow / 再接続時は full rescan する

4.5. idempotency を前提にする

5. 擬似コード（抜粋）

5.1. 典型的な失敗パターン

5.2. 正しい方向の例（雑に書くとこう）

6. ざっくり使い分け

7. まとめ

8. 参考資料

.NET Generic HostとBackgroundServiceをデスクトップアプリで使う理由

シリアル通信アプリの落とし穴 - 再接続とログ設計まで

.NET Frameworkから.NETへの移行前チェックリスト

.NET Generic Hostとは - DI・設定・ログの土台

.NET Native AOTとは - JITやtrimmingとの違い

関連トピック

Windows技術トピック

このテーマがつながるサービス

Windowsアプリ開発

技術相談・設計レビュー

著者プロフィール

小村豪

目次

1. まず結論（ひとことで）

2. FileSystemWatcher の使い方で起きやすい勘違いパターン（図）

2.1. Created を完了通知だと思う

2.2. Changed の回数と順序を信じる

2.3. 内部バッファあふれで変更を失う

3. アンチパターン

3.1. イベントハンドラの中でそのまま処理する

3.2. イベント列から真実の状態を復元しようとする

3.3. Changed が止まったら完了扱い

3.4. InternalBufferSize を上げれば解決したと思う

3.5. Error をログだけ出して無視する

4. ベストプラクティス

4.1. 通知は「再スキャン要求」に畳む

4.2. 完了条件は送信側で明示する

4.3. 受信側は claim を原子的に取る

4.4. startup / overflow / 再接続時は full rescan する

4.5. idempotency を前提にする

5. 擬似コード（抜粋）

5.1. 典型的な失敗パターン

5.2. 正しい方向の例（雑に書くとこう）

6. ざっくり使い分け

7. まとめ

8. 参考資料

関連する記事

関連トピック

このテーマがつながるサービス

著者プロフィール

小村 豪

2. `FileSystemWatcher` の使い方で起きやすい勘違いパターン（図）

2.1. `Created` を完了通知だと思う

2.2. `Changed` の回数と順序を信じる

3.3. `Changed` が止まったら完了扱い

3.4. `InternalBufferSize` を上げれば解決したと思う

3.5. `Error` をログだけ出して無視する

小村豪