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

> Master OfficeCLI dump batch round trip serialization. This guide details lossless XML and binary payload capture for complete document reconstruction, including OLE objects and ActiveX controls. Enhance your workflow.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: deep-dive
- Published: 2026-07-12

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

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

```

Replay the batch to recreate a bit-identical copy:

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

```

Pipe directly without intermediate files:

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

```

### Programmatic API Usage

Access the batch serialization directly from C#:

```csharp
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs)**: Hosts the resident process, parses the `dump` command, and manages the batch output stream handling.

- **[`src/officecli/Handlers/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/WordHandler.cs)**: Contains the core emit helpers (`GetOleEmitData`, `GetActiveXEmitData`, `GetVmlShapeEmitData`) and structural bookmark extraction methods.

- **[`src/officecli/Handlers/Word/WordBatchEmitter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.