Open-XML-SDK 中 AddWorkbookPart() 方法的写入模式兼容性问题分析

问题现象

在使用 Open-XML-SDK 3.1.0 版本时，部分开发者遇到了一个与工作簿创建相关的问题。当调用 SpreadsheetDocument 的 AddWorkbookPart() 方法时，系统会抛出 System.IO.IOException 异常，错误信息为"无法检索只写容器的部件"(Cannot retrieve parts of writeonly container)。

技术背景

这个问题实际上涉及到了 Open-XML-SDK 底层对 System.IO.Packaging 的调用机制。在创建 Office 文档时，SDK 会使用 Package 类来处理文档的打包结构。Package 类提供了不同的访问模式控制：

• 只读模式(FileAccess.Read)
• 读写模式(FileAccess.ReadWrite)
• 只写模式(FileAccess.Write)

问题根源

在 Open-XML-SDK 3.1.0 版本中，当开发者使用只写模式(FileAccess.Write)创建 Package 对象时，系统会严格执行写入权限检查。底层代码中的 GetRelationshipsHelper 方法会调用 ThrowIfWriteOnly 方法进行验证，如果检测到当前处于只写模式，就会抛出上述异常。

值得注意的是，这个问题在 Open-XML-SDK 2.18.0 版本中并未出现，这表明新版本对权限控制更加严格，遵循了 System.IO.Packaging 的设计规范。

解决方案

正确的做法是使用读写模式(FileAccess.ReadWrite)来创建 Package 对象。以下是推荐的代码实现方式：

using (var spreadsheetDocument = SpreadsheetDocument.Create(filePath, SpreadsheetDocumentType.Workbook))
{
    // 添加工作簿部件
    WorkbookPart workbookPart = spreadsheetDocument.AddWorkbookPart();
    workbookPart.Workbook = new Workbook();
    
    // 添加工作表部件
    WorksheetPart worksheetPart = workbookPart.AddNewPart<WorksheetPart>();
    worksheetPart.Worksheet = new Worksheet(new SheetData());
    
    // 添加工作表到工作簿
    Sheets sheets = workbookPart.Workbook.AppendChild(new Sheets());
    Sheet sheet = new Sheet()
    {
        Id = spreadsheetDocument.WorkbookPart.GetIdOfPart(worksheetPart),
        SheetId = 1,
        Name = "工作表1"
    };
    sheets.Append(sheet);
}

最佳实践

1. 避免直接使用 Package.Open 方法，而是使用 SpreadsheetDocument.Create 方法
2. 如果需要控制文件访问模式，确保使用 FileAccess.ReadWrite 而非 FileAccess.Write
3. 在创建复杂文档结构时，按照"先创建部件，再设置内容"的顺序操作
4. 及时释放资源，使用 using 语句包裹文档操作代码块

版本兼容性说明

从 Open-XML-SDK 2.18.0 升级到 3.1.0 时，开发者需要注意权限控制方面的变化。新版本更严格地遵循了 System.IO.Packaging 的设计规范，这虽然可能导致部分原有代码需要调整，但提高了代码的健壮性和安全性。

对于必须使用只写模式的特殊场景，建议考虑以下替代方案：

1. 先使用读写模式创建文档结构
2. 完成内容填充后，再以只写模式进行最终保存
3. 或者使用内存流作为中间存储介质

这种设计变更体现了软件开发中"显式优于隐式"的原则，使权限控制更加明确，有助于开发者编写更可靠的代码。