Come lavorare con il Packaging OOXML in .NET

Un file XLSX è un archivio ZIP Open Packaging Convention (OPC). Aspose.Cells FOSS per .NET espone la struttura del pacchetto sottostante tramite PackageModel, PackagePartDescriptor, IPackageReader e IPackageWriter. Queste sono API a livello di infrastruttura principalmente utili per diagnosi e implementazioni di archiviazione personalizzate. Installa con dotnet add package Aspose.Cells_FOSS.

Guida passo passo

Passo 1: Installa il pacchetto

dotnet add package Aspose.Cells.FOSS

Passo 2: Importa lo spazio dei nomi

using Aspose.Cells_FOSS;

Passo 3: Gestisci PackageStructureException

PackageStructureException viene generato quando il pacchetto XLSX ha una struttura OPC non valida (ad es. relazioni richieste mancanti). Catturalo insieme a WorkbookLoadException quando carichi file da fonti non attendibili.

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

Passo 4: Comprendere IPackageReader e IPackageWriter

IPackageReader definisce un metodo Read() per leggere un pacchetto OPC; IPackageWriter definisce un metodo Write() per scriverne uno. La libreria fornisce implementazioni predefinite basate su ZIP. Implementazioni personalizzate possono essere fornite quando si carica da o si salva su un archivio non basato su file system (ad es. blob cloud o buffer in memoria).

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

Passo 5: Verificare le parti non supportate

Durante il caricamento di un file XLSX, PackageModel.UnsupportedParts elenca le parti che la libreria non elabora. Queste vengono conservate ma non interpretate. Accedi a PackageLoadContext durante un flusso di caricamento personalizzato per ispezionare il modello.

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

Problemi comuni e soluzioni

PackageStructureException viene lanciato anche con TryRepairPackage = true. Alcuni errori strutturali OPC sono oltre la riparazione automatica (ad esempio mappa content-type completamente mancante). Verifica che il file sia un ZIP valido con unzip -t file.xlsx. Se è valido, potrebbe essere crittografato — i file protetti da password non sono supportati.

Workbook si carica ma alcuni contenuti sono mancanti. Check LoadDiagnostics.Issues for DataLossRisk = true voci. Queste indicano parti che sono state rimosse durante la riparazione.

Custom IPackageReader non viene chiamato. Assicurati che venga utilizzato il sovraccarico del costruttore che accetta il lettore personalizzato. Non tutti Workbook i sovraccarichi del costruttore accettano un lettore di pacchetto personalizzato.

Domande frequenti

Quando dovrei implementare IPackageReader o IPackageWriter?

Solo quando il tuo backend di archiviazione non è il file system locale — ad esempio, caricando direttamente da un flusso di archiviazione cloud senza creare un file temporaneo.

Le parti non supportate in PackageModel vengono preservate al salvataggio?

Le parti non standard in UnsupportedParts non sono garantite essere riscritte. Per mantenere la fedeltà di andata e ritorno delle parti non standard, elabora in post-produzione il file XLSX salvato a livello ZIP.

Qual è la differenza tra PackageStructureException e WorkbookLoadException?

PackageStructureException è un errore di livello OPC/ZIP (tipo di contenuto mancante, relazione interrotta). WorkbookLoadException è un errore di livello superiore nell’analisi del contenuto XLSX XML.