Com treballar amb l'empaquetament OOXML a .NET

Un fitxer XLSX és un arxiu ZIP basat en l’Open Packaging Convention (OPC). Aspose.Cells FOSS for .NET exposa l’estructura del paquet subjacents a través de PackageModel, PackagePartDescriptor, IPackageReader i IPackageWriter. Aquests són APIs a nivell d’infraestructura principalment útils per a diagnòstics i implementacions d’emmagatzematge personalitzades. Instal·la-ho amb dotnet add package Aspose.Cells_FOSS.

Guia pas a pas

Pas 1: Instal·la el paquet

dotnet add package Aspose.Cells_FOSS

Pas 2: Importa l’espai de noms

using Aspose.Cells_FOSS;

Pas 3: Gestiona PackageStructureException

PackageStructureException es llança quan el paquet XLSX té una estructura OPC invàlida (p. ex. falten relacions requerides). Captura’l juntament amb WorkbookLoadException quan es carreguen fitxers des de fonts no fiables.

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

Pas 4: Entendre IPackageReader i IPackageWriter

IPackageReader defineix un Read() mètode per llegir un paquet OPC; IPackageWriter defineix un Write() mètode per escriure’n un. La biblioteca ofereix implementacions per defecte basades en ZIP. Es poden proporcionar implementacions personalitzades quan es carrega o es desa en un emmagatzematge que no sigui del sistema de fitxers (p. ex. blobs al núvol o buffers en memòria).

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

Pas 5: Comprovar les parts no compatibles

En carregar un fitxer XLSX, PackageModel.UnsupportedParts enumera les parts que la biblioteca no processa. Aquestes es conserven però no s’interpreten. Accediu a PackageLoadContext durant un flux de càrrega personalitzat per inspeccionar el 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.");

Problemes comuns i solucions

PackageStructureException es llança fins i tot amb TryRepairPackage = true.
Algunes falles estructurals d’OPC són més enllà de la reparació automàtica (p. ex. mapa de tipus de contingut completament absent). Verifiqueu que el fitxer sigui un ZIP vàlid amb unzip -t file.xlsx. Si és vàlid, pot estar xifrat — els fitxers protegits amb contrasenya no són compatibles.

Workbook carrega però falta part del contingut.
Comproveu LoadDiagnostics.Issues per a entrades DataLossRisk = true. Això indica parts que van ser eliminades durant la reparació.

El IPackageReader personalitzat no s’està cridant. Assegureu-vos que s’utilitza la sobrecàrrega del constructor que accepta el lector personalitzat. No totes les sobrecàrregues del constructor Workbook accepten un lector de paquet personalitzat.

Preguntes freqüents

Quan hauria d’implementar IPackageReader o IPackageWriter?

Només quan el teu backend d’emmagatzematge no és el sistema de fitxers local — per exemple, carregant directament des d’un flux d’emmagatzematge al núvol sense crear un fitxer temporal.

Es conserven les parts no compatibles en PackageModel en desar?

Les parts no estàndard a UnsupportedParts no es garanteix que es tornin a escriure. Per a la fidelitat d’anada i tornada de les parts no estàndard, postprocessa el XLSX desat a nivell ZIP.

Quina és la diferència entre PackageStructureException i WorkbookLoadException?

PackageStructureException és un error a nivell OPC/ZIP (tipus de contingut absent, relació trencada). WorkbookLoadException és un error a nivell superior en analitzar el contingut XML de XLSX.