How to Work with OOXML Packaging in .NET

An XLSX file is an Open Packaging Convention (OPC) ZIP archive. Aspose.Cells FOSS for .NET exposes the underlying package structure through PackageModel, PackagePartDescriptor, IPackageReader, and IPackageWriter. These are infrastructure-level APIs primarily useful for diagnostics and custom storage implementations. Install with dotnet add package Aspose.Cells_FOSS.

Step-by-Step Guide

Step 1: Install the Package

dotnet add package Aspose.Cells_FOSS

Step 2: Import the Namespace

using Aspose.Cells_FOSS;

Step 3: Handle PackageStructureException

PackageStructureException is thrown when the XLSX package has an invalid OPC structure (e.g. missing required relationships). Catch it alongside WorkbookLoadException when loading files from untrusted sources.

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);
}

Step 4: Understand IPackageReader and IPackageWriter

IPackageReader defines a Read() method for reading an OPC package; IPackageWriter defines a Write() method for writing one. The library provides default ZIP-backed implementations. Custom implementations can be supplied when loading from or saving to non-filesystem storage (e.g. cloud blobs or in-memory buffers).

// 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)");

Step 5: Check for Unsupported Parts

When loading an XLSX file, PackageModel.UnsupportedParts lists parts that the library does not process. These are preserved but not interpreted. Access PackageLoadContext during a custom load flow to inspect the model.

// 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.");

Common Issues and Fixes

PackageStructureException is thrown even with TryRepairPackage = true. Some OPC structural failures are beyond automatic repair (e.g. completely missing content-type map). Verify the file is a valid ZIP with unzip -t file.xlsx. If valid, it may be encrypted — password-protected files are not supported.

Workbook loads but some content is missing. Check LoadDiagnostics.Issues for DataLossRisk = true entries. These indicate parts that were dropped during repair.

Custom IPackageReader is not being called. Ensure the constructor overload that accepts the custom reader is used. Not all Workbook constructor overloads accept a custom package reader.

Frequently Asked Questions

When should I implement IPackageReader or IPackageWriter?

Only when your storage backend is not the local file system — for example, loading directly from a cloud storage stream without creating a temporary file.

Are unsupported parts in PackageModel preserved on save?

Non-standard parts in UnsupportedParts are not guaranteed to be written back. For round-trip fidelity of non-standard parts, post-process the saved XLSX at the ZIP level.

What is the difference between PackageStructureException and WorkbookLoadException?

PackageStructureException is an OPC/ZIP level failure (missing content type, broken relationship). WorkbookLoadException is a higher-level failure in parsing the XLSX XML content.