PowGrade.FileConverters.XlsToXlsx.Cli 0.1.0

PowGrade.FileConverters.XlsToXlsx

PowGrade.FileConverters.XlsToXlsx 是一个 .NET 的 XLS(BIFF8) 到 XLSX(OpenXML) 转换器，包含：

• 类库：PowGrade.FileConverters.XlsToXlsx
• 命令行：PowGrade.FileConverters.XlsToXlsx.Cli（命令名 xls2xlsx）

项目目标是尽可能保留旧版 Excel 工作簿的可读内容与常见结构，同时保持纯托管、无 Office 依赖、可在服务端运行。

当前功能完成度

以下状态基于当前代码实现与测试覆盖情况整理。

已完成（可稳定使用）

• OLE 复合文档读取（Workbook 流、FAT/DIFAT/MiniFAT）
• BIFF8 基础单元格解析：数字、字符串、布尔、错误值、公式结果
• 样式主链路：字体、填充、边框、对齐、数字格式、行列样式索引映射
• 工作表基础布局：行高、列宽、冻结窗格、合并单元格去重防冲突
• 超链接（外链/本地/邮件）
• 页面设置：页边距、页眉页脚、方向、纸张、缩放相关字段
• 文档属性：core/app 属性（作者、标题、公司、时间等）
• 工作簿/工作表保护标志与 16 位密码哈希透传
• 严格模式（--strict）与公式未知 PTG 诊断（--report / ConversionReport）
• CLI 单文件与目录批量转换（目录模式为当前目录下 *.xls）

部分完成（可用但有边界）

• 公式反编译：覆盖大量函数与 PTG，但仍存在未知 PTG 的兼容场景
• 图表：支持基础图类型和系列数据写出；已支持轴最小/最大值、对数刻度、反向轴、主/次单位，线图/散点图 marker 细节写出，以及按系列图类型覆盖、次坐标轴与类别轴/XY 轴族并存映射；高级图表特性仍不完整
• 图片/绘图：支持常见图片提取与锚点；复杂 Escher 容器仅部分解析
• 条件格式：支持 CFRULE/CF12 主体结构；已增强 CF12 的阈值解析、图标集类型映射、“公式前缀 + 载荷”场景解析、DataBar 长度提取，以及 iconSet percent/dataBar 长度写出一致性处理，复杂样式仍含降级逻辑
• 数据验证：支持常见规则与公式；复杂多区域/细粒度标志处理有限
• 数据透视表：可生成 pivotCache/pivotTable 结构，支持 row/column/page/data 字段索引映射与基础布局，复杂行为依赖 Excel 刷新
• 外部链接：支持 EXTERNBOOK/EXTERNSHEET 基础映射，并写出外部工作表名与外部定义名；复杂路径场景仍有限
• 注释：已写出 comments part + legacy VML，支持基础文本与作者；富文本细节与高级注释属性仍有限

明确缺失或不完整项

• 图表高级能力缺失（如复杂 3D 参数、跨类型组合图的更完整布局语义、更多样式细节）
• 条件格式 CF12 二进制细节未完全逐字段映射，部分场景走默认/回退值
• 目录过滤策略支持 include/exclude 通配符与基础正则；支持输出目录、输出扩展名、JSON 汇总报告、dry-run 与输出冲突策略（尚未提供更复杂条件组合规则）

快速开始

1) 本地运行 CLI

dotnet run --project src\PowGrade.FileConverters.XlsToXlsx.Cli -- -i input.xls -o output.xlsx

CLI 参数：

• -i, --input <path>：输入文件或目录
• -o, --output <file>：输出文件（单文件转换时使用，支持 .xlsx / .xlsm）
• --strict：严格模式，未知公式 PTG 视为错误，并启用输出包校验
• --report：输出转换诊断信息
• --password <value>：加密 XLS 密码（默认会尝试 VelvetSweatshop）
• -r, --recursive：目录输入时递归扫描子目录
• --pattern <glob>：目录输入时的文件匹配模式（默认 *.xls）
• --exclude-pattern <glob>：目录输入时排除文件名模式
• --include-regex <expr>：目录输入时按文件名正则包含
• --exclude-regex <expr>：目录输入时按文件名正则排除
• --output-dir <path>：指定输出目录（目录模式保留相对结构）
• --output-ext <ext>：输出扩展名（xlsx 或 xlsm，默认 xlsx）
• --report-file <path>：输出 JSON 汇总报告（含成功/失败、输入输出路径、未知 PTG）
• --dry-run：仅输出计划转换映射，不写文件
• --flatten-output：目录模式下将输出扁平化写入 --output-dir
• --on-collision <mode>：输出冲突策略（fail 或 overwrite）
• --dump-colors <file>：仅解析调色板/字体信息，不执行转换
• --version：显示版本
• --help, -h：显示帮助

示例：

xls2xlsx -i C:\legacy\book.xls -o C:\out\book.xlsx --strict --report

xls2xlsx -i C:\legacy\book.xls -o C:\out\book.xlsm

xls2xlsx -i C:\legacy-folder

xls2xlsx -i C:\legacy-folder --recursive --pattern *invoice*.xls --strict

xls2xlsx -i C:\legacy-folder --recursive --pattern *.xls --exclude-pattern *backup*.xls

xls2xlsx -i C:\legacy-folder --recursive --pattern *.xls --include-regex ^sales-.*\.xls$ --exclude-regex backup

xls2xlsx -i C:\legacy-folder --recursive --output-dir C:\converted --output-ext xlsm

xls2xlsx -i C:\legacy-folder --recursive --report-file C:\converted\summary.json

xls2xlsx -i C:\legacy-folder --recursive --output-dir C:\flat --flatten-output --on-collision overwrite

2) 类库调用

using var input = File.OpenRead(@"C:\legacy.xls");
using var output = File.Create(@"C:\converted.xlsx");

XlsToXlsxConverter.Convert(
    input,
    output,
    strictMode: false);

带诊断报告：

ConversionReport report = XlsToXlsxConverter.ConvertWithReport(
    input,
    output,
    strictMode: false);

ConversionReport 除未知 PTG 外，还包含工作表/行/单元格、公式单元格、注释、超链接、数据验证、条件格式、图表、透视表、外部引用数量，以及是否宏项目与输出是否宏启用等统计信息；并提供按工作表维度的明细统计（WorksheetSummaries）与结构化兼容性告警（Warnings，含 WarningSeverity、来源索引与 ActionHint）。Warnings 结果在库内会去重并稳定排序，便于 CI 结果对比。

架构概览

• OleCompoundFile：读取 OLE 复合文档结构
• XlsParser：解析 BIFF8 记录并构建中间模型 Workbook
• FormulaDecompiler：将 PTG/RPN 公式反编译为 A1 风格文本
• WorkbookStylesBuilder：归并/映射样式索引
• XlsxGenerator：将中间模型序列化为 OpenXML 包
• XlsToXlsxConverter：对外统一 API（同步/异步/报告/批量）

开发与验证

dotnet build PowGrade.FileConverters.XlsToXlsx.sln -c Release
dotnet test PowGrade.FileConverters.XlsToXlsx.sln -c Release

发布前可运行：

.\tools\verify-release-metadata.ps1

改进计划（建议）

1. 宏文件输出策略：补齐 .xlsm 输出路径与内容类型一致性
2. 注释体系：补齐 comments 相关部件并增强富文本支持
3. 条件格式：完善 CF12 二进制解析与样式精确映射
4. 图表：扩展高级图表参数、轴与样式覆盖面
5. 批量转换：增加递归目录与过滤策略
6. 回归样本：增加多来源真实 XLS 样本集做兼容性回归

License

MIT