Як працювати з OOXML Packaging у .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 виходять за межі автоматичного виправлення (наприклад, повністю відсутня карта content-type). Перевірте, чи файл є дійсним ZIP за допомогою unzip -t file.xlsx. Якщо дійсний, він може бути зашифрований — файли, захищені паролем, не підтримуються.

Workbook завантажується, але деякий вміст відсутній. Перевірте LoadDiagnostics.Issues на наявність записів DataLossRisk = true. Це вказує на частини, які були втрачено під час ремонту.

Custom IPackageReader не викликається. Переконайтеся, що використано перевантаження конструктора, яке приймає користувацький читач. Не всі перевантаження конструктора Workbook приймають користувацький читач пакету.

Поширені запитання

Коли мені слід реалізовувати IPackageReader або IPackageWriter?

Тільки коли ваш бекенд сховища не є локальною файловою системою — наприклад, завантаження безпосередньо з потоку хмарного сховища без створення тимчасового файлу.

Чи зберігаються непідтримувані частини в PackageModel при збереженні?

Нестандартні частини у UnsupportedParts не гарантуються до запису назад. Для забезпечення точності зворотного проходу нестандартних частин пост‑обробіть збережений XLSX на рівні ZIP.

У чому різниця між PackageStructureException і WorkbookLoadException?

PackageStructureException є помилкою рівня OPC/ZIP (відсутній тип вмісту, пошкоджене відношення). WorkbookLoadException є помилкою вищого рівня під час розбору XML‑вмісту XLSX.