How to Work with XLSX Packaging in C++

Aspose.Cells FOSS for C++ reads and writes Excel files in the .xlsx Open XML format. Internally, the XlsxWorkbookSerializer class orchestrates loading and saving of all workbook parts. This guide explains how to use the load/save API and what the packaging layer manages automatically.

Step-by-Step Guide

Step 1: Set Up the Build

cmake_minimum_required(VERSION 3.15)
project(XlsxPackaging CXX)
set(CMAKE_CXX_STANDARD 17)

add_subdirectory(path/to/Aspose.Cells-FOSS-for-Cpp)
add_executable(XlsxPackaging main.cpp)
target_link_libraries(XlsxPackaging PRIVATE Aspose.Cells.Foss.Cpp)

Step 2: Include Headers

#include "aspose/cells_foss/Workbook.h"
#include "aspose/cells_foss/Worksheet.h"
#include "aspose/cells_foss/Cell.h"

using namespace Aspose::Cells_FOSS;

Step 3: Load an Existing XLSX File

The Workbook(filePath) constructor calls XlsxWorkbookSerializer::Load internally to unpack all Open XML parts:

int main() {
    Workbook workbook("input.xlsx");
    Worksheet& sheet = workbook.GetWorksheets()[0];
    std::string title = sheet.GetCells()["A1"].GetStringValue();
    return 0;
}

Step 4: Modify the Workbook

Make any cell, style, or structural changes using the standard API:

sheet.GetCells()["A1"].PutValue("Updated Title");
sheet.GetCells()["B2"].PutValue(99.0);
sheet.GetCells()["C3"].SetFormula("=B2*2");

Step 5: Save the Workbook

Call Workbook::Save(fileName) to pack all Open XML parts back into an XLSX archive:

workbook.Save("output.xlsx");
workbook.Dispose();

The format is inferred from the .xlsx extension. The XlsxWorkbookSerializer::Save method handles writing the xl/workbook.xml, xl/worksheets/sheet*.xml, xl/styles.xml, and xl/sharedStrings.xml parts automatically.

Step 6: Understand What the Packaging Layer Manages

You do not need to interact with packaging internals directly. The serializer handles:

Part	Managed by
Workbook structure	`XlsxWorkbookProperties`
Worksheet data	`WorksheetXmlMapper`
Styles and fonts	`XlsxWorkbookStyles`
Shared strings	`SharedStringTableXmlMapper`
Document properties	`XlsxDocumentProperties`
Defined names	`XlsxWorkbookDefinedNames`

Common Issues and Fixes

File saves but does not open in Excel Ensure the output file path uses the .xlsx extension. Saving with a different extension may produce an unrecognized file.

Styles lost after round-trip Apply Cell::SetStyle(style) before calling Workbook::Save. Styles modified after save are not written.

File loads as empty Verify the file is not password-protected and is a valid XLSX (not .xls or .xlsm). The library supports .xlsx only.

Defined names missing after save Use Workbook::EnsureUniqueDefinedName() before saving to resolve any scope conflicts.

Memory not released Call workbook.Dispose() after saving to free all internal XLSX packaging resources.

Frequently Asked Questions

Can I save to formats other than XLSX?

The current v0.1 release supports saving to XLSX only. Loading CSV is supported but saving to CSV is not available.

Does the library preserve existing parts I haven’t modified?

Yes. The serializer round-trips all parts it loads. Unmodified worksheet data, styles, and defined names are preserved on save.

Can I inspect the raw XML of a workbook part?

The XmlDocument::SaveToUtf8() method serializes an XML document to a string. However, direct access to XLSX archive parts is not exposed in the public API. Use XmlDocument for custom XML processing.

Is there a streaming API for large files?

No. The current release loads the entire workbook into memory. For very large files, consider chunking your processing into smaller workbooks.

What happens if I save over the same file I loaded?

This is supported. The library writes to a new internal buffer before overwriting the file on disk, so in-place save does not corrupt the source.