Cara Bekerja dengan Pengemasan OOXML di .NET

Sebuah file XLSX adalah arsip ZIP dengan Open Packaging Convention (OPC). Aspose.Cells FOSS for .NET mengekspos struktur paket yang mendasarinya melalui PackageModel, PackagePartDescriptor, IPackageReader, dan IPackageWriter. Ini adalah API tingkat infrastruktur yang terutama berguna untuk diagnostik dan implementasi penyimpanan khusus. Instal dengan dotnet add package Aspose.Cells_FOSS.

Panduan Langkah-demi-Langkah

Langkah 1: Instal Paket

dotnet add package Aspose.Cells_FOSS

Langkah 2: Impor Namespace

using Aspose.Cells_FOSS;

Langkah 3: Tangani PackageStructureException

PackageStructureException dilempar ketika paket XLSX memiliki struktur OPC yang tidak valid (mis. hubungan yang diperlukan tidak ada). Tangkap bersama WorkbookLoadException saat memuat file dari sumber yang tidak tepercaya.

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

Langkah 4: Memahami IPackageReader dan IPackageWriter

IPackageReader mendefinisikan metode Read() untuk membaca paket OPC; IPackageWriter mendefinisikan metode Write() untuk menulisnya. Perpustakaan menyediakan implementasi default yang didukung ZIP. Implementasi khusus dapat disediakan saat memuat dari atau menyimpan ke penyimpanan non‑sistem file (misalnya blob cloud atau buffer dalam memori).

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

Langkah 5: Periksa Bagian yang Tidak Didukung

Ketika memuat file XLSX, PackageModel.UnsupportedParts mencantumkan bagian‑bagian yang tidak diproses oleh perpustakaan. Bagian‑bagian ini dipertahankan tetapi tidak diinterpretasikan. Akses PackageLoadContext selama alur pemuatan khusus untuk memeriksa 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.");

Masalah Umum dan Solusi

PackageStructureException dilempar bahkan dengan TryRepairPackage = true.
Beberapa kegagalan struktural OPC berada di luar perbaikan otomatis (mis. peta content-type yang benar-benar hilang). Verifikasi bahwa file adalah ZIP yang valid dengan unzip -t file.xlsx. Jika valid, mungkin file tersebut terenkripsi — file yang dilindungi kata sandi tidak didukung.

Workbook memuat tetapi beberapa konten hilang. Periksa LoadDiagnostics.Issues untuk entri DataLossRisk = true. Ini menunjukkan bagian yang terlepas selama perbaikan.

Custom IPackageReader tidak dipanggil. Pastikan overload konstruktor yang menerima pembaca khusus digunakan. Tidak semua overload konstruktor Workbook menerima pembaca paket khusus.

Pertanyaan yang Sering Diajukan

Kapan saya harus mengimplementasikan IPackageReader atau IPackageWriter?

Hanya ketika backend penyimpanan Anda bukan sistem file lokal — misalnya, memuat langsung dari aliran penyimpanan cloud tanpa membuat file sementara.

Apakah bagian yang tidak didukung dalam PackageModel dipertahankan saat disimpan?

Bagian non-standar dalam UnsupportedParts tidak dijamin akan ditulis kembali. Untuk menjaga kesetiaan round‑trip bagian non‑standar, lakukan pemrosesan lanjutan pada file XLSX yang disimpan di tingkat ZIP.

Apa perbedaan antara PackageStructureException dan WorkbookLoadException?

PackageStructureException adalah kegagalan tingkat OPC/ZIP (tipe konten hilang, hubungan rusak). WorkbookLoadException adalah kegagalan tingkat lebih tinggi dalam parsing konten XML XLSX.