Как да работим с OOXML пакетиране в .NET

XLSX файл е ZIP архив, съответстващ на Open Packaging Convention (OPC). Aspose.Cells FOSS for .NET разкрива основната структура на пакета чрез PackageModel, PackagePartDescriptor, IPackageReader и IPackageWriter. Това са API‑та на инфраструктурно ниво, предимно полезни за диагностика и персонализирани реализации на съхранение. Инсталирайте с dotnet add package Aspose.Cells_FOSS.

Ръководство стъпка по стъпка

Стъпка 1: Инсталирайте пакета

dotnet add package Aspose.Cells_FOSS

Стъпка 2: Импортиране на пространството от имена

using Aspose.Cells_FOSS;

Стъпка 3: Обработете PackageStructureException

PackageStructureException се хвърля, когато XLSX пакетът има невалидна OPC структура (например липсващи задължителни връзки). Улавяйте я заедно с WorkbookLoadException при зареждане на файлове от недоверени източници.

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

Стъпка 4: Разбиране на IPackageReader и IPackageWriter

IPackageReader определя Read() метод за четене на OPC пакет; IPackageWriter определя Write() метод за записване на такъв. Библиотеката предоставя стандартни реализации, базирани на ZIP. Персонализирани реализации могат да се предоставят при зареждане от или записване в съхранение, различно от файловата система (например облачни блобове или буфери в паметта).

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

Стъпка 5: Проверка за неподдържани части

При зареждане на XLSX файл, PackageModel.UnsupportedParts изброява части, които библиотеката не обработва. Те се запазват, но не се интерпретират. Достъпете PackageLoadContext по време на персонализиран процес на зареждане, за да инспектирате модела.

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

Общи проблеми и решения

PackageStructureException се хвърля дори с TryRepairPackage = true. Някои структурни грешки в OPC са извън автоматичната поправка (например напълно липсваща карта за типове съдържание). Проверете дали файлът е валиден ZIP с unzip -t file.xlsx. Ако е валиден, може да е криптиран — файлове, защитени с парола, не се поддържат.

Workbook зарежда, но липсва част от съдържанието. Проверете LoadDiagnostics.Issues за DataLossRisk = true записи. Те указват части, които са били премахнати по време на ремонта.

Персонализираният IPackageReader не се извиква.
Уверете се, че се използва претоварването на конструктора, което приема персонализирания четец. Не всички претоварвания на конструктора Workbook приемат персонализиран четец на пакет.

Често задавани въпроси

Кога трябва да имплементирам IPackageReader или IPackageWriter?

Само когато вашият бекенд за съхранение не е локалната файлова система — например, зареждане директно от поток в облачно съхранение без създаване на временен файл.

Запазват ли неподдържаните части в PackageModel при запазване?

Нестандартните части в UnsupportedParts не са гарантирани да бъдат записани обратно. За запазване на точността при обратното преобразуване на нестандартните части, обработете запазения XLSX на ниво ZIP.

Каква е разликата между PackageStructureException и WorkbookLoadException?

PackageStructureException е грешка на ниво OPC/ZIP (липсва тип на съдържанието, нарушена връзка). WorkbookLoadException е грешка на по-високо ниво при парсиране на XML съдържанието на XLSX.