把 C# 静态调用（DateTime/File/Enviro…

当已有包装器或内置抽象（TimeProvider、IFileSystem、IEnvironmentReader 等），需要按限定范围把生产代码里的静态调用替换为注入式调用并保持行为不变时使用。

适用场景

解决思路

1. 确认前置条件：验证包装器/抽象在项目中已可用（TimeProvider 需 .NET 8+ 或引用 Microsoft.Bcl.TimeProvider；System.IO.Abstractions 需引用对应 NuGet 包），并确认生产组合根（Program.cs、Startup.cs 或手动构造点）已注册；若缺少包/包装器/注册且用户未明确授权依赖变更，则停止编辑并报告缺失的前置条件。
2. 列出范围内所有 .cs 文件，排除测试项目、obj/、bin/ 和生成代码。
3. 在编辑前锁定并统计成员集合：使用用户指定的确切成员，或从请求与发现的调用点推断最小无歧义集合，记录该集合并搜索每个成员、捕获文件/行清单，编辑过程中不得更改集合或从部分读取推断计数。
4. 逐文件规划迁移：识别包含调用点的类、检查构造函数是否已注入该依赖、确定每个调用点的替换表达式；只迁移用户明确指定的成员，不触碰相邻成员（如只迁移 DateTime.UtcNow 时保留 DateTime.Now），不触碰用户未指定的文件，保留标注为有意为之的调用点（如 // intentional local time），并把有意保留的内容列入“Remaining (out of scope)”。
5. 按替换映射表执行替换：DateTime.Now → _timeProvider.GetLocalNow().LocalDateTime；DateTime.UtcNow → _timeProvider.GetUtcNow().UtcDateTime；DateTime.Today → _timeProvider.GetLocalNow().LocalDateTime.Date；DateTimeOffset.Now → _timeProvider.GetLocalNow()；DateTimeOffset.UtcNow → _timeProvider.GetUtcNow()；File.ReadAllText(path) → _fileSystem.File.ReadAllText(path)；File.WriteAllText(path, text) → _fileSystem.File.WriteAllText(path, text)；File.Exists(path) → _fileSystem.File.Exists(path)；Directory.Exists(path) → _fileSystem.Directory.Exists(path)；Environment.GetEnvironmentVariable(name) → _env.GetEnvironmentVariable(name)；Console.WriteLine(msg) → _console.WriteLine(msg)；Process.Start(info) → _processRunner.Start(info)；其他同类成员按相同模式处理。
6. 保留 DateTimeKind：DateTime.UtcNow 的 Kind 为 Utc，必须用 .UtcDateTime（不能用 .DateTime，否则 Kind 变为 Unspecified）；DateTime.Now 的 Kind 为 Local，必须用 .LocalDateTime；当调用点本身消费 DateTimeOffset（字段/参数/返回值已是 DateTimeOffset）时，直接赋值 DateTimeOffset，不加 .UtcDateTime/.LocalDateTime 后缀；匹配目标成员类型，不把 DateTime 字段改成 DateTimeOffset。
7. 保持读取的次数、顺序和位置：每个原始时钟读取就地替换为一次 provider 读取，不得提升、缓存或合并两次读取为一个共享的 now 局部变量，即使在同一对象初始化器或方法中；仅当原始代码已捕获并复用时才复用值。
8. 添加构造函数注入：主构造函数（C# 12+）在参数列表中加入依赖；传统构造函数添加 private readonly 字段与构造参数，字段命名遵循现有约定（_camelCase 或 m_camelCase）。
9. 对静态类使用环境上下文接缝（ambient seam），不要转换为非静态类：用 AsyncLocal<TimeProvider?> 存储，属性默认返回 TimeProvider.System，提供 OverrideClock(TimeProvider) 返回 IDisposable 作用域以恢复先前值；生产环境无需启动时修改；测试为每个异步流创建新的 fake/provider 并释放作用域，嵌套释放恢复外层 provider；AsyncLocal<T> 保证 await 后各测试流隔离，不要在槽中存可变栈/列表或让多个子流共享同一 fake；为替换、嵌套恢复和并行异步隔离添加针对性测试；同一形状适用于 IFileSystem 和自定义包装器。
10. 执行替换：把静态调用替换为包装器调用，保留周围表达式结构和求值顺序，必要时添加 using 指令（TimeProvider 无需 using；IFileSystem 需 using System.IO.Abstractions;；IHttpClientFactory 通常已有 using System.Net.Http;；自定义包装器用 using <wrapper namespace>;）。
11. 编辑后重复精确搜索，要求所有范围内生产文件中出现次数为零；重新打开每个改动文件与编辑前清单比对；同时验证排他范围：搜索或比对用户明确要求保留的文件，确认其原始静态调用和内容不变；单文件迁移也要报告两个数字：范围内 N/N 已替换、指定范围外 M 个调用已保留。
12. 更新受影响的测试文件：为测试类实例化添加新参数；TimeProvider 用 Microsoft.Extensions.TimeProvider.Testing 的 new FakeTimeProvider()；IFileSystem 用 System.IO.Abstractions.TestingHelpers 的 new MockFileSystem()；自定义包装器用 new Mock<IWrapperName>() 或手写 fake；保留依赖原始静态结果的所有可观察分支（如 Environment.GetEnvironmentVariable(name) ?? "production" 需覆盖已配置值和 null/缺失回退两种情况）；保留现有测试框架与断言风格，但至少包含一个配置/fake 值断言和一个回退/错误路径断言；当请求明确要求测试不再访问真实文件或环境时，编辑后搜索测试中是否还有临时文件、真实磁盘或环境修改 API，保留范围外的有意集成测试。
13. 构建验证：对受影响的生产项目执行 dotnet build <project.csproj>，当存在或改动了测试时执行 dotnet test <affected-test-project.csproj>；只报告实际观察到的结果，仅当退出码为 0 才写“build succeeded”，失败（含 restore/NuGet 失败如 assets file not found）要引用错误并修复（dotnet restore、添加缺失包）或给出精确阻塞点；构建失败时按原因处理：缺少 using 则添加、缺少 NuGet 包仅在明确授权依赖变更时添加否则报告并停止、测试构造函数不匹配则更新测试实例化、调用歧义则完全限定包装器调用；不得用构建成功替代请求的测试运行。
14. 报告变更：即使只有一个生产文件和一个测试文件，也要包含精确的范围内替换计数、已验证未变的指定范围外文件或调用、以及针对性构建/测试结果，格式包含 Pattern、Scope、Files Modified (production) 表格（文件、替换调用点数、注入方式）、Files Modified (tests) 表格、Remaining (out of scope) 列表。
15. 按验证清单自检：范围内所有调用点已替换；前后精确成员搜索证明范围内出现次数为零；未修改范围外调用点；有意保留的调用点未被触碰并已报告；所有受影响类已添加构造函数注入；字段命名符合现有约定；已添加所需 using；已引用所需 NuGet 包；构建成功且报告与实际退出码一致；测试文件已用合适测试替身更新；已配置、回退/null 和错误分支仍有直接测试证据；存在或改动测试时针对性测试已成功运行；未引入行为变化（包装器直接委托静态）；静态读取一对一替换、未提升/缓存/合并；DateTimeKind 已保留（原 DateTime.UtcNow 保持 Utc 用 .UtcDateTime，原 DateTime.Now 保持 Local 用 .LocalDateTime）。

适用边界 · 注意事项

• 尚无包装器或抽象且需要从零设计（应先用 generate-testability-wrappers；TimeProvider、IFileSystem 等内置抽象视为已存在）。
• 用户只想检测静态依赖而非迁移（应使用 detect-static-dependencies）。
• 用户主要要求确定性的行为测试且尚未选定生产接缝（应使用 testability-obstacle），或需要在测试框架之间迁移。