SuperAPI AI 工具集

maintaining-binary-log-compatibility

部署与运维

查看项目

更新于 10-15 21:12

技能介绍

用途:该技能用于指导 MSBuild 二进制日志(.binlog)基础设施的变更,在修改 BinaryLogger、BinaryLogReplayEventSource 或新增 BuildEventArgs 类型时参考。

核心原则:binlog 是 MSBuild 的主要诊断格式与构建分析的事实来源,需完整捕获所有有意义的构建事件;格式变更必须向后兼容,旧版 Structured Log Viewer 等工具至少能优雅降级读取新版 binlog;同时需向前兼容,新版查看器应能处理旧版 binlog 而不崩溃。

架构:构建引擎产生 BuildEventArgs,经 BinaryLogger 序列化为 .binlog,ProjectImportsCollector 嵌入项目与 targets 文件;回放时由 BinaryLogReplayEventSource 反序列化后交给任意 ILogger。关键源文件包括 src/Build/Logging/BinaryLogger/BinaryLogger.cs、src/Framework/BuildEventArgs.cs、src/Build/Logging/BinaryLogger/ProjectImportsCollector.cs。

新增事件类型:定义继承自相应基类的事件类,实现 WriteToStream 与 CreateFromStream,格式变化时递增二进制日志版本,在记录类型枚举中新增常量,并在回放源中处理未知类型以便旧读取器优雅跳过。序列化兼容规则:不移除已有字段,新字段追加到流末尾,读取时用版本检查,可空字段先序列化存在标志。

重要性级别:High 用于关键用户信息,Normal 用于标准构建进度,Low 用于详细诊断,Diagnostic 用于内部调试;不要因“太啰嗦”而跳过日志,应改用 Low。

ProjectImportsCollector:将导入的 .props、.targets 和项目文件嵌入 binlog 以支持预处理视图;MSBUILDLOGIMPORTS=1 或 /bl 开关启用;内容在求值时捕获;大型导入链会增大 binlog 体积;敏感内容会被嵌入,需向用户说明。

测试:进行往返测试(写入、回放、验证事件重建)、版本兼容测试、内容验证与体积回归监控,可使用 BinaryLogReplayEventSource 以编程方式验证 binlog 内容。

限制:资料未提供具体版本号、命令细节或收费信息。