Handle non-existent root directory in PhysicalFilesWatcher by svick · Pull Request #126411 · dotnet/runtime

svick · 2026-04-01T15:09:24Z

Handle non-existent root directory in PhysicalFilesWatcher

Problem

When PhysicalFileProvider is constructed with a root directory that does not yet exist (e.g., a configuration file path whose parent directory hasn't been created), Watch() fails because FileSystemWatcher cannot watch a non-existent directory. This commonly occurs with AddJsonFile when the config file's parent directory is missing at startup.

FileConfigurationSource had its own solution: watching the closest existing directory instead. The problem with this is that it commonly watched too much of the system (possibly even all of it), causing significant performance issues.

Solution

PhysicalFilesWatcher now gracefully handles a missing root directory by deferring FileSystemWatcher activation until the root appears. A PendingCreationWatcher monitors the nearest existing ancestor directory using a non-recursive FileSystemWatcher and cascades through intermediate directory levels as they are created. Once the root directory exists, the main recursive FileSystemWatcher is enabled and any already-existing watched entries are reported.

Callers always receive normal FSW-backed change tokens — no re-registration is needed when the root directory appears later.

FileConfigurationSource then uses PhysicalFilesWatcher on a directory that may not exist, which is now handled well.

Changes

File	Description
`PhysicalFilesWatcher.cs`	Added `PendingCreationWatcher` inner class that watches for a non-existent directory to be created. `TryEnableFileSystemWatcher` defers to `EnsureRootCreationWatcher` when `_root` doesn't exist, with a callback to retry once it appears. `ReportExistingWatchedEntries` fires tokens for entries created before the FSW was active. The constructor normalizes `_root` to always have a trailing separator and validates FSW path relationship. `OnFileSystemEntryChange` now uses `DirectoryInfo` for directory paths so exclusion filters work correctly, and guards against events outside `_root`. `OnError` now also notifies wildcard tokens.
`PhysicalFileProvider.cs`	Constructor no longer throws `DirectoryNotFoundException` for a missing root. Updated `Watch` doc comments to include directories. Removed duplicate `_pathSeparators` field in favor of `PathUtils.PathSeparators`.
`FileConfigurationSource.cs`	`ResolveFileProvider` creates the `PhysicalFileProvider` with the file's immediate parent directory (even if missing), relying on the watcher to handle the non-existent case.
`PollingFileChangeToken.cs`	`GetLastWriteTimeUtc` now falls back to checking `DirectoryInfo` when `FileInfo.Exists` is false, so polling correctly detects directory changes. `DirectoryInfo` is created lazily.
`PathUtils.cs`	`PathSeparators` made `internal` for reuse across files.
`PhysicalFilesWatcherTests.cs`	Tests for missing root (file path and wildcard), root deleted and recreated, subdirectory create/delete/recreate cycles, directory watch tokens, hidden directory exclusion, FSW path above/below root, sibling directory prefix isolation, and active polling variants.
`FileConfigurationProviderTest.cs`	Integration test verifying the watch token fires when a file is created inside a previously-missing directory.
`PhysicalFileProviderTests.cs`	Added test for constructing with non-existent root. Fixed `TokenFiredForGlobbingPatternsPointingToSubDirectory` path length issue on .NET Framework.

When PhysicalFileProvider is constructed with a root directory that does not yet exist, PhysicalFilesWatcher now defers FileSystemWatcher activation until the root appears. A PendingCreationWatcher monitors the nearest existing ancestor using a non-recursive FileSystemWatcher and cascades through intermediate directory levels as they are created. Once the root directory exists, the main recursive FileSystemWatcher is enabled and any already-existing watched entries are reported. Callers always receive normal FSW-backed change tokens — no re-registration is needed when the root directory appears later. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dotnet-policy-service · 2026-04-01T15:10:51Z

Tagging subscribers to this area: @dotnet/area-extensions-filesystem
See info in area-owners.md if you want to be subscribed.

Copilot

Pull request overview

This PR updates the Microsoft.Extensions.FileProviders.Physical watcher stack (and related configuration/file-globbing components) to handle roots that don’t exist yet by deferring FileSystemWatcher activation until the directory appears, avoiding broad/incorrect ancestor watching and improving correctness for configuration reload-on-change scenarios.

Changes:

Add deferred root-creation monitoring to PhysicalFilesWatcher (including a cascading non-recursive watcher for intermediate directories) and report already-existing entries once the root appears.
Relax PhysicalFileProvider to allow construction with missing roots; update configuration source resolution to use the file’s immediate parent directory even when missing.
Extend polling and globbing helpers/tests to correctly handle directory paths and missing-directory lifecycles.