Hoe te werken met OOXML Packaging in .NET

Een XLSX‑bestand is een Open Packaging Convention (OPC) ZIP‑archief. Aspose.Cells FOSS for .NET maakt de onderliggende pakketsstructuur toegankelijk 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: PackageStructureException afhandelen

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 biedt standaard ZIP‑ondersteunde implementaties. Aangepaste implementaties kunnen worden geleverd bij het laden van 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 aangepaste laadstroom 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-structurele fouten liggen buiten automatische reparatie (bijv. volledig ontbrekende content‑type‑map). Controleer of het bestand een geldige ZIP is met unzip -t file.xlsx. Indien geldig, kan het versleuteld zijn — wachtwoordbeveiligde bestanden worden niet ondersteund.

Workbook laadt maar sommige inhoud ontbreekt. Controleer LoadDiagnostics.Issues op DataLossRisk = true items. Deze geven aan welke delen tijdens de reparatie zijn weggelaten.

Aangepaste IPackageReader wordt niet aangeroepen. Zorg ervoor dat de constructoroverload die de aangepaste lezer accepteert, wordt gebruikt. Niet alle Workbook constructoroverloads accepteren een aangepaste pakketlezer.

Veelgestelde vragen

Wanneer moet ik IPackageReader of IPackageWriter implementeren?

Alleen wanneer uw opslagbackend niet het lokale bestandssysteem is — bijvoorbeeld door direct te laden vanuit een cloudopslagstream zonder een tijdelijk bestand te maken.

Worden niet‑ondersteunde onderdelen in PackageModel behouden bij opslaan?

Niet-standaardonderdelen in UnsupportedParts worden niet gegarandeerd teruggeschreven. Voor round-trip fidelity van niet-standaardonderdelen, verwerk het opgeslagen XLSX 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.