# How to Use OfficeCLI Dump and Batch Commands for Round-Trip Document Serialization

> Master OfficeCLI dump and batch commands for true round-trip document serialization. Capture and reconstruct Office document XML and binary payloads losslessly.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-24

---

**OfficeCLI's `dump --format batch` command captures verbatim XML and binary payloads from Office documents, enabling lossless reconstruction via the `batch` command for true round-trip document serialization.**

The iOfficeAI/OfficeCLI repository implements a sophisticated serialization system that transcends simple text extraction. Unlike standard dumps that flatten document structure into human-readable formats, the batch format preserves every byte of binary data, relationship ID, and positioning attribute needed to recreate the original Word, Excel, or PowerPoint file exactly.

## Understanding the Three-Stage Round-Trip Architecture

The round-trip process operates through distinct dump, transport, and replay phases defined in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) and [`src/officecli/Handlers/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/WordHandler.cs).

### Stage 1: Dump Extraction

When you invoke `officecli dump --format batch`, the resident server walks the OpenXML DOM and calls specialized *emit* helpers to extract 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` return records containing the verbatim XML of each element alongside the raw bytes of every referenced part.

These helpers also capture structural metadata through `GetTableStructuralBookmarks`, `GetCellStructuralBookmarks`, and `GetPartRootStructuralPermMarkers`, ensuring elements outside the normal paragraph flow survive the round-trip.

### Stage 2: Transport Streaming

The extracted data serializes as plain-text batch commands (`add /…`, `raw‑set /…`, etc.) that can stream to stdout or files. Because the output is text-based, you can pipe it between processes, store it in version control, or transmit it over networks without corruption. The `ResidentServer.ProcessRequest` method in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) handles this `"dump"` command orchestration.

### Stage 3: Replay Reconstruction

The `officecli batch --input` command parses these commands and re-executes them on a target document via [`src/officecli/Handlers/Word/WordBatchEmitter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordBatchEmitter.cs). The emitter feeds the original *emit* data back into corresponding `add` and `raw‑set` implementations, reconstructing parts byte-for-byte while preserving original IDs and relationship references.

During replay, `DeferSave = true` ensures mutations accumulate in memory until the batch completes, reducing serialization cost from **O(N²)** to **O(N)** for N commands.

## What Gets Serialized in Batch Format

The batch format captures document components that standard APIs cannot recreate:

- **OLE Objects**: `OleEmitData` preserves embedded bytes, icon bytes, VML shape styles, and cropping information from `GetOleEmitData`
- **ActiveX Controls**: `ActiveXEmitData` stores run XML, referenced parts, and external relationships via `GetActiveXEmitData`
- **SmartArt Diagrams**: Stored as `ActiveXEmitData` structures capturing every diagram part's bytes
- **VML Shapes**: `VmlShapeEmitData` from `GetVmlShapeEmitData` retains run XML and image parts for legacy vector graphics
- **Structural Bookmarks**: Lists of `(Xml, RelXpath, Action)` tuples preserve table and cell markers invisible to the typed DOM
- **Custom Properties**: `EnumerateCustomDocPropertyNames` captures user-defined properties beyond the standard `OfficeCLI.*` namespace
- **Raw Part Replacements**: `RawReplaceWholePart` enables direct modification of [`docProps/custom.xml`](https://github.com/iOfficeAI/OfficeCLI/blob/main/docProps/custom.xml) and [`fontTable.xml`](https://github.com/iOfficeAI/OfficeCLI/blob/main/fontTable.xml) through the `raw‑set` command

## Command-Line Usage Examples

### Dumping a Document to Batch Format

Extract the complete document state including binary payloads:

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

```

This triggers [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) emit helpers to serialize every OLE object, ActiveX control, and VML shape into recoverable commands.

### Replaying a Batch File

Reconstruct the document on a fresh file:

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

```

The [`WordBatchEmitter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordBatchEmitter.cs) parser executes each command, deferring saves until the final operation for optimal performance.

### Piping for Zero-Copy Workflows

Stream dump output directly into batch replay without intermediate files:

```bash
officecli dump --format batch source.docx | \
  officecli batch --input - --file target.docx

```

Both commands understand plain-text streams, enabling efficient pipelined transformations.

### Programmatic API Access (C#)

Access the same functionality directly from .NET applications:

```csharp
using OfficeCli;
using OfficeCli.Handlers;

// Extract batch commands
var handler = DocumentHandlerFactory.Open("source.docx", editable: false);
var batchCommands = ((WordHandler)handler).EmitBatchCommands();
File.WriteAllLines("backup.batch", batchCommands);

// Replay on new document
var target = DocumentHandlerFactory.Open("target.docx", editable: true);
((WordHandler)target).ApplyBatchCommands(File.ReadAllLines("backup.batch"));
target.Save();

```

The `EmitBatchCommands` and `ApplyBatchCommands` methods wrap the internal helpers found in [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) and [`WordBatchEmitter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordBatchEmitter.cs).

## Fidelity Guarantees and Performance

OfficeCLI batch serialization provides **byte-level fidelity** for binary blobs including OLE packages and ActiveX controls. Relationship integrity remains intact because the dump includes original `r:id` references, and floating object positioning survives through preserved VML `style` attributes.

The process is **idempotent**: executing `dump → batch → dump` yields identical batch text (modulo command ordering). [`ResidentFlushPolicy.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentFlushPolicy.cs) manages auto-flush intervals during long-running batch operations to prevent memory pressure while maintaining the deferred save optimization.

## Summary

- **OfficeCLI dump and batch commands** enable lossless round-trip serialization of complex Office documents through plain-text batch commands
- **`dump --format batch`** extracts verbatim XML and binary data via helpers in [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) (`GetOleEmitData`, `GetActiveXEmitData`, etc.)
- **`batch --input`** replays commands through [`WordBatchEmitter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordBatchEmitter.cs) with deferred saves for **O(N)** performance
- **Byte-level preservation** covers OLE objects, ActiveX controls, VML shapes, structural bookmarks, and custom document properties
- **Streaming architecture** supports pipes and programmatic APIs for integration into automated workflows

## Frequently Asked Questions

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

Standard dump produces human-readable text representations of document content, while `dump --format batch` generates machine-readable commands that include raw binary payloads and relationship IDs. The batch format is the only mode that supports lossless reconstruction through the `batch` command.

### Does batch serialization preserve embedded macros and ActiveX controls?

Yes, the `GetActiveXEmitData` method in [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) captures the complete run XML, all referenced parts, and external relationships for ActiveX controls. OLE objects are similarly preserved through `GetOleEmitData`, ensuring embedded Excel workbooks and other binary content survive the round-trip intact.

### How does OfficeCLI handle binary data in the batch text format?

Binary payloads are encoded within the batch commands as Base64 or hex strings alongside their XML descriptors. During replay, [`WordBatchEmitter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordBatchEmitter.cs) decodes these payloads and writes them directly to the document package via `RawReplaceWholePart`, ensuring byte-for-byte fidelity without interpretation.

### Can I modify batch files manually before replaying them?

Yes, because batch files are plain text containing structured commands like `add /...` and `raw‑set /...`, you can edit them with standard text tools. However, modifying relationship IDs or binary payloads requires care to maintain referential integrity; the [`WordBatchEmitter.Resources.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordBatchEmitter.Resources.cs) file defines the exact command syntax expected during replay.