Working with OOXML Packaging

Working with OOXML Packaging

An XLSX file is an Open Packaging Convention (OPC) ZIP archive. Aspose.Cells FOSS for .NET exposes the underlying package layer through IPackageReader, IPackageWriter, and the PackageModel object graph. These are low-level APIs intended for diagnostics and tooling — most applications use only the high-level Workbook class.

Package Model

PackageModel represents the logical contents of an XLSX archive. It exposes three collections: Parts (all content parts), Relationships (OPC relationship entries), and UnsupportedParts (parts present in the file that the library does not process). Each part is described by a PackagePartDescriptor with PartUri, ContentType, and Category.

using Aspose.Cells_FOSS;

// PackageModel is accessed via PackageLoadContext during custom load flows
// The following illustrates the object structure
// var context = new PackageLoadContext(workbook, packageModel);
// var model = context.Package;
// foreach (var part in model.Parts)
// {
//     Console.WriteLine($"URI={part.PartUri}, Type={part.ContentType}");
// }
// Console.WriteLine("Unsupported parts: " + model.UnsupportedParts.Count);

Note: PackageModel is populated internally when loading an XLSX file. Direct instantiation is not part of the standard high-level workflow.

IPackageReader and IPackageWriter

IPackageReader defines a single Read() method for reading an OPC package. IPackageWriter defines a single Write() method for writing one. These interfaces are implemented by the library’s internal ZIP-based reader/writer and can be supplied by custom implementations for in-memory or cloud-storage scenarios.

// Signature reference — not a complete runnable example
// public interface IPackageReader { void Read(...); }
// public interface IPackageWriter { void Write(...); }

PackageStructureException

PackageStructureException is thrown when the XLSX package structure is fundamentally invalid — for example, when required OPC relationships are missing. It extends the general exception hierarchy and carries a message describing which structural invariant was violated.

using Aspose.Cells_FOSS;

var opts = new LoadOptions { TryRepairPackage = true };

try
{
    var wb = new Workbook("bad.xlsx", opts);
}
catch (PackageStructureException ex)
{
    Console.WriteLine("OPC structure error: " + ex.Message);
}
catch (WorkbookLoadException ex)
{
    Console.WriteLine("Load error: " + ex.Message);
}

Tips and Best Practices

• Use PackageModel.UnsupportedParts to discover non-standard parts that may be silently dropped on round-trip.
• Catch PackageStructureException in addition to WorkbookLoadException when loading files from untrusted sources.
• The IPackageReader/IPackageWriter interfaces are extension points; implement them only when you need custom storage (e.g. loading from a cloud blob without a local file).
• For most diagnostics, LoadDiagnostics (accessible via Workbook.LoadDiagnostics) is sufficient — dropping to the package layer is rarely necessary.

Common Issues

FAQ

Do I need to use IPackageReader/IPackageWriter for normal spreadsheet work?

No. These interfaces are extension points for advanced scenarios. All standard read/write operations go through Workbook directly.

Are unsupported parts preserved on save?

Parts listed in PackageModel.UnsupportedParts are not processed and may not be written back. If round-trip fidelity for non-standard parts is required, use a zip-level post-processing step.

What is the difference between PackageStructureException and WorkbookLoadException?

PackageStructureException indicates an OPC/ZIP-level failure (missing content type, broken relationship). WorkbookLoadException indicates a higher-level parse or semantic failure in the XLSX content.

API Reference Summary