Document breaking change: PhysicalFilesWatcher validates root and FileSystemWatcher paths

[Copilot]

PhysicalFilesWatcher constructors now validate the root argument and its relationship to a supplied FileSystemWatcher.Path, rejecting combinations at construction time that previously succeeded but generally didn't work correctly.

New breaking-change article

• Added docs/core/compatibility/extensions/11/physicalfileswatcher-validates-root-path.md covering:
  • root is now normalized via Path.GetFullPath(); null throws ArgumentNullException, invalid paths propagate the Path.GetFullPath() exception.
  • A nonempty FileSystemWatcher.Path unrelated to root now throws ArgumentException. It must be empty, equal to root, or an ancestor/descendant of it.
  • A nonexistent root directory remains valid (watching is deferred until it's created).

Index updates

• Added the article to the .NET 11 toc.yml and 11.md under the Extensions area.

Example of the now-invalid pattern called out in the article:

using var fileSystemWatcher = new FileSystemWatcher(unrelatedPath);
using var watcher = new PhysicalFilesWatcher(
    root,
    fileSystemWatcher,
    pollForChanges: false); // now throws ArgumentException

• Fixes [Breaking change]: PhysicalFilesWatcher validates root and FileSystemWatcher paths #55756

---

Internal previews

File	Preview link
docs/core/compatibility/11.md	Learn preview
docs/core/compatibility/extensions/11/physicalfileswatcher-validates-root-path.md	Learn preview
docs/core/compatibility/toc.yml	Learn preview

Build report

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.