Aspose.Cells FOSS
.NET
如何在 .NET 中使用 OOXML 打包

如何在 .NET 中使用 OOXML 打包

XLSX 文件是一个开放包装约定（OPC）ZIP 存档。Aspose.Cells FOSS for .NET 通过 PackageModel、PackagePartDescriptor、IPackageReader 和 IPackageWriter 暴露底层包结构。这些是基础设施级别的 API，主要用于诊断和自定义存储实现。使用 dotnet add package Aspose.Cells_FOSS 安装。

分步指南

步骤 1：安装软件包 

dotnet add package Aspose.Cells_FOSS

步骤 2：导入命名空间 

using Aspose.Cells_FOSS;

步骤 3：处理 PackageStructureException

当 XLSX 包具有无效的 OPC 结构（例如缺少必需的关系）时会抛出 PackageStructureException。在从不受信任的来源加载文件时，请同时捕获 WorkbookLoadException。

using Aspose.Cells_FOSS;

var opts = new LoadOptions { TryRepairPackage = true };

try
{
    var wb = new Workbook("suspect.xlsx", opts);
    Console.WriteLine("Loaded: " + wb.Worksheets.Count + " sheet(s)");
}
catch (PackageStructureException ex)
{
    Console.WriteLine("OPC structure invalid: " + ex.Message);
}
catch (WorkbookLoadException ex)
{
    Console.WriteLine("Load error: " + ex.Message);
}

步骤 4：了解 IPackageReader 和 IPackageWriter

IPackageReader 定义了一个用于读取 OPC 包的 Read() 方法；IPackageWriter 定义了一个用于写入 OPC 包的 Write() 方法。该库提供默认的基于 ZIP 的实现。当从非文件系统存储（例如云 Blob 或内存缓冲区）加载或保存时，可以提供自定义实现。

// Signature reference
// public interface IPackageReader { void Read(/* ... */); }
// public interface IPackageWriter { void Write(/* ... */); }
//
// Standard usage: pass a Stream to the Workbook constructor
using Aspose.Cells_FOSS;
using System.IO;

byte[] fileBytes = File.ReadAllBytes("data.xlsx");
using var ms = new MemoryStream(fileBytes);
var wb = new Workbook(ms);
Console.WriteLine("Loaded from stream: " + wb.Worksheets.Count + " sheet(s)");

步骤 5：检查不受支持的部件

加载 XLSX 文件时，PackageModel.UnsupportedParts 列出了库不处理的部分。这些部分会被保留但不进行解释。在自定义加载流程中访问 PackageLoadContext 以检查模型。

// PackageModel is populated internally during Workbook construction.
// Use LoadDiagnostics to detect load-time structural warnings without
// dropping to the PackageModel level directly.
using Aspose.Cells_FOSS;

var opts = new LoadOptions { TryRepairPackage = true, TryRepairXml = true };
var wb = new Workbook("file.xlsx", opts);
var diag = wb.LoadDiagnostics;
if (diag.HasRepairs)
    Console.WriteLine("Package had " + diag.Issues.Count() + " repair entries.");

常见问题及解决方案

PackageStructureException 即使在 TryRepairPackage = true 时也会抛出。
某些 OPC 结构性故障超出自动修复范围（例如完全缺失 content-type 映射）。请使用 unzip -t file.xlsx 验证文件是否为有效的 ZIP。如果有效，可能已加密——不支持受密码保护的文件。

Workbook 加载但有些内容缺失。
检查 LoadDiagnostics.Issues 中的 DataLossRisk = true 条目。这些表示在修复过程中被丢弃的部分。

自定义 IPackageReader 未被调用。 确保使用接受自定义读取器的构造函数重载。并非所有 Workbook 构造函数重载都接受自定义包读取器。

常见问题

我应该何时实现 IPackageReader 或 IPackageWriter？

仅当您的存储后端不是本地文件系统时——例如，直接从云存储流加载而不创建临时文件。

在保存时，PackageModel 中不受支持的部件会被保留吗？

UnsupportedParts 中的非标准部分不保证会被写回。若要确保非标准部分的往返保真度，请在 ZIP 级别对保存的 XLSX 进行后处理。

PackageStructureException 和 WorkbookLoadException 之间有什么区别？

PackageStructureException 是一种 OPC/ZIP 级别的错误（缺少内容类型，关系损坏）。WorkbookLoadException 是在解析 XLSX XML 内容时的更高级别错误。

另请参阅

 中文