语言运行时标准库JIT编译编译器【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址https://gitcode.com/GitHub_Trending/runtime6/runtime点击查看免费下载Microsoft.Extensions.FileProviders.Physical是 .NET 运行时仓库中负责从磁盘查找文件、并监视磁盘变化的官方实现。它以PhysicalFileProvider为核心类型向应用提供统一的IFileProvider抽象既可以基于FileSystemWatcher实时响应文件变更也可以在FileSystemWatcher失效的场景如挂载盘、网络共享、WebAssembly/移动端下自动退化为按固定间隔轮询。读完本文你将掌握该组件的完整 API 面、路径安全与排除过滤规则、两种变更监视机制的切换开关以及其底层源码级的工作原理可直接用于构建配置热重载、静态资源监视、模板引擎文件系统等真实场景。一、组件定位IFileProvider 抽象的物理实现在 .NET 的扩展体系中文件访问被抽象为IFileProvider接口从而让上层框架配置系统、静态文件中间件、Razor 视图引擎等不依赖具体文件系统形态。Microsoft.Extensions.FileProviders.Physical正是该抽象的本地磁盘实现通过GetFileInfo(subpath)在磁盘上定位单个文件通过GetDirectoryContents(subpath)枚举目录内容通过Watch(filter)监视文件/目录变化并返回IChangeToken。正如该组件 README 所述它的核心价值在于从磁盘查找文件并且既可以基于FileSystemWatcher、也可以基于轮询来监视磁盘变化。它的公开 API 面定义在 ref/Microsoft.Extensions.FileProviders.Physical.cs包含以下公开类型类型职责PhysicalFileProvider面向应用的入口实现IFileProvider负责查找与监视PhysicalFileInfo单个物理文件的IFileInfo实现PhysicalDirectoryInfo单个物理目录的IFileInfoIDirectoryContents实现PhysicalDirectoryContents目录内容枚举实现IDirectoryContentsPhysicalFilesWatcher底层文件系统监视器封装FileSystemWatcher与轮询逻辑PollingFileChangeToken针对单个文件/目录的轮询变更令牌PollingWildCardChangeToken针对 glob 通配符模式的轮询变更令牌ExclusionFilters文件/目录排除过滤规则[Flags]枚举该程序集以 NuGet 包Microsoft.Extensions.FileProviders.Physical的形式对外发布是 .NET 通用主机Generic Host配置热重载、ASP.NET Core 静态文件与 Razor 热编译的基础设施之一。二、快速上手构造与三个核心方法1. 构造函数与 Root 规则PhysicalFileProvider提供两个构造函数见 PhysicalFileProvider.cspublic PhysicalFileProvider(string root); public PhysicalFileProvider(string root, ExclusionFilters filters);关键约束root必须是绝对路径否则构造函数抛出ArgumentException源码通过Path.IsPathRooted校验root对应的目录不要求存在——即使目录尚未创建也可以创建 provider 并注册监视底层会等待目录出现内部通过Path.GetFullPath规范化并用PathUtils.EnsureTrailingSlash统一补上结尾分隔符保证后续路径比较时只匹配完整目录名。默认构造使用ExclusionFilters.Sensitive过滤规则详见下文第四节。2. GetFileInfo定位单个文件IFileInfo info provider.GetFileInfo(wwwroot/index.html); if (info.Exists) { using Stream stream info.CreateReadStream(); // 读取内容... }GetFileInfo将相对路径直接映射到物理目录见 PhysicalFileProvider.cs其行为规则包括返回的IFileInfo调用方必须检查Exists属性因为失败场景返回的是NotFoundFileInfo而非异常允许以/或\开头的相对路径会TrimStart去掉前导分隔符拒绝绝对路径Path.IsPathRooted时返回 NotFound拒绝包含非法路径字符的输入PathUtils.HasInvalidPathChars拒绝逃逸到 root 之外的路径如../命中排除规则的文件同样返回NotFoundFileInfo。PhysicalFileInfo包装FileInfo见 PhysicalFileInfo.cs其CreateReadStream()使用FileShare.ReadWrite打开流并采用FileOptions.Asynchronous | FileOptions.SequentialScan、bufferSize 设为 1避免 FileStream 分配内部缓冲来适配流式读取。3. GetDirectoryContents枚举目录IDirectoryContents contents provider.GetDirectoryContents(wwwroot); if (contents.Exists) { foreach (IFileInfo entry in contents) { Console.WriteLine(${entry.Name} (IsDirectory{entry.IsDirectory})); } }目录枚举基于DirectoryInfo.EnumerateFileSystemInfos()惰性展开见 PhysicalDirectoryInfo.cs并在展开过程中应用排除过滤。目录不存在、路径非法、绝对路径或目录遍历异常时返回NotFoundDirectoryContents.Singleton。对于目录条目Length恒为 -1、IsDirectory恒为 trueCreateReadStream()会抛出InvalidOperationException。三、路径安全如何杜绝目录穿越PhysicalFileProvider对路径逃逸做了两层防护见 PathUtils.cs 与 PhysicalFileProvider.cs语法层校验PathNavigatesAboveRoot用StringTokenizer按分隔符逐段解析路径遇到..时深度减一一旦深度为 -1 立即判定越界同时忽略.与空段。物理层校验IsUnderneathRoot将合并后的完整路径与Root做OrdinalIgnoreCase前缀比较注意 Root 已补结尾斜杠防止通过C:\root2这类前缀欺骗绕过检查。两条路径中任一条失败都会让GetFileInfo返回 NotFound、让Watch返回NullChangeToken。测试用例GetFileInfoReturnsNotFoundFileInfoForRelativePathAboveRootPath、GetFileInfoReturnsNotFoundFileInfoForRelativePathThatNavigatesAboveRoot等在 PhysicalFileProviderTests.cs 中覆盖了这些边界。四、ExclusionFilters排除敏感文件ExclusionFilters是一个[Flags]枚举见 ExclusionFilters.cs控制哪些文件/目录从查找与监视结果中被排除成员值含义None0不排除任何文件DotPrefixed0x0001名称以.开头如.gitignore、.envHidden0x0002设置了FileAttributes.Hidden属性System0x0004设置了FileAttributes.System属性Sensitive7等价于DotPrefixed \| Hidden \| System为默认值由于是位标志可以自由组合例如ExclusionFilters.Hidden | ExclusionFilters.System表示仅排除隐藏与系统文件、但保留.dot文件。测试 ExclusionFilterTests.cs 与用例GetFileInfoReturnsNotFoundFileInfoForHiddenFile、GetFileInfoReturnsFileInfoWhenExclusionDisabled验证了各组合的行为。该过滤同时作用于GetFileInfo、GetDirectoryContents与底层 watcher 的事件分发。五、变更监视的两种机制FileSystemWatcher 与轮询这是该组件最核心的设计。Watch(filter)返回的IChangeToken在文件/目录被新增、修改或删除时触发。触发机制有两种1. 基于 FileSystemWatcher默认默认情况下PhysicalFileProvider使用FileSystemWatcher监听事件见 PhysicalFileProvider.cs 的说明。PhysicalFilesWatcher订阅了Created、Changed、Renamed、Deleted、Error五个事件Renamed事件还会递归通知被重命名目录下的所有条目见 PhysicalFilesWatcher.cs。2. 基于轮询PollingFileSystemWatcher在部分场景下无效例如挂载盘mounted drives、网络共享、某些容器/WSL 路径。此时需要轮询。切换方式有两种方式 A环境变量全局开启设置环境变量DOTNET_USE_POLLING_FILE_WATCHER为1或true不区分大小写即可见 PhysicalFileProvider.cs# Linux / macOS export DOTNET_USE_POLLING_FILE_WATCHER1 dotnet run # Windows (PowerShell) $env:DOTNET_USE_POLLING_FILE_WATCHER1 dotnet run方式 B通过属性编程式控制var provider new PhysicalFileProvider(/data/app) { UsePollingFileWatcher true, UseActivePolling true, };两个属性的语义见 PhysicalFileProvider.csUsePollingFileWatcher是否使用轮询来判断文件变化。默认值由DOTNET_USE_POLLING_FILE_WATCHER决定UseActivePolling仅在UsePollingFileWatcher为 true 时生效。为 true 时Watch返回的 tokenActiveChangeCallbacks为 true主动通过定时器回调触发变更为 false 时 token 是被动的调用方必须自行轮询HasChanged。平台自动回退在 Browser、WASI、iOS非 Mac Catalyst、tvOS 平台FileSystemWatcher不受支持CreateFileWatcher会自动把两个属性都置为 true 并跳过 FileSystemWatcher见 PhysicalFileProvider.cs若在构造PhysicalFilesWatcher时显式传入 FileSystemWatcher这些平台会直接抛出PlatformNotSupportedException。属性还受时序约束一旦底层 watcher 已被初始化再修改UsePollingFileWatcher会抛出InvalidOperationException。3. 轮询令牌的底层原理PollingFileChangeToken单文件/目录默认每4 秒轮询一次PhysicalFilesWatcher.DefaultPollingInterval TimeSpan.FromSeconds(4)通过比较FileSystemInfo.LastWriteTimeUtc判断变化见 PollingFileChangeToken.cs。文件不存在时回退检查同路径的DirectoryInfo瞬时 IO 异常按无变化处理下轮重试。一旦HasChanged变为 true 就永远为 truetoken不可复用。PollingWildCardChangeTokenglob 通配符用Matcher执行模式匹配对匹配到的文件集合路径 最后写入时间计算SHA-256 哈希两次扫描哈希不同即判定变化见 PollingWildCardChangeToken.cs因此能捕获新增文件这类单个文件 token 无法感知的变化扫描失败如网络盘掉线同样按无变化处理并下轮重试。主动轮询时PhysicalFilesWatcher通过一个NonCapturingTimer周期驱动所有已注册轮询 tokenRaiseChangeEvents见 PhysicalFilesWatcher.csIO 异常被捕获并保留 token 等待下次轮询。六、Watch 与 glob 模式Watch(filter)接受 glob 通配符模式由Microsoft.Extensions.FileSystemGlobbing.Matcher解释见 PhysicalFileProvider.cs// 监视根目录下所有 .cs 文件递归子目录 IChangeToken token1 provider.Watch(**/*.cs); // 监视根目录下所有文件 IChangeToken token2 provider.Watch(*.*); // 监视子目录下所有 .cshtml IChangeToken token3 provider.Watch(subDirectory/**/*.cshtml); // 监视单个具体文件 IChangeToken token4 provider.Watch(appsettings.json);规则与边界监视对象不要求已存在——文件/目录可以稍后创建这正是热重载场景的基础模式按相对 root 解释前导/或\会被去除非法 filter 字符含非法文件名字符以外的*、|、?之外字符见PathUtils.GetInvalidFilterChars、绝对路径、越界路径均返回NullChangeToken.Singleton带*的模式或目录路径走通配符 token 路径否则走单文件 token 路径见 PhysicalFilesWatcher.cs单文件 token 与通配符 token 在PhysicalFilesWatcher内部各自维护ConcurrentDictionary_filePathTokenLookup/_wildcardTokenLookup相同模式复用同一个CancellationChangeToken测试TokenIsSameForSamePath验证了这一点。七、底层 PhysicalFilesWatcher 的工程细节PhysicalFilesWatcher是整个监视机制的中枢见 PhysicalFilesWatcher.cs有几点值得注意的实现细节懒启用与自动关闭只有注册了至少一个 token 才启用FileSystemWatcher.EnableRaisingEvents所有 token 消耗完毕后自动关闭TryDisableFileSystemWatcher避免无谓的系统资源占用。递归监视的动态开关IncludeSubdirectories仅在存在需要子目录的 token 时才开启如模式含/或**或 watcher 监视的是 root 的祖先目录避免在 Linux 上为每个子目录创建 inotify 描述符——这是PollingFileProviderShouldntConsumeINotifyInstances测试所守护的性能点。root 尚未存在当 root 目录不存在时PendingCreationWatcher会向上找到最近的已存在祖先目录用非递归 watcher 逐级等待目录链创建root 出现后再启用主 watcher并补扫已存在的条目ReportExistingWatchedEntries以覆盖监视空窗期。错误处理与自我修复InternalBufferOverflowException缓冲溢出、事件丢失与DirectoryNotFoundException目录被删/移动会立即通知所有 token 并重试同类型同错误码的重复错误会被去重防止不可监视文件系统如网络盘导致的取消-重建死循环IsSameError见 PhysicalFilesWatcher.cs。构造PhysicalFilesWatcher时若pollForChanges为 false 但未提供 FileSystemWatcher会抛出ArgumentNullException传入的 FileSystemWatcher 路径必须与 root 有祖先/后代关系否则抛出ArgumentException。八、典型应用场景结合以上机制PhysicalFileProvider的典型用法包括配置热重载对appsettings.json注册Watch结合IChangeToken.RegisterChangeCallback在文件变更时重新加载配置——这也是DOTNET_USE_POLLING_FILE_WATCHER环境变量在容器、CI 与挂载卷环境中被广泛使用的场景。静态资源监视Web 宿主在开发模式下用它对wwwroot建立文件提供程序实现静态文件的即时生效与目录浏览。模板/内容引擎将磁盘目录作为内容源统一通过IFileProvider接口向业务层暴露便于后续替换为嵌入式EmbeddedFileProvider或内存ManifestEmbeddedFileProvider实现。无法使用 FileSystemWatcher 的平台在 WASM/移动端自动启用轮询保证跨平台行为一致。读者若希望深入实现细节可重点阅读 PhysicalFileProvider.cs、PhysicalFilesWatcher.cs 两个核心文件并以 PhysicalFileProviderTests.cs、PhysicalFilesWatcherTests.cs、PollingWildCardChangeTokenTest.cs内含TestClock、MockFileSystemWatcher等测试基建作为行为契约参考。九、小结Microsoft.Extensions.FileProviders.Physical以极小的 API 表面完成了查找 监视两大职责PhysicalFileProvider提供GetFileInfo/GetDirectoryContents/Watch三个核心入口ExclusionFilters提供灵活的排除策略而PhysicalFilesWatcher在FileSystemWatcher与 4 秒间隔轮询之间自动或按需切换并内建了路径越界防护、子目录监视优化、目录缺失恢复与错误自我修复等工程细节。理解它的机制无论是排查热重载失效、在挂载卷上开启轮询还是评估自定义文件系统实现都能有的放矢。赞分享语言运行时标准库JIT编译编译器【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址https://gitcode.com/GitHub_Trending/runtime6/runtime点击查看免费下载相关推荐xv6 RISC-V入门指南如何在10分钟内启动你的第一个教学操作系统xv6 RISC V入门指南如何在10分钟内启动你的第一个教学操作系统 xv6 RISC V是一款基于RISC V架构的教学操作系统专为学习操作系统原理而设Turso.Data.Native 深度解析Turso .NET 提供程序的原生运行时打包与加载机制Turso.Data.Native 深度解析Turso .NET 提供程序的原生运行时打包与加载机制 Turso.Data.Native 是 Turso .N数据库嵌入式数据库关系型数据库Automatisch Dropbox 触发器深度解析监听新文件与新文件夹的轮询机制与配置实战Automatisch Dropbox 触发器深度解析监听新文件与新文件夹的轮询机制与配置实战 Automatisch开源 Zapier 替代品通过 Dr工作流自动化后端前端低代码任务调度创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考