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

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 and 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, 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 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. 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 and 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:

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

This triggers 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:

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

The 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:

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:

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 and 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 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 (GetOleEmitData, GetActiveXEmitData, etc.)
• batch --input replays commands through 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 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 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 file defines the exact command syntax expected during replay.

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