Cum să lucraţi cu ambalarea OOXML în .NET

Un fișier XLSX este o arhivă ZIP conform Open Packaging Convention (OPC). Aspose.Cells FOSS pentru .NET expune structura de pachet de bază prin PackageModel, PackagePartDescriptor, IPackageReader și IPackageWriter. Acestea sunt API-uri la nivel de infrastructură, în principal utile pentru diagnosticare și implementări de stocare personalizate. Instalați cu dotnet add package Aspose.Cells_FOSS.

Ghid pas cu pas

Pasul 1: Instalați pachetul

dotnet add package Aspose.Cells_FOSS

Pasul 2: Importă spațiul de nume

using Aspose.Cells_FOSS;

Pasul 3: Gestionați PackageStructureException

PackageStructureException este aruncat când pachetul XLSX are o structură OPC invalidă (de exemplu, relații necesare lipsă). Prinde‑l alături de WorkbookLoadException când încarci fișiere din surse neîncredere.

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

Pasul 4: Înțelegeți IPackageReader și IPackageWriter

IPackageReader definește o metodă Read() pentru citirea unui pachet OPC; IPackageWriter definește o metodă Write() pentru scrierea unuia. Biblioteca furnizează implementări implicite susținute de ZIP. Implementări personalizate pot fi furnizate la încărcarea din sau salvarea în stocare non-fișier (de exemplu, bloburi în cloud sau buffer-e în memorie).

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

Pasul 5: Verifică părțile neacceptate

Când încărcați un fișier XLSX, PackageModel.UnsupportedParts enumeră părțile pe care biblioteca nu le procesează. Acestea sunt păstrate, dar nu sunt interpretate. Accesați PackageLoadContext în timpul unui flux de încărcare personalizat pentru a inspecta modelul.

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

Probleme comune și soluții

PackageStructureException este aruncat chiar și cu TryRepairPackage = true.
Unele erori structurale OPC depășesc repararea automată (de exemplu, lipsă completă a hărții content‑type). Verificați că fișierul este un ZIP valid cu unzip -t file.xlsx. Dacă este valid, ar putea fi criptat — fișierele protejate prin parolă nu sunt suportate.

Workbook se încarcă, dar lipsește o parte din conținut.
Verificați LoadDiagnostics.Issues pentru intrările DataLossRisk = true. Acestea indică părți care au fost eliminate în timpul reparației.

Custom IPackageReader nu este apelat. Asigurați-vă că este utilizată suprasarcina constructorului care acceptă cititorul personalizat. Nu toate suprasarcinile constructorului Workbook acceptă un cititor de pachet personalizat.

Întrebări frecvente

Când ar trebui să implementez IPackageReader sau IPackageWriter?

Numai atunci când backend‑ul de stocare nu este sistemul de fișiere local — de exemplu, încărcarea directă dintr-un flux de stocare în cloud fără a crea un fișier temporar.

Sunt părțile nesuportate în PackageModel păstrate la salvare?

Părțile non-standard din UnsupportedParts nu sunt garantate să fie scrise înapoi. Pentru fidelitatea round‑trip a părților non-standard, procesați ulterior fișierul XLSX salvat la nivelul ZIP.

Care este diferența dintre PackageStructureException și WorkbookLoadException?

PackageStructureException este o eroare la nivelul OPC/ZIP (tip de conținut lipsă, relație ruptă). WorkbookLoadException este o eroare la nivel superior în analizarea conținutului XML al XLSX.