OfficeCLI Dump Batch Round-Trip Serialization: A Complete Technical Guide

OfficeCLI's dump --format batch command enables lossless round-trip serialization by capturing verbatim XML and binary payloads, allowing complete document reconstruction including OLE objects, ActiveX controls, and VML shapes that standard typed APIs cannot preserve.

The iOfficeAI/OfficeCLI repository implements a sophisticated dump batch round-trip serialization system that moves beyond human-readable exports to preserve the exact byte-level structure of Word, Excel, and PowerPoint documents. Unlike conventional flat dumps that lose embedded objects and complex relationships, the batch format stores the precise OpenXML DOM and binary payloads needed for bit-identical reconstruction. This capability allows developers to version control complex Office documents, migrate embedded content between environments, and automate document pipelines with guaranteed fidelity.

How Dump Batch Serialization Works

The round-trip process operates through three distinct stages that transform a live document into a portable batch representation and back again.

Stage 1: Dump Extraction

When you execute officecli dump --format batch, the resident server walks the OpenXML DOM and invokes specialized emit helpers to capture raw data. In src/officecli/Handlers/WordHandler.cs, methods like GetOleEmitData, GetActiveXEmitData, GetDiagramEmitData, and GetVmlShapeEmitData extract verbatim XML fragments alongside their associated binary parts. These helpers return structured records containing the exact bytes of referenced parts, which are then formatted as batch commands such as add /… and raw-set /….

Stage 2: Transport and Storage

The batch text streams to stdout or a file as plain text, making it compatible with pipes, version control systems, or network transmission. The ResidentServer.ProcessRequest method in src/officecli/ResidentServer.cs handles the "dump" command logic at line 336, ensuring that the serialized representation maintains human readability while preserving binary integrity through base64 or similar encoding schemes.

Stage 3: Batch Replay

The officecli batch --input - command parses the batch commands and reconstructs the document by invoking the same low-level helpers used during the dump phase. The WordBatchEmitter.cs file contains the logic that reads batch commands and executes add/raw-set operations on a fresh document. During replay, every mutation is deferred (DeferSave = true), meaning the document serializes only once at the end of the batch, reducing complexity from O(N²) to O(N) compared to per-command saves.

What Gets Serialized

The batch format captures document elements that traditional APIs often fail to preserve:

• OLE Objects: The OleEmitData structure stores embedded file bytes, icon representations, VML shape styles, and cropping information, ensuring that embedded Excel workbooks or other packages survive the round-trip intact.

• ActiveX Controls: ActiveXEmitData captures the run XML, all referenced parts, and external relationships required to recreate form controls and their functionality.

• SmartArt Diagrams: Stored using the same ActiveXEmitData structure as ActiveX controls, capturing the complete set of parts that comprise complex diagrams.

• VML Shapes and Pictures: The GetVmlShapeEmitData method preserves run XML and image parts for legacy Vector Markup Language graphics that predate the modern DrawingML standard.

• Structural Bookmarks: Methods like GetTableStructuralBookmarks, GetCellStructuralBookmarks, and GetBodyStructuralPermMarkers capture markers that exist outside the normal paragraph flow, including permission markers and structural boundaries.

• Custom Document Properties: The EnumerateCustomDocPropertyNames helper preserves user-defined properties in docProps/custom.xml beyond the standard OfficeCLI.* namespace.

• Raw Part Replacements: The raw-set command enables direct replacement of entire parts such as fontTable.xml through RawReplaceWholePart, bypassing limitations of the typed API.

Performance Characteristics and Guarantees

The batch round-trip system provides specific technical guarantees essential for production workflows:

Byte-Level Fidelity: OLE embeddings, ActiveX binaries, and VML positioning data survive transport unchanged, with all r:id relationship references preserved from the original document.

Relationship Integrity: The dump format maintains original relationship IDs, ensuring that cross-references between document parts remain valid after reconstruction.

Positioning Preservation: For floating OLE objects, the exact VML style attributes containing position and wrap hints are retained to maintain visual layout.

Idempotence: Running dump → batch → dump on the same file yields identical batch text, allowing for consistent checksums and verification workflows.

Practical Usage Examples

Shell-Based Round-Trip

Dump a Word document to a batch file for version control:

officecli dump --format batch my-document.docx > my-document.batch

Replay the batch to recreate a bit-identical copy:

cp my-document.docx empty.docx
officecli batch --input my-document.batch --file empty.docx

Pipe directly without intermediate files:

officecli dump --format batch my-document.docx | \
  officecli batch --input - --file rebuilt.docx

Programmatic API Usage

Access the batch serialization directly from C#:

using OfficeCli;
using OfficeCli.Handlers;

// Extract batch commands from existing document
var handler = DocumentHandlerFactory.Open("my-document.docx", editable: false);
var batchCommands = ((WordHandler)handler).EmitBatchCommands();
File.WriteAllLines("my-document.batch", batchCommands);

// Replay onto fresh document
var fresh = DocumentHandlerFactory.Open("recreated.docx", editable: true);
((WordHandler)fresh).ApplyBatchCommands(File.ReadAllLines("my-document.batch"));
fresh.Save();

The EmitBatchCommands and ApplyBatchCommands methods in WordHandler.cs provide thin wrappers around the internal emit helpers, exposing the same functionality available to the CLI.

Key Implementation Files

Understanding the source structure helps developers extend or debug the serialization process:

• src/officecli/ResidentServer.cs: Hosts the resident process, parses the dump command, and manages the batch output stream handling.

• src/officecli/Handlers/WordHandler.cs: Contains the core emit helpers (GetOleEmitData, GetActiveXEmitData, GetVmlShapeEmitData) and structural bookmark extraction methods.

• src/officecli/Handlers/Word/WordBatchEmitter.cs: Parses incoming batch commands and orchestrates the add/raw-set operations during replay, implementing the deferred save logic.

• src/officecli/Handlers/Word/WordBatchEmitter.Resources.cs: Handles the resource-specific serialization for OLE, ActiveX, diagrams, and VML shapes, generating the raw-set commands.

• src/officecli/Handlers/Word/WordHandler.Query.cs: Provides GetElementXml and GetSiblingRangeXml utilities used by the batch emitter to capture raw XML fragments without DOM manipulation.

Summary

• OfficeCLI dump batch round-trip serialization captures verbatim XML and binary payloads to preserve document fidelity beyond what standard APIs allow.
• The process uses specialized emit helpers in WordHandler.cs to extract OLE objects, ActiveX controls, VML shapes, and structural bookmarks.
• Batch replay defers saves until completion, optimizing performance to O(N) complexity.
• The text-based batch format supports piping, version control, and network transport while maintaining byte-level accuracy.
• Idempotence ensures that dump-batch-dump cycles produce consistent output suitable for automated verification.

Frequently Asked Questions

What is the difference between a standard dump and a batch format dump?

A standard dump produces a human-readable flat representation of document content, often losing embedded binary objects and complex relationships. The batch format preserves the exact OpenXML and binary payloads required for bit-identical reconstruction, including OLE objects, ActiveX controls, and VML shapes that the typed API cannot recreate.

How does the batch format handle binary objects like embedded Excel workbooks?

The GetOleEmitData method in WordHandler.cs captures the complete OleEmitData structure, which includes the embedded file bytes, icon bitmaps, and VML positioning information. During replay, the raw-set command writes these bytes directly to the target document's part structure without modification.

Can I use dump batch serialization for version control workflows?

Yes. Because the batch format outputs plain text containing base64-encoded binary data and readable XML commands, it integrates with Git or other VCS systems. The idempotent nature of the format ensures that identical documents produce identical batch files, enabling meaningful diffs and reliable historical reconstruction.

What performance optimizations does the batch replay implement?

The batch system sets DeferSave = true during replay, accumulating all mutations in memory and performing a single serialization operation at completion. This approach reduces computational complexity from O(N²) (where N is the number of commands) to O(N), making it practical for documents containing thousands of embedded objects or complex structural elements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}