When to Use OfficeCLI Raw XML Access (L3) Instead of the DOM (L2)

Use OfficeCLI's Level 3 raw XML access when the DOM lacks support for obscure OOXML attributes, when you need perfect round-trip fidelity for binary content, or when performing performance-critical bulk updates that must bypass the overhead of parsing and re-serializing the entire document.

OfficeCLI provides two distinct modes for manipulating Open XML documents: a high-level typed DOM (Level 2) and direct XML fragment injection (Level 3). While the DOM handles most day-to-day document editing through semantic commands, the raw XML access layer serves as an escape hatch for edge cases and advanced scenarios. Understanding when to switch from the typed API to raw XML ensures you maintain precision without sacrificing the CLI's automation capabilities.

Understanding OfficeCLI's Two-Level Architecture

Level 2: The DOM (Typed API)

The Level 2 DOM parses Open XML into a strongly-typed object model exposed through high-level commands like set, add, remove, and move. This API identifies document elements by semantic names, providing type safety, validation, and IDE auto-completion. Use this layer for standard operations such as formatting text, inserting tables, or managing images where the schema is well-defined and exposed by the DOM implementation.

Level 3: Raw XML Access (raw-set)

Level 3 bypasses the DOM entirely, working directly on underlying XML fragments via the raw-set verb. According to the source code in CommandBuilder.Raw.cs, this command inserts the exact XML payload you provide verbatim into the document package, or replaces existing nodes via explicit XPath targeting. This level operates without the validation and abstraction layers that might otherwise rewrite or sanitize your markup.

When to Choose Raw XML Access Over the DOM

The codebase explicitly distinguishes these paths in ResidentServer.cs (line 1118), where the command dispatcher routes "raw" or "raw-set" verbs to the raw-XML pipeline, bypassing normal DOM mutators. You should opt for L3 in the following scenarios:

• Unsupported Elements and Attributes: When the DOM reports "property not found" or cannot express required OOXML attributes, such as custom XML parts, obscure schema elements, or newly introduced markup not yet implemented in the typed API. As seen in WordHandler.Set.Dispatch.cs (line 1052), even standard properties may fall back to raw-set when the typed setter cannot represent the required XML structure.

• Round-Trip Fidelity: When you need to preserve embedded binary blobs, custom VML, or legacy markup exactly as-is. The DOM may rewrite or sanitize content during serialization, whereas raw XML access guarantees verbatim insertion.

• Performance-Critical Bulk Updates: When processing large documents where parsing and re-serializing the entire package would create unacceptable overhead. Raw XML access allows surgical updates to specific fragments without loading the full object model.

• Binary Data Manipulation: When embedding or manipulating binary data through embed-binary actions, which the DOM cannot represent. The raw-set command supports binary file embedding alongside XML payloads for complex package modifications.

Implementation Details in the Source Code

The architectural split between L2 and L3 is implemented across several key files:

• ResidentServer.cs: The command dispatcher at line 1118 determines the execution path based on the verb. If the command is "raw" or "raw-set", it invokes the raw-XML handler instead of routing through the DOM mutators.

• CommandBuilder.Raw.cs: Implements the raw and raw-set verbs, providing the entry point for L3 usage. This file handles the explicit XPath targeting and verbatim XML insertion logic.

• WordHandler.Set.Dispatch.cs: Contains fallback logic at line 1052 where typed setters delegate to raw-set when encountering properties the SDK treats as unknown or ambiguous.

• WordHandler.cs: Documents the raw-set capability at line 518, noting its use for "verbatim XML" when the structured API cannot represent specific features.

Practical Examples: L2 vs L3 Commands

The following examples demonstrate the difference between standard DOM operations and raw XML access.

Level 2 – DOM Approach:

Use the typed API for standard formatting tasks where the DOM exposes the necessary properties.

# Make the first paragraph bold using the high-level API

officecli set mydoc.docx /body/p[1] --prop bold=true

Level 3 – Raw XML Access:

Use raw-set when injecting custom attributes or elements outside the DOM's knowledge.

# Insert a custom element that the DOM does not support

officecli raw-set /body/p[1] --xpath "./w:p" \
    --xml '<w:p><w:r><w:t>Hello</w:t></w:r><w:myCustomAttr w:val="42"/></w:p>'

Level 3 – Embedding Binary Data:

When working with binary payloads that require precise XML wrapping.

# Embed a binary file as an OOXML relationship

officecli raw-set /customXml --action embed-binary \
    --xml '<my:customXmlPart xmlns:my="http://example.com"><my:data/></my:customXmlPart>' \
    --binary-file ./payload.bin

Summary

• Start with L2: Use the DOM (set, add, remove) for most document editing tasks involving standard OOXML elements like paragraphs, tables, and text formatting.
• Switch to L3 When: The DOM cannot expose an element, round-trip fidelity is required for binary content, or you need to avoid the overhead of full document serialization.
• Key Implementation: The dispatcher in ResidentServer.cs routes commands to raw XML handlers when using the raw-set verb, while CommandBuilder.Raw.cs manages the verbatim insertion logic.
• Safety: Raw XML access preserves markup exactly as provided, making it the safest choice for custom schemas and edge-case scenarios.

Frequently Asked Questions

What is the main difference between OfficeCLI L2 and L3?

Level 2 provides a strongly-typed DOM that abstracts Open XML into high-level commands with validation and auto-completion. Level 3 exposes raw XML access that inserts your markup verbatim without DOM abstraction, useful for unsupported schema elements or binary data.

How do I know if I need to use raw-set instead of the standard set command?

If the CLI returns a "property not found" error, or if you discover that specific attributes are being stripped or altered during DOM serialization, switch to raw-set. Check WordHandler.Set.Dispatch.cs for examples where the codebase itself falls back to raw XML when the typed API cannot represent a feature.

Can I use raw XML access for performance optimization?

Yes. Raw XML access avoids the overhead of parsing the entire document into a DOM and re-serializing it. For bulk updates or large document processing, injecting XML fragments directly via raw-set significantly reduces processing time compared to the typed API.

Does raw-set support binary file embedding?

Yes. The raw-set command includes an --action embed-binary option that allows you to embed binary files alongside XML payloads. This is essential for custom XML parts or binary data that the DOM cannot represent, as implemented in CommandBuilder.Raw.cs.

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