Hoe te werken met OOXML Packaging in .NET

Een XLSX-bestand is een Open Packaging Convention (OPC) ZIP archief. Aspose.Cells FOSS voor .NET maakt de onderliggende pakketsstructuur bloot via PackageModel, PackagePartDescriptor, IPackageReader en IPackageWriter. Dit zijn infrastructuur-niveau API’s die voornamelijk nuttig zijn voor diagnostiek en aangepaste opslagimplementaties. Installeer met dotnet add package Aspose.Cells_FOSS.

Stapsgewijze handleiding

Stap 1: Installeer het pakket

dotnet add package Aspose.Cells.FOSS

Stap 2: Importeer de namespace

using Aspose.Cells_FOSS;

Stap 3: Behandel PackageStructureException

PackageStructureException wordt gegooid wanneer het XLSX-pakket een ongeldige OPC-structuur heeft (bijv. ontbrekende vereiste relaties). Vang het op samen met WorkbookLoadException bij het laden van bestanden uit onbetrouwbare bronnen.

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

Stap 4: Begrijp IPackageReader en IPackageWriter

IPackageReader definieert een Read() methode voor het lezen van een OPC-pakket; IPackageWriter definieert een Write() methode voor het schrijven ervan. De bibliotheek levert standaard ZIP-ondersteunde implementaties. Aangepaste implementaties kunnen worden geleverd bij het laden vanuit of opslaan naar niet-bestandssysteemopslag (bijv. cloud-blobs of 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)");

Stap 5: Controleer op niet-ondersteunde onderdelen

Bij het laden van een XLSX-bestand geeft PackageModel.UnsupportedParts onderdelen weer die de bibliotheek niet verwerkt. Deze worden bewaard maar niet geïnterpreteerd. Toegang tot PackageLoadContext tijdens een aangepast laadproces om het model te inspecteren.

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

Veelvoorkomende problemen en oplossingen

PackageStructureException wordt gegooid zelfs met TryRepairPackage = true. Sommige OPC-structuurfouten liggen buiten automatische reparatie (bijv. volledig ontbrekende content-type map). Controleer of het bestand een geldige ZIP is met unzip -t file.xlsx. Als het geldig is, kan het versleuteld zijn — wachtwoordbeveiligde bestanden worden niet ondersteund.

Workbook laadt, maar sommige inhoud ontbreekt. Check LoadDiagnostics.Issues for DataLossRisk = true items. Deze geven onderdelen aan die tijdens reparatie zijn weggelaten.

Custom IPackageReader wordt niet aangeroepen. Zorg ervoor dat de constructor-overload die de aangepaste lezer accepteert wordt gebruikt. Niet alle Workbook constructor-overloads accepteren een aangepaste pakketlezer.

Veelgestelde vragen

Wanneer moet ik IPackageReader of IPackageWriter implementeren?

Alleen wanneer uw opslagbackend niet het lokale bestandssysteem is — bijvoorbeeld, rechtstreeks laden vanuit een cloud-opslagstroom zonder een tijdelijk bestand te maken.

Worden niet-ondersteunde onderdelen in PackageModel bewaard bij opslaan?

Niet-standaardonderdelen in UnsupportedParts worden niet gegarandeerd teruggeschreven. Voor round-trip-fideliteit van niet-standaardonderdelen, verwerk het opgeslagen XLSX achteraf op ZIP-niveau.

Wat is het verschil tussen PackageStructureException en WorkbookLoadException?

PackageStructureException is een OPC/ZIP niveau fout (ontbrekend contenttype, verbroken relatie). WorkbookLoadException is een fout op hoger niveau bij het parseren van de XLSX XML inhoud.