Cómo trabajar con el empaquetado OOXML en .NET

Un archivo XLSX es un archivo ZIP con la Convención de Empaquetado Abierto (OPC). Aspose.Cells FOSS for .NET expone la estructura subyacente del paquete a través de PackageModel, PackagePartDescriptor, IPackageReader y IPackageWriter. Estas son API de nivel de infraestructura principalmente útiles para diagnósticos e implementaciones de almacenamiento personalizadas. Instale con dotnet add package Aspose.Cells_FOSS.

Guía paso a paso

Paso 1: Instalar el paquete

dotnet add package Aspose.Cells_FOSS

Paso 2: Importar el espacio de nombres

using Aspose.Cells_FOSS;

Paso 3: Manejar PackageStructureException

PackageStructureException se lanza cuando el paquete XLSX tiene una estructura OPC no válida (p. ej., faltan relaciones requeridas). Atrápalo junto con WorkbookLoadException al cargar archivos de fuentes no confiables.

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

Paso 4: Comprender IPackageReader y IPackageWriter

IPackageReader define un método Read() para leer un paquete OPC; IPackageWriter define un método Write() para escribir uno. La biblioteca proporciona implementaciones predeterminadas respaldadas por ZIP. Se pueden suministrar implementaciones personalizadas al cargar o guardar en un almacenamiento que no sea del sistema de archivos (p. ej., blobs en la nube o búferes en 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)");

Paso 5: Verificar partes no compatibles

Al cargar un archivo XLSX, PackageModel.UnsupportedParts enumera las partes que la biblioteca no procesa. Estas se conservan pero no se interpretan. Acceda a PackageLoadContext durante un flujo de carga personalizado para inspeccionar el modelo.

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

Problemas comunes y soluciones

PackageStructureException se lanza incluso con TryRepairPackage = true.
Algunos fallos estructurales de OPC están más allá de la reparación automática (p. ej., mapa de content‑type completamente ausente). Verifique que el archivo sea un ZIP válido con unzip -t file.xlsx. Si es válido, puede estar cifrado — los archivos protegidos con contraseña no son compatibles.

Workbook se carga pero falta parte del contenido. Verifique LoadDiagnostics.Issues para entradas DataLossRisk = true. Estas indican partes que se eliminaron durante la reparación.

Custom IPackageReader no se está llamando.
Asegúrese de que se utilice la sobrecarga del constructor que acepta el lector personalizado. No todas las sobrecargas del constructor Workbook aceptan un lector de paquetes personalizado.

Preguntas Frecuentes

¿Cuándo debo implementar IPackageReader o IPackageWriter?

Solo cuando su backend de almacenamiento no sea el sistema de archivos local — por ejemplo, cargando directamente desde un flujo de almacenamiento en la nube sin crear un archivo temporal.

¿Se conservan las partes no compatibles en PackageModel al guardar?

Las partes no estándar en UnsupportedParts no están garantizadas para ser escritas de nuevo. Para la fidelidad de ida y vuelta de las partes no estándar, procese después el XLSX guardado a nivel ZIP.

¿Cuál es la diferencia entre PackageStructureException y WorkbookLoadException?

PackageStructureException es una falla a nivel OPC/ZIP (tipo de contenido faltante, relación rota). WorkbookLoadException es una falla de nivel superior al analizar el contenido XML de XLSX.