# When to Use Layer 3 (Raw XML) in OfficeCLI: A Complete Guide
> Master OfficeCLI's Layer 3 Raw XML for advanced OpenXML manipulation. Unlock direct XPath access for complex features, debugging, performance edits, and more. Enhance your document automation.
- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-18
---
**Use Layer 3 (Raw XML) in OfficeCLI when you need direct XPath access to OpenXML parts that the DOM layer cannot manipulate, such as complex features, precise targeting, batch part creation, debugging, or performance-critical bulk edits.**
OfficeCLI organizes document manipulation into a three-layer architecture, with Layer 3 serving as the escape hatch when semantic commands prove insufficient. According to the iOfficeAI/OfficeCLI source code, the `raw` and `raw-set` commands implemented in [`CommandBuilder.Raw.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Raw.cs) provide direct XML access, bypassing the abstraction layers that simplify common operations but restrict advanced customization.
## Understanding the Three-Layer Architecture
OfficeCLI structures its command hierarchy to balance ease of use against flexibility. Each layer builds upon the previous, with Layer 3 offering the most direct control at the cost of manual XML management.
### Layer 1: Read Operations
The **L1 Read** layer provides high-level semantic views of documents through the `view` command. This layer abstracts the underlying XML into readable summaries, ideal for quick inspection without requiring OpenXML knowledge.
### Layer 2: DOM Operations
The **L2 DOM** layer offers structured element manipulation through commands like `get`, `query`, `set`, and `add`. This layer handles path syntax translation and validation, providing a middle ground between usability and control. However, the DOM layer only supports elements with explicit command mappings.
### Layer 3: Raw XML
The **L3 Raw XML** layer removes abstraction entirely, exposing the actual OpenXML via XPath expressions. Found in [`src/officecli/CommandBuilder.Raw.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Raw.cs), this layer implements `raw`, `raw-set`, `add-part`, and `validate` commands. The `raw` command displays a part's XML (lines 12-55), while `raw-set` applies XPath-based edits (lines 60-106), forming the core fallback mechanism when L2 proves insufficient.
## Specific Use Cases for Layer 3 Raw XML
### Complex or Unsupported OpenXML Features
When manipulating elements that lack dedicated DOM-level commands, Layer 3 becomes essential. This includes custom VML shapes, non-standard relationships, proprietary extensions, or newly released OpenXML specifications that the DOM layer has not yet implemented. Direct XML access allows you to inject or modify these structures without waiting for command updates.
### Precise XPath Targeting
Layer 2 uses simplified path syntax, but Layer 3 accepts exact XPath expressions. Use Raw XML when you need to target elements based on complex predicates, namespace-specific queries, or positional logic that the DOM path syntax cannot express. This precision prevents unintended modifications in documents with repetitive structures.
### Batch Creation of New Parts
Creating entirely new document parts—such as custom charts, hidden slides, or specialized metadata containers—requires Layer 3 workflows. The typical pattern involves using `add-part` to generate the container and capture the relationship ID, followed by `raw-set` to populate the XML content. This two-step process enables the extension of document formats beyond standard templates.
### Debugging and Inspection
When higher-level commands fail or produce unexpected results, viewing the raw XML reveals the actual document state. Use the `raw` command to dump specific parts—such as individual PowerPoint slides or Excel worksheets—to files for manual inspection. This visibility helps identify namespace errors, malformed relationships, or corruption sources that abstract layers might mask.
### Performance-Critical Bulk Edits
Layer 2 introduces validation and mapping overhead that slows bulk operations. For scenarios requiring many small, rapid modifications—such as updating thousands of cells or mass-applying formatting attributes—direct XML manipulation via `raw-set` eliminates abstraction penalties. This approach trades safety checks for execution speed.
## Implementation Details in CommandBuilder.Raw.cs
The Layer 3 implementation resides in [`src/officecli/CommandBuilder.Raw.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Raw.cs), where two primary methods handle raw XML operations:
- **`raw`**: Retrieves and displays XML content from specified parts, supporting JSON output for programmatic parsing
- **`raw-set`**: Applies targeted modifications using XPath selectors, supporting actions like append, replace, or delete
These methods interact directly with the OpenXML SDK's part streams, bypassing the DOM wrapper classes used by Layer 2 commands. This direct access explains both the power and the risk of Layer 3 operations.
## Practical Examples
View the raw XML of the first slide in a PowerPoint file:
```bash
officecli raw deck.pptx '/slide[1]' --json
```
Append a new run element to the first paragraph in a Word document:
```bash
officecli raw-set report.docx '/document' \
--xpath "//w:p[1]" \
--action append \
--xml 'Injected text' --json
```
Create a custom chart part and insert raw XML:
```bash
# Add the part and capture the relationship ID
rel=$(officecli add-part chart.docx / --type chart --json | jq -r .relId)
# Insert raw XML into the new part
officecli raw-set chart.docx "/part[$rel]" \
--xpath "/chart" \
--action replace \
--xml ''
```
Debug an Excel formula issue by extracting the worksheet XML:
```bash
officecli raw sales.xlsx '/sheet[1]' > sheet1.xml
```
## Summary
- **Layer 3 (Raw XML)** in OfficeCLI provides direct XPath access to OpenXML parts when the DOM layer cannot express your requirements.
- Use `raw` and `raw-set` commands from [`CommandBuilder.Raw.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Raw.cs) to manipulate unsupported features, target specific XPath locations, create new document parts, debug corruption, and optimize bulk edit performance.
- Always verify XML syntax and namespace declarations when using Layer 3, as this bypasses the validation safeguards present in Layers 1 and 2.
- Combine `add-part` with `raw-set` to generate and populate custom document extensions.
## Frequently Asked Questions
### What is the difference between Layer 2 DOM and Layer 3 Raw XML in OfficeCLI?
Layer 2 DOM provides structured commands like `get` and `set` that handle OpenXML complexity behind simplified syntax, performing automatic validation and path translation. Layer 3 Raw XML removes these abstractions entirely, requiring you to write explicit XPath expressions and raw XML payloads, but granting access to elements that Layer 2 does not support.
### Can I corrupt my document using Layer 3 Raw XML?
Yes. Because `raw-set` writes XML directly to document parts without schema validation or relationship checking, malformed XML, incorrect namespaces, or invalid XPath targets can produce corrupted files that Office applications cannot open. Always work on copies when using Layer 3 operations.
### How do I find the correct XPath for a specific element in OfficeCLI?
Use the `raw` command to dump the target part's XML to a file, then inspect the structure to identify element names, namespaces, and hierarchy. The Office Open XML standards documentation provides canonical paths for standard elements, though document-specific variations may require manual inspection.
### Is Layer 3 faster than Layer 2 for bulk operations?
Generally yes. Layer 2 incurs overhead from DOM wrapper instantiation, validation, and path translation. When performing hundreds or thousands of edits, direct XML manipulation via `raw-set` avoids these abstraction layers, resulting in faster execution at the cost of reduced safety checks.