3382 lines
119 KiB
Markdown
3382 lines
119 KiB
Markdown
# OpenXML SDK C# Code Encyclopedia
|
||
Complete, heavily commented C# code patterns for DocumentFormat.OpenXml 3.x / .NET 8+ / C# 12.
|
||
|
||
**Namespace aliases used throughout:**
|
||
```csharp
|
||
using DocumentFormat.OpenXml;
|
||
using DocumentFormat.OpenXml.Packaging;
|
||
using DocumentFormat.OpenXml.Wordprocessing;
|
||
using A = DocumentFormat.OpenXml.Drawing;
|
||
using DW = DocumentFormat.OpenXml.Drawing.Wordprocessing;
|
||
using M = DocumentFormat.OpenXml.Math;
|
||
using PIC = DocumentFormat.OpenXml.Drawing.Pictures;
|
||
```
|
||
|
||
**EMU conversion reference** (used throughout image/shape code):
|
||
```
|
||
1 inch = 914400 EMU
|
||
1 cm = 360000 EMU
|
||
1 pixel @ 96dpi = 9525 EMU
|
||
1 pt = 12700 EMU
|
||
```
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
1. [Table of Contents (TOC)](#1-table-of-contents-toc)
|
||
2. [Footnotes and Endnotes](#2-footnotes-and-endnotes)
|
||
3. [Field Codes — Comprehensive](#3-field-codes--comprehensive)
|
||
4. [Track Changes / Revisions](#4-track-changes--revisions)
|
||
5. [Comments (4-File System)](#5-comments-4-file-system)
|
||
6. [Images — Deep Dive](#6-images--deep-dive)
|
||
7. [Drawing Shapes (Non-Image)](#7-drawing-shapes-non-image)
|
||
8. [Math / Equations (OMML)](#8-math--equations-omml)
|
||
9. [Numbering System — Deep Dive](#9-numbering-system--deep-dive)
|
||
10. [Document Protection & Encryption](#10-document-protection--encryption)
|
||
|
||
---
|
||
|
||
## 1. Table of Contents (TOC)
|
||
|
||
### 1.1 Basic TOC Field (SimpleField Pattern)
|
||
|
||
The simplest way to insert a TOC. Uses `SimpleField` which wraps the entire field in one element.
|
||
|
||
```csharp
|
||
// Creates:
|
||
// <w:p>
|
||
// <w:r>
|
||
// <w:fldChar w:fldCharType="begin"/>
|
||
// </w:r>
|
||
// <w:r>
|
||
// <w:instrText xml:space="preserve"> TOC \o "1-3" \h \z \u </w:instrText>
|
||
// </w:r>
|
||
// <w:r>
|
||
// <w:fldChar w:fldCharType="separate"/>
|
||
// </w:r>
|
||
// <w:r>
|
||
// <w:t>Update this field to generate table of contents.</w:t>
|
||
// </w:r>
|
||
// <w:r>
|
||
// <w:fldChar w:fldCharType="end"/>
|
||
// </w:r>
|
||
// </w:p>
|
||
|
||
var tocParagraph = new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" TOC \\o \"1-3\" \\h \\z \\u ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
// Placeholder text shown before update
|
||
new Run(new Text("Update this field to generate table of contents.") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
body.Append(tocParagraph);
|
||
```
|
||
|
||
**TOC switch reference:**
|
||
| Switch | Meaning |
|
||
|--------|---------|
|
||
| `\o "1-3"` | Include outline levels 1–3 (customize as needed) |
|
||
| `\h` | Make entries hyperlinks (clickable) |
|
||
| `\z` | Hide tab leader and page numbers in Web Layout view |
|
||
| `\u` | Use applied paragraph outline level |
|
||
| `\f` | TOC entry from bookmark |
|
||
| `\t "style1,style2"` | Use custom styles instead of outline levels |
|
||
| `\n "1-2"` | Omit page numbers for levels 1–2 |
|
||
|
||
### 1.2 TOC Field with SdtBlock Wrapper
|
||
|
||
Wrapping a TOC in a Structured Document Tag (SdtBlock) enables rich content control features.
|
||
|
||
```csharp
|
||
// SdtBlock wrapper provides:
|
||
// - Ability to repeat/remove the entire TOC
|
||
// - Richer programmatic control
|
||
// - "Content Control" appearance in Word UI
|
||
|
||
var sdtBlock = new SdtBlock(
|
||
// SdtProperties defines the control's identity and behavior
|
||
new SdtProperties(
|
||
new SdtAlias { Val = "Table of Contents" },
|
||
new Tag { Val = "toc" },
|
||
new SdtContentText() // Plain text content
|
||
),
|
||
// SdtContentBlock contains the actual TOC field
|
||
new SdtContentBlock(
|
||
new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" TOC \\o \"1-2\" \\h \\z ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("Press F9 or right-click and select 'Update Field'") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
)
|
||
)
|
||
);
|
||
body.Append(sdtBlock);
|
||
```
|
||
|
||
### 1.3 TOC with Custom Heading Levels
|
||
|
||
Use the `\t` switch to build a TOC from arbitrary styles (not just Heading 1–9).
|
||
|
||
```csharp
|
||
// TOC using custom style names instead of outline levels:
|
||
// \t switch format: "style1,level1,style2,level2,..."
|
||
// This uses CustomHeading1 and CustomHeading2 styles mapped to TOC levels
|
||
|
||
var customTocPara = new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" TOC \\t \"CustomHeading1,1,CustomHeading2,2,CustomHeading3,3\" \\h \\z ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("Update to see entries from CustomHeading1/2/3 styles.") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
```
|
||
|
||
### 1.4 TOC with Hyperlinks (\h switch)
|
||
|
||
The `\h` switch makes TOC entries clickable hyperlinks. This requires the entries to have a hyperlink anchor.
|
||
|
||
```csharp
|
||
// When \h is used, Word generates internal hyperlinks to each heading.
|
||
// The target is the bookmark automatically created by Word for headings.
|
||
// This is the standard pattern — no additional work needed in the field code itself.
|
||
|
||
var tocWithHyperlinks = new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" TOC \\o \"1-3\" \\h \\z \\u ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
// In Web Layout/Print Layout, Word will populate this with real entries
|
||
// Each entry will be a hyperlink pointing to the heading's internal bookmark
|
||
new Run(new Text("Click to update...") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
```
|
||
|
||
### 1.5 Auto-Update TOC on Document Open
|
||
|
||
You cannot programmatically update a TOC field's content (Word does this on open). Instead, tell Word to update fields automatically.
|
||
|
||
```csharp
|
||
// Method 1: Via DocumentSettingsPart — UpdateFieldsOnOpen
|
||
var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
|
||
settingsPart.Settings = new Settings(
|
||
new UpdateFieldsOnOpen { Val = true } // Triggers field update on open
|
||
);
|
||
settingsPart.Settings.Save();
|
||
|
||
// Method 2: Field code includes \w to preserve formatting changes
|
||
// (Field code approach is limited — you still need Word to evaluate it)
|
||
|
||
// GOTCHA: OpenXML SDK cannot evaluate field codes.
|
||
// Word evaluates fields on open. Other readers (e.g., LibreOffice) may not.
|
||
// The document opens without content until the user explicitly updates.
|
||
```
|
||
|
||
### 1.6 TOC Styles — Custom TOC1, TOC2, TOC3 Styles with Leaders
|
||
|
||
Define custom TOC styles with indentation, tab leaders, and proper formatting.
|
||
|
||
```csharp
|
||
// First, add TOC1/TOC2/TOC3 styles to StyleDefinitionsPart
|
||
var stylesPart = mainDocumentPart.AddNewPart<StyleDefinitionsPart>();
|
||
var styles = new Styles();
|
||
|
||
// TOC1 — Top-level entry (e.g., "1. Heading")
|
||
var toc1Style = new Style(
|
||
new StyleName { Val = "toc 1" },
|
||
new BasedOn { Val = "Normal" },
|
||
new PrimaryStyle(),
|
||
new StyleParagraphProperties(
|
||
new SpacingBetweenLines { Before = "120", After = "60" },
|
||
new Tabs(new TabStop { Val = TabStopValues.Right, Leader = TabStopLeaderCharValues.Dot, Position = 9072 }) // 5 inches right-aligned with dot leader
|
||
),
|
||
new StyleRunProperties(
|
||
new Bold(),
|
||
new FontSize { Val = "24" }, // 12pt
|
||
new FontSizeComplexScript { Val = "24" }
|
||
)
|
||
) { Type = StyleValues.Paragraph, StyleId = "TOC1" };
|
||
styles.Append(toc1Style);
|
||
|
||
// TOC2 — Second-level entry (e.g., "1.1 Subheading")
|
||
var toc2Style = new Style(
|
||
new StyleName { Val = "toc 2" },
|
||
new BasedOn { Val = "Normal" },
|
||
new PrimaryStyle(),
|
||
new StyleParagraphProperties(
|
||
new Indentation { Left = "220", Hanging = "220" }, // 0.15" indent, hang to align after number
|
||
new SpacingBetweenLines { Before = "60", After = "40" },
|
||
new Tabs(new TabStop { Val = TabStopValues.Right, Leader = TabStopLeaderCharValues.Dot, Position = 9072 })
|
||
),
|
||
new StyleRunProperties(
|
||
new FontSize { Val = "20" }, // 10pt
|
||
new FontSizeComplexScript { Val = "20" }
|
||
)
|
||
) { Type = StyleValues.Paragraph, StyleId = "TOC2" };
|
||
styles.Append(toc2Style);
|
||
|
||
// TOC3 — Third-level entry
|
||
var toc3Style = new Style(
|
||
new StyleName { Val = "toc 3" },
|
||
new BasedOn { Val = "Normal" },
|
||
new PrimaryStyle(),
|
||
new StyleParagraphProperties(
|
||
new Indentation { Left = "440", Hanging = "440" }, // 0.3" indent
|
||
new SpacingBetweenLines { Before = "40", After = "20" },
|
||
new Tabs(new TabStop { Val = TabStopValues.Right, Leader = TabStopLeaderCharValues.Dot, Position = 9072 })
|
||
),
|
||
new StyleRunProperties(
|
||
new Italic(),
|
||
new FontSize { Val = "20" },
|
||
new FontSizeComplexScript { Val = "20" }
|
||
)
|
||
) { Type = StyleValues.Paragraph, StyleId = "TOC3" };
|
||
styles.Append(toc3Style);
|
||
|
||
stylesPart.Styles = styles;
|
||
stylesPart.Styles.Save();
|
||
|
||
// Now use \t switch to reference these styles in the TOC field:
|
||
// TOC \t "TOC1,1,TOC2,2,TOC3,3" \h \z
|
||
```
|
||
|
||
**Tab leader options:** `TabStopLeaderCharValues.Dot` (........), `TabStopLeaderCharValues.Dash` (--------), `TabStopLeaderCharValues.Underscore` (________), `TabStopLeaderCharValues.MiddleDot` (·······).
|
||
|
||
### 1.7 Mini TOC for a Section
|
||
|
||
A mini TOC covers only a portion of the document using a bookmark-scoped `\f` switch.
|
||
|
||
```csharp
|
||
// Step 1: Define a bookmark around the section to be covered
|
||
var sectionStart = new BookmarkStart { Id = "10", Name = "_Section1TOC" };
|
||
var sectionEnd = new BookmarkEnd { Id = "10" };
|
||
|
||
// Step 2: Put heading paragraphs inside the bookmark range
|
||
var headingPara = new Paragraph(
|
||
new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
|
||
new Run(new Text("Section A: Introduction"))
|
||
);
|
||
|
||
// Full section wrapped in bookmark
|
||
body.Append(sectionStart);
|
||
body.Append(headingPara);
|
||
body.Append(sectionEnd);
|
||
|
||
// Step 3: Mini TOC field references that bookmark with \f switch
|
||
var miniTocPara = new Paragraph(
|
||
new Run(new Text("In this section: ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" TOC \\f _Section1TOC ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("Mini TOC placeholder") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Footnotes and Endnotes
|
||
|
||
### 2.1 FootnotesPart — Initialization
|
||
|
||
Footnotes in Word require a dedicated `FootnotesPart`. The first three footnotes are special: separator, continuation separator, and continuation notice.
|
||
|
||
```csharp
|
||
// Initialize the FootnotesPart
|
||
var footnotesPart = mainDocumentPart.AddNewPart<FootnotesPart>();
|
||
var footnotes = new Footnotes();
|
||
|
||
// CRITICAL: Footnotes must start with these 3 special footnotes:
|
||
// 1. Separator (id="0") — thin line between main text and footnotes
|
||
// 2. ContinuationSeparator (id="1") — thick line when footnotes continue to next column/page
|
||
// 3. ContinuationNotice (id="2") — "..." text when footnotes overflow
|
||
|
||
// Footnote ID=0: Separator (appears between main text and first footnote)
|
||
var separatorFootnote = new Footnote(
|
||
new Paragraph(
|
||
new ParagraphProperties(
|
||
new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }
|
||
),
|
||
// The separator is just a paragraph with a border at the bottom
|
||
new Paragraph(
|
||
new Run(new Separator())
|
||
)
|
||
)
|
||
) { Type = FootnoteEndnoteValues.Separator, Id = 0 };
|
||
footnotes.Append(separatorFootnote);
|
||
|
||
// Footnote ID=1: Continuation Separator
|
||
var continuationSepFootnote = new Footnote(
|
||
new Paragraph(
|
||
new ParagraphProperties(
|
||
new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }
|
||
),
|
||
new Run(new ContinuationSeparator())
|
||
)
|
||
) { Type = FootnoteEndnoteValues.ContinuationSeparator, Id = 1 };
|
||
footnotes.Append(continuationSepFootnote);
|
||
|
||
// Footnote ID=2: Continuation Notice (optional, appears when footnotes overflow)
|
||
var continuationNoticeFootnote = new Footnote(
|
||
new Paragraph(
|
||
new ParagraphProperties(
|
||
new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }
|
||
),
|
||
new Run(new Text("...") { Space = SpaceProcessingModeValues.Preserve })
|
||
)
|
||
) { Type = FootnoteEndnoteValues.ContinuationNotice, Id = 2 };
|
||
footnotes.Append(continuationNoticeFootnote);
|
||
|
||
footnotesPart.Footnotes = footnotes;
|
||
footnotesPart.Footnotes.Save();
|
||
```
|
||
|
||
### 2.2 Adding a Normal Footnote
|
||
|
||
Place a `FootnoteReference` in the document body and corresponding `Footnote` content in `FootnotesPart`.
|
||
|
||
```csharp
|
||
// In the document body, at the insertion point:
|
||
var footnoteRefRun = new Run(
|
||
new RunProperties(
|
||
new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
|
||
),
|
||
new FootnoteReference { Id = 3 } // ID must match the Footnote's Id
|
||
);
|
||
body.Append(new Paragraph(
|
||
new Run(new Text("Some text with a footnote marker.") { Space = SpaceProcessingModeValues.Preserve }),
|
||
footnoteRefRun
|
||
));
|
||
|
||
// In FootnotesPart, add the corresponding footnote content:
|
||
// <w:footnote w:id="3">
|
||
// <w:p>
|
||
// <w:pPr><w:pStyle w:val="FootnoteText"/></w:pPr>
|
||
// <w:r><w:footnoteRef/></w:r>
|
||
// <w:r><w:t xml:space="preserve"> This is the footnote text.</w:t></w:r>
|
||
// </w:p>
|
||
// </w:footnote>
|
||
|
||
var newFootnote = new Footnote { Id = 3 };
|
||
newFootnote.Append(new Paragraph(
|
||
new ParagraphProperties(new ParagraphStyleId { Val = "FootnoteText" }),
|
||
new Run(new FootnoteReferenceMark()), // Small superscript mark
|
||
new Run(new Text(" This is the footnote text.") { Space = SpaceProcessingModeValues.Preserve })
|
||
));
|
||
footnotesPart.Footnotes!.Append(newFootnote);
|
||
footnotesPart.Footnotes.Save();
|
||
```
|
||
|
||
### 2.3 Footnote with Custom Mark (Asterisk, Symbol)
|
||
|
||
Override the default auto-numbering with a custom symbol.
|
||
|
||
```csharp
|
||
// Use FootnoteReferenceMark (the automatic symbol) OR provide a custom character.
|
||
// For custom marks, use a regular Run with the symbol character instead of FootnoteReferenceMark.
|
||
|
||
// Footnote ID=4 with custom asterisk mark
|
||
var customFootnote = new Footnote { Id = 4 };
|
||
customFootnote.Append(new Paragraph(
|
||
new ParagraphProperties(new ParagraphStyleId { Val = "FootnoteText" }),
|
||
// Custom mark: use a bold asterisk from Symbol font
|
||
new Run(
|
||
new RunProperties(
|
||
new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
|
||
),
|
||
new RunFonts { Ascii = "Symbol", HighAnsi = "Symbol" },
|
||
new Text("*")
|
||
),
|
||
new Run(new Text(" Custom footnote with symbol mark.") { Space = SpaceProcessingModeValues.Preserve })
|
||
));
|
||
footnotesPart.Footnotes!.Append(customFootnote);
|
||
|
||
// In document body, at the insertion point:
|
||
var customFootnoteRef = new Run(
|
||
new RunProperties(
|
||
new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
|
||
),
|
||
new FootnoteReference { Id = 4 }
|
||
);
|
||
```
|
||
|
||
### 2.4 FootnotePosition — Placement via SectionProperties
|
||
|
||
Control whether footnotes appear at the bottom of each page or beneath the text.
|
||
|
||
```csharp
|
||
// Add FootnoteProperties to SectionProperties
|
||
var sectPr = body.Elements<SectionProperties>().First()
|
||
?? body.AppendChild(new SectionProperties());
|
||
|
||
// Footnote placement:
|
||
// - BottomOfPage (default) — footnotes appear at bottom of page
|
||
// - BeneathText — footnotes appear immediately below the last text on the page
|
||
sectPr.Append(new FootnoteProperties(
|
||
new FootnotePosition { Val = FootnotePositionValues.BeneathText }
|
||
));
|
||
|
||
// Footnote numbering restart options:
|
||
// - RestartAtSection — restart numbering at each section
|
||
// - RestartAtPage — restart at each page (Word default for footnotes)
|
||
// - Continuous — don't restart (number sequentially through document)
|
||
sectPr.Append(new FootnoteProperties(
|
||
new FootnotePosition { Val = FootnotePositionValues.BottomOfPage },
|
||
new FootnoteNumberingFormat { Val = NumberFormatValues.Decimal }, // 1, 2, 3...
|
||
new FootnoteNumberingStart { Val = 1 }, // Start at 1
|
||
new FootnoteNumberingRestart { Val = FootnoteRestartValues.RestartAtPage }
|
||
));
|
||
```
|
||
|
||
### 2.5 EndnotesPart — Same Pattern
|
||
|
||
Endnotes follow the exact same structure as footnotes but use `EndnotesPart`.
|
||
|
||
```csharp
|
||
var endnotesPart = mainDocumentPart.AddNewPart<EndnotesPart>();
|
||
var endnotes = new Endnotes();
|
||
|
||
// Endnote ID=0: Separator (same pattern as footnotes)
|
||
var endnoteSeparator = new Endnote(
|
||
new Paragraph(new Run(new Separator()))
|
||
) { Type = FootnoteEndnoteValues.Separator, Id = 0 };
|
||
endnotes.Append(endnoteSeparator);
|
||
|
||
// Endnote ID=1: ContinuationSeparator
|
||
var endnoteContSep = new Endnote(
|
||
new Paragraph(new Run(new ContinuationSeparator()))
|
||
) { Type = FootnoteEndnoteValues.ContinuationSeparator, Id = 1 };
|
||
endnotes.Append(endnoteContSep);
|
||
|
||
endnotesPart.Endnotes = endnotes;
|
||
endnotesPart.Endnotes.Save();
|
||
|
||
// In document body, use EndnoteReference instead of FootnoteReference
|
||
var endnoteRefRun = new Run(
|
||
new RunProperties(
|
||
new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
|
||
),
|
||
new EndnoteReference { Id = 3 }
|
||
);
|
||
body.Append(new Paragraph(
|
||
new Run(new Text("An endnote marker.") { Space = SpaceProcessingModeValues.Preserve }),
|
||
endnoteRefRun
|
||
));
|
||
|
||
// Corresponding Endnote content in EndnotesPart
|
||
var newEndnote = new Endnote { Id = 3 };
|
||
newEndnote.Append(new Paragraph(
|
||
new ParagraphProperties(new ParagraphStyleId { Val = "EndnoteText" }),
|
||
new Run(new EndnoteReferenceMark()),
|
||
new Run(new Text(" This is the endnote content.") { Space = SpaceProcessingModeValues.Preserve })
|
||
));
|
||
endnotesPart.Endnotes!.Append(newEndnote);
|
||
```
|
||
|
||
### 2.6 Endnote Placement via SectionProperties
|
||
|
||
```csharp
|
||
// EndnoteProperties on SectionProperties controls endnote placement
|
||
sectPr.Append(new EndnoteProperties(
|
||
new EndnotePosition { Val = EndnotePositionValues.EndOfDocument } // Default
|
||
// Other options: EndOfSection, BeneathText (rarely used for endnotes)
|
||
));
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Field Codes — Comprehensive
|
||
|
||
### 3.1 SimpleField vs Complex Field Architecture
|
||
|
||
**SimpleField** — single element, easier to write but less control:
|
||
```csharp
|
||
// <w:fldSimple w:instr=" PAGE "><w:r><w:t>1</w:t></w:r></w:fldSimple>
|
||
new SimpleField(new Run(new Text("1"))) { Instruction = " PAGE " }
|
||
```
|
||
|
||
**Complex Field (Begin/Separate/End)** — full control over each field component:
|
||
```csharp
|
||
// <w:r><w:fldChar w:fldCharType="begin"/></w:r>
|
||
// <w:r><w:instrText> PAGE </w:instrText></w:r>
|
||
// <w:r><w:fldChar w:fldCharType="separate"/></w:r>
|
||
// <w:r><w:t>1</w:t></w:r>
|
||
// <w:r><w:fldChar w:fldCharType="end"/></w:r>
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("1")), // Cached result shown until update
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
|
||
```
|
||
|
||
**Key differences:**
|
||
- `SimpleField` is one `w:fldSimple` element containing one `w:r`
|
||
- Complex field uses `FieldChar` with `FieldCharValues.Begin/Separate/End` to delimit regions
|
||
- `FieldCode` is `w:instrText` — contains the field instruction string
|
||
- The text between `Separate` and `End` is the "cached result" shown before update
|
||
- After `Separate`, `FieldCode` contains the switches that define field behavior
|
||
|
||
### 3.2 PAGE, NUMPAGES, DATE, TIME
|
||
|
||
**PAGE — current page number:**
|
||
```csharp
|
||
// SimpleField version
|
||
new SimpleField(new Run(new Text("1"))) { Instruction = " PAGE " }
|
||
|
||
// Complex field version
|
||
new Paragraph(
|
||
new Run(new Text("Page ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("1")), // Cached value
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
```
|
||
|
||
**NUMPAGES — total page count:**
|
||
```csharp
|
||
new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" NUMPAGES ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("10")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
|
||
new Run(new Text(" pages") { Space = SpaceProcessingModeValues.Preserve })
|
||
);
|
||
```
|
||
|
||
**DATE — current date with format switch:**
|
||
```csharp
|
||
// DATE with custom format: \@ "yyyy-MM-dd"
|
||
// The \@ switch specifies the date picture
|
||
new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" DATE \\@ \"yyyy-MM-dd\" ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("2026-03-22")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
|
||
// DATE with time: \@ "MMMM d, yyyy h:mm AM/PM"
|
||
new Run(new FieldCode(" DATE \\@ \"MMMM d, yyyy h:mm AM/PM\" ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
|
||
// DATE with locale: \* MERGEFORMAT preserves formatting on update
|
||
new Run(new FieldCode(" DATE \\@ \"d/M/yyyy\" \\* MERGEFORMAT ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
```
|
||
|
||
**TIME — current time:**
|
||
```csharp
|
||
new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" TIME \\@ \"HH:mm:ss\" ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("14:30:00")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
```
|
||
|
||
### 3.3 FILENAME, AUTHOR, TITLE (Document Properties)
|
||
|
||
These fields pull from the document's core properties.
|
||
|
||
```csharp
|
||
// FILENAME — document filename
|
||
new Run(new FieldCode(" FILENAME ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
|
||
// FILENAME with path: \* MERGEFORMAT
|
||
new Run(new FieldCode(" FILENAME \\* MERGEFORMAT ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
|
||
// AUTHOR — from document core properties
|
||
new Run(new FieldCode(" AUTHOR ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
|
||
// TITLE — from document core properties
|
||
new Run(new FieldCode(" TITLE ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
|
||
// SUBJECT — from document core properties
|
||
new Run(new FieldCode(" SUBJECT ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
|
||
// Keywords — from document core properties
|
||
new Run(new FieldCode(" KEYWORDS ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
|
||
// All document property fields
|
||
new Paragraph(
|
||
new Run(new Text("Title: ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" TITLE ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("My Document")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
```
|
||
|
||
**Set document properties programmatically:**
|
||
```csharp
|
||
// Set core properties via PackageProperties (OfficePackage)
|
||
var package = doc.ExtendedFilePropertiesPart?.Properties;
|
||
if (package != null)
|
||
{
|
||
package.Creator = "Author Name";
|
||
package.Title = "Document Title";
|
||
package.Subject = "Subject";
|
||
package.Description = "Description";
|
||
package.Keywords = "keyword1, keyword2";
|
||
package.Save();
|
||
}
|
||
```
|
||
|
||
### 3.4 REF — Cross-Reference to Bookmark
|
||
|
||
`REF` retrieves the text of a bookmarked paragraph or the value of a REF field.
|
||
|
||
```csharp
|
||
// First, create a bookmark around some content
|
||
var bookmarkStart = new BookmarkStart { Id = "100", Name = "Figure1Caption" };
|
||
var bookmarkEnd = new BookmarkEnd { Id = "100" };
|
||
var captionPara = new Paragraph(
|
||
new Run(new Text("Figure 1: Architecture diagram") { Space = SpaceProcessingModeValues.Preserve })
|
||
);
|
||
body.Append(new Paragraph(
|
||
new ParagraphProperties(new ParagraphStyleId { Val = "Caption" }),
|
||
bookmarkStart,
|
||
new Run(new Text("Figure 1: Architecture diagram")),
|
||
bookmarkEnd
|
||
));
|
||
|
||
// Now reference it with REF field
|
||
var refField = new Paragraph(
|
||
new Run(new Text("As shown in ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" REF Figure1Caption \\* MERGEFORMAT ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("Figure 1: Architecture diagram")), // Cached result
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
|
||
new Run(new Text(", the system consists of...") { Space = SpaceProcessingModeValues.Preserve })
|
||
);
|
||
```
|
||
|
||
**REF switches:**
|
||
| Switch | Effect |
|
||
|--------|--------|
|
||
| `\r` | Insert bookmarked text but as hyperlink |
|
||
| `\h` | Make REF a hyperlink to the bookmark |
|
||
| `\n` | Suppress paragraph number |
|
||
| `\p` | Show relative position (above/below) |
|
||
| `\t` | Suppress trailing spaces |
|
||
| `\* MERGEFORMAT` | Preserve formatting |
|
||
|
||
### 3.5 SEQ — Sequence Numbering for Figures/Tables
|
||
|
||
`SEQ` generates auto-incrementing numbers for elements like figures, tables, and listings.
|
||
|
||
```csharp
|
||
// First figure caption
|
||
var fig1Caption = new Paragraph(
|
||
new ParagraphProperties(new ParagraphStyleId { Val = "Caption" }),
|
||
new Run(new Text("Figure ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" SEQ Figure \\* ARABIC ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("1")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
|
||
new Run(new Text(": System Architecture") { Space = SpaceProcessingModeValues.Preserve })
|
||
);
|
||
|
||
// Second figure (Word auto-increments)
|
||
var fig2Caption = new Paragraph(
|
||
new ParagraphProperties(new ParagraphStyleId { Val = "Caption" }),
|
||
new Run(new Text("Figure ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" SEQ Figure \\* ARABIC ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("2")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
|
||
new Run(new Text(": Data Flow") { Space = SpaceProcessingModeValues.Preserve })
|
||
);
|
||
|
||
// Reference a figure number
|
||
var figRef = new Paragraph(
|
||
new Run(new Text("See Figure ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" SEQ Figure \\* ARABIC ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("1")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
|
||
new Run(new Text(" above.") { Space = SpaceProcessingModeValues.Preserve })
|
||
);
|
||
|
||
// SEQ sequence identifier: "Figure" can be any name
|
||
// Multiple sequences: SEQ Figure, SEQ Table, SEQ Listing are independent
|
||
```
|
||
|
||
### 3.6 HYPERLINK — Internal and External Links
|
||
|
||
```csharp
|
||
// External hyperlink (to URL)
|
||
var extHyperlinkRel = mainDocumentPart.AddHyperlinkRelationship(
|
||
new Uri("https://example.com"), true);
|
||
var extHyperlink = new Hyperlink(
|
||
new Run(
|
||
new RunProperties(new Color { Val = "0563C1" }, new Underline { Val = UnderlineValues.Single }),
|
||
new Text("Visit Example.com")
|
||
)
|
||
) { Id = extHyperlinkRel.Id }; // Id references the relationship
|
||
|
||
// Internal hyperlink (to bookmark)
|
||
var intHyperlink = new Hyperlink(
|
||
new Run(
|
||
new RunProperties(new Color { Val = "0563C1" }, new Underline { Val = UnderlineValues.Single }),
|
||
new Text("Go to Chapter 1")
|
||
)
|
||
) { Anchor = "Chapter1Bookmark" }; // Anchor = bookmark name
|
||
|
||
// HYPERLINK field for advanced cases (with screen tip)
|
||
var hyperlinkedField = new Run(
|
||
new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" HYPERLINK \\l \"Chapter1Bookmark\" \\t \"_top\" ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("Go to Chapter 1")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
|
||
// \l = target (anchor for internal, URL for external)
|
||
// \t = target frame (optional, e.g., "_top" to open in same window)
|
||
```
|
||
|
||
### 3.7 MERGEFIELD — Mail Merge
|
||
|
||
```csharp
|
||
// MERGEFIELD uses a special syntax: MERGEFIELD FieldName
|
||
// The field name must match a mail merge data source column name
|
||
|
||
// Simple MERGEFIELD
|
||
var mergeFieldPara = new Paragraph(
|
||
new Run(new Text("Dear ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" MERGEFIELD FirstName ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("«FirstName»")), // «» are Word's placeholder markers
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
|
||
new Run(new Text(",") { Space = SpaceProcessingModeValues.Preserve })
|
||
);
|
||
|
||
// Full name with formatting
|
||
var mergeFieldWithFormat = new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" MERGEFIELD FullName \\* UPPERCASE ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("«FullName»")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
|
||
// To actually perform mail merge, use Word's MailMerge settings
|
||
var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
|
||
settingsPart.Settings = new Settings(
|
||
new MailMerge(
|
||
new DataType { Val = MailMergeDataValues.TextFile },
|
||
new DataSourceReference { Id = "rIdForDataSource" }
|
||
)
|
||
);
|
||
```
|
||
|
||
### 3.8 IF Field — Conditional Text
|
||
|
||
The `IF` field evaluates a condition and displays one of two text values. Commonly used with `MERGEFIELD`.
|
||
|
||
```csharp
|
||
// IF Field syntax: IF [expression] [operator] [value] "true_text" "false_text"
|
||
// Often combined with MERGEFIELD:
|
||
|
||
// If the recipient's region equals "USA", show "Dear Customer", otherwise "Dear Valued Customer"
|
||
var ifFieldPara = new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
// Complex nested: { IF { MERGEFIELD Region } = "USA" "Dear American Customer" "Dear Customer" }
|
||
new Run(new FieldCode(" IF ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }), // Nested MERGEFIELD begin
|
||
new Run(new FieldCode(" MERGEFIELD Region ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("«Region»")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End }), // Nested MERGEFIELD end
|
||
new Run(new FieldCode(" = \"USA\" \"Dear American Customer\" \"Dear Customer\" ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("Dear Customer")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
|
||
// Note: Nested fields within IF are tricky with complex field syntax.
|
||
// A simpler approach: use two separate IF fields checking a bookmark value.
|
||
```
|
||
|
||
### 3.9 STYLEREF — Reference Heading Text
|
||
|
||
`STYLEREF` displays the text of the nearest paragraph with a specified style — useful for running headers.
|
||
|
||
```csharp
|
||
// STYLEREF Heading1 — inserts the text of the most recent Heading1 paragraph
|
||
// Great for running headers that show the current chapter
|
||
|
||
// Running header in footer
|
||
var footerPart = mainDocumentPart.AddNewPart<FooterPart>();
|
||
footerPart.Footer = new Footer(
|
||
new Paragraph(
|
||
new ParagraphProperties(
|
||
new Justification { Val = JustificationValues.Right }
|
||
),
|
||
// Left-aligned: chapter heading
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" STYLEREF \"Heading 1\" ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("Chapter Title")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
|
||
new Run(new Text("\t") { Space = SpaceProcessingModeValues.Preserve }), // Tab
|
||
// Right-aligned: page number
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("1")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
)
|
||
);
|
||
|
||
// STYLEREF with \n switch to suppress paragraph numbering
|
||
new Run(new FieldCode(" STYLEREF \"Heading 1\" \\n ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
|
||
// STYLEREF with \p switch to show relative position
|
||
new Run(new FieldCode(" STYLEREF \"Heading 2\" \\p ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
```
|
||
|
||
### 3.10 SET and ASK Fields
|
||
|
||
`SET` stores a value in a variable. `ASK` prompts the user and stores their response.
|
||
|
||
```csharp
|
||
// SET — define a document variable (accessed via DOCPROPERTY or REF)
|
||
var setField = new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" SET MyVariable \"some value\" ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
|
||
// REF to read the variable
|
||
var refMyVar = new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" REF MyVariable ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("some value")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
|
||
// ASK — prompt user for input when field is updated
|
||
// Note: ASK displays a dialog box when updated
|
||
var askField = new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" ASK AuthorName \"Enter author name:\" ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
|
||
// REF to display the stored value
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" REF AuthorName ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("Author Name")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
```
|
||
|
||
### 3.11 Calculated Fields (= Expressions)
|
||
|
||
The `=` field evaluates arithmetic expressions.
|
||
|
||
```csharp
|
||
// = field with arithmetic
|
||
var calcPara = new Paragraph(
|
||
new Run(new Text("Total: $") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" = 100 + 250 - 30 ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("320")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
|
||
// = with multiplication using SEQ references
|
||
var calcWithSeq = new Paragraph(
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
|
||
new Run(new FieldCode(" = 3 * 5 ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
|
||
new Run(new Text("15")),
|
||
new Run(new FieldChar { FieldCharType = FieldCharValues.End })
|
||
);
|
||
|
||
// Combine with formatting
|
||
new Run(new FieldCode(" = 1000 * 1.08 \\# \"#,##0.00\" ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
// \# switch applies number format to result
|
||
```
|
||
|
||
### 3.12 UpdateFieldsOnOpen — Automatic Field Updates
|
||
|
||
```csharp
|
||
// Settings that trigger field updates when document opens
|
||
var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
|
||
settingsPart.Settings = new Settings(
|
||
// Update all fields (TOC, REF, PAGE, etc.) on open
|
||
new UpdateFieldsOnOpen { Val = true }
|
||
);
|
||
settingsPart.Settings.Save();
|
||
|
||
// Additional field-related settings:
|
||
var additionalSettings = new Settings(
|
||
// Auto-format fractions: 1/2 → ½
|
||
new AutomaticAdjustmentOfFontSizesToFitDocument(),
|
||
|
||
// True: use field codes instead of cached values on update
|
||
new UseXSLTWhenSaving(),
|
||
|
||
// Mail merge settings
|
||
new MailMerge(
|
||
new MainDocumentType { Val = MailMergeDocumentValues.FormLetters }
|
||
)
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Track Changes / Revisions
|
||
|
||
### 4.1 Enabling Track Changes
|
||
|
||
Track changes must be explicitly enabled via DocumentSettingsPart.
|
||
|
||
```csharp
|
||
var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
|
||
settingsPart.Settings = new Settings(
|
||
// Enable track changes — any edit will be tracked
|
||
new TrackRevisions()
|
||
);
|
||
|
||
// Also recommended: prevent fields from being updated during tracking
|
||
settingsPart.Settings.Append(new DonNotTrackFormatting());
|
||
```
|
||
|
||
### 4.2 InsertedRun (w:ins) — Tracked Insertion
|
||
|
||
```csharp
|
||
// <w:ins w:id="5" w:author="Alice" w:date="2026-03-22T10:00:00Z">
|
||
// <w:r>
|
||
// <w:t>Inserted text.</w:t>
|
||
// </w:r>
|
||
// </w:ins>
|
||
|
||
var insertedText = new InsertedRun(
|
||
new Run(
|
||
new Text("Inserted text.") { Space = SpaceProcessingModeValues.Preserve }
|
||
)
|
||
)
|
||
{
|
||
Author = "Alice",
|
||
Date = new DateTime(2026, 3, 22, 10, 0, 0, DateTimeKind.Utc),
|
||
Id = "5"
|
||
};
|
||
|
||
var para = new Paragraph(
|
||
new Run(new Text("Existing text. ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
insertedText,
|
||
new Run(new Text(" More existing text.") { Space = SpaceProcessingModeValues.Preserve })
|
||
);
|
||
```
|
||
|
||
### 4.3 DeletedRun (w:del) — Tracked Deletion
|
||
|
||
**CRITICAL: Inside `w:del`, text MUST be `DeletedText` (`w:delText`), NOT `Text` (`w:t`)!**
|
||
|
||
```csharp
|
||
// <w:del w:id="6" w:author="Alice" w:date="2026-03-22T10:05:00Z">
|
||
// <w:r>
|
||
// <w:rPr><w:b/></w:rPr>
|
||
// <w:delText>Deleted text.</w:delText>
|
||
// </w:r>
|
||
// </w:del>
|
||
|
||
var deletedRun = new DeletedRun(
|
||
new Run(
|
||
new RunProperties(new Bold()),
|
||
new DeletedText("Deleted text.") { Space = SpaceProcessingModeValues.Preserve }
|
||
)
|
||
)
|
||
{
|
||
Author = "Alice",
|
||
Date = new DateTime(2026, 3, 22, 10, 5, 0, DateTimeKind.Utc),
|
||
Id = "6"
|
||
};
|
||
|
||
var para = new Paragraph(
|
||
new Run(new Text("Keep this. ") { Space = SpaceProcessingModeValues.Preserve }),
|
||
deletedRun,
|
||
new Run(new Text(" Keep this too.") { Space = SpaceProcessingModeValues.Preserve })
|
||
);
|
||
|
||
// GOTCHA: Never use <w:t> inside <w:del> — use <w:delText> only.
|
||
// Using w:t inside w:del causes corruption or silent repair by Word.
|
||
```
|
||
|
||
### 4.4 RunPropertiesChange — Formatting Change Tracking
|
||
|
||
Records that a run's formatting was changed. The `w:rPrChange` goes inside `w:rPr`.
|
||
|
||
```csharp
|
||
// <w:r>
|
||
// <w:rPr>
|
||
// <w:b/> <!-- New: bold -->
|
||
// <w:rPrChange w:id="7" w:author="Bob" w:date="2026-03-22T11:00:00Z">
|
||
// <w:rPr/> <!-- Old: no formatting -->
|
||
// </w:rPrChange>
|
||
// </w:rPr>
|
||
// <w:t>Formatted text.</w:t>
|
||
// </w:r>
|
||
|
||
// The current (new) formatting is in the outer w:rPr
|
||
// The old (previous) formatting is in the w:rPrChange child
|
||
var formattedTextRun = new Run(
|
||
new RunProperties(
|
||
new Bold(), // New formatting: now bold
|
||
new RunPropertiesChange( // Records the old formatting (empty = not bold)
|
||
new RunProperties() // Empty = previously had no formatting
|
||
)
|
||
{
|
||
Author = "Bob",
|
||
Date = new DateTime(2026, 3, 22, 11, 0, 0, DateTimeKind.Utc),
|
||
Id = "7"
|
||
}
|
||
),
|
||
new Text("Formatted text.") { Space = SpaceProcessingModeValues.Preserve }
|
||
);
|
||
```
|
||
|
||
### 4.5 ParagraphPropertiesChange
|
||
|
||
Records that paragraph-level properties were changed.
|
||
|
||
```csharp
|
||
// <w:pPr>
|
||
// <w:jc w:val="center"/> <!-- New: centered -->
|
||
// <w:pPrChange w:id="8" w:author="Bob" w:date="2026-03-22T11:05:00Z">
|
||
// <w:pPr>
|
||
// <w:jc w:val="left"/> <!-- Old: left-aligned -->
|
||
// </w:pPr>
|
||
// </w:pPrChange>
|
||
// </w:pPr>
|
||
|
||
var changedPara = new Paragraph(
|
||
new ParagraphProperties(
|
||
new Justification { Val = JustificationValues.Center }, // New
|
||
new ParagraphPropertiesChange(
|
||
new ParagraphProperties(
|
||
new Justification { Val = JustificationValues.Left } // Old
|
||
)
|
||
)
|
||
{
|
||
Author = "Bob",
|
||
Date = new DateTime(2026, 3, 22, 11, 5, 0, DateTimeKind.Utc),
|
||
Id = "8"
|
||
}
|
||
),
|
||
new Run(new Text("Centered paragraph."))
|
||
);
|
||
```
|
||
|
||
### 4.6 ParagraphMarkRunPropertiesChange
|
||
|
||
Records that the paragraph mark's formatting (trailing formatting) was changed.
|
||
|
||
```csharp
|
||
// <w:p>
|
||
// <w:pPr>
|
||
// <w:pPrChange .../>
|
||
// </w:pPr>
|
||
// <w:r>
|
||
// <w:rPr>
|
||
// <w:b/> <!-- New paragraph mark: bold -->
|
||
// <w:rPrChange w:id="9" ...>
|
||
// <w:rPr/> <!-- Old: no formatting on paragraph mark -->
|
||
// </w:rPrChange>
|
||
// </w:rPr>
|
||
// </w:r>
|
||
// </w:r>
|
||
```
|
||
|
||
### 4.7 Table Revision Marks
|
||
|
||
```csharp
|
||
// TableRowInsertionRevision — a row was inserted
|
||
// <w:trPr>
|
||
// <w:ins w:id="10" w:author="Alice" w:date="..."/>
|
||
// </w:trPr>
|
||
|
||
var insertedRow = new TableRow(
|
||
new TableRowProperties(
|
||
new TableRowInsertionRevision
|
||
{
|
||
Author = "Alice",
|
||
Date = new DateTime(2026, 3, 22, 12, 0, 0, DateTimeKind.Utc),
|
||
Id = "10"
|
||
}
|
||
),
|
||
new TableCell(new Paragraph(new Run(new Text("New row cell"))))
|
||
);
|
||
|
||
// TableCellInsertionRevision — a cell was inserted
|
||
var insertedCell = new TableCell(
|
||
new TableCellProperties(
|
||
new TableCellInsertionRevision
|
||
{
|
||
Author = "Alice",
|
||
Date = new DateTime(2026, 3, 22, 12, 1, 0, DateTimeKind.Utc),
|
||
Id = "11"
|
||
}
|
||
),
|
||
new Paragraph(new Run(new Text("New cell")))
|
||
);
|
||
```
|
||
|
||
### 4.8 SectionPropertiesChange
|
||
|
||
```csharp
|
||
// <w:sectPr>
|
||
// <w:sectPrChange w:id="12" w:author="Bob" w:date="...">
|
||
// <w:sectPr>
|
||
// <w:pgSz w:w="12240" w:h="15840"/> <!-- Old: Letter -->
|
||
// </w:sectPr>
|
||
// </w:sectPrChange>
|
||
// <w:pgSz w:w="16838" w:h="11906"/> <!-- New: A4 -->
|
||
// </w:sectPr>
|
||
|
||
var changedSection = new SectionProperties(
|
||
new PageSize { Width = 16838U, Height = 11906U }, // New: A4
|
||
new SectionPropertiesChange(
|
||
new SectionProperties(
|
||
new PageSize { Width = 12240U, Height = 15840U } // Old: Letter
|
||
)
|
||
)
|
||
{
|
||
Author = "Bob",
|
||
Date = new DateTime(2026, 3, 22, 12, 30, 0, DateTimeKind.Utc),
|
||
Id = "12"
|
||
}
|
||
);
|
||
```
|
||
|
||
### 4.9 NumberingChange
|
||
|
||
```csharp
|
||
// <w:numPr>
|
||
// <w:ilvl w:val="0"/>
|
||
// <w:numId w:val="3"/>
|
||
// <w:numPrChange w:id="13" w:author="Alice" w:date="...">
|
||
// <w:numPr>
|
||
// <w:ilvl w:val="0"/>
|
||
// <w:numId w:val="1"/> <!-- Old: was numId 1 -->
|
||
// </w:numPr>
|
||
// </w:numPrChange>
|
||
// </w:numPr>
|
||
|
||
var changedNumbering = new NumberingProperties(
|
||
new NumberingLevelReference { Val = 0 },
|
||
new NumberingId { Val = 3 }, // New: numId 3
|
||
new NumberingChange(
|
||
new NumberingProperties(
|
||
new NumberingLevelReference { Val = 0 },
|
||
new NumberingId { Val = 1 } // Old: numId 1
|
||
)
|
||
)
|
||
{
|
||
Author = "Alice",
|
||
Date = new DateTime(2026, 3, 22, 13, 0, 0, DateTimeKind.Utc),
|
||
Id = "13"
|
||
}
|
||
);
|
||
```
|
||
|
||
### 4.10 Accepting All Revisions Programmatically
|
||
|
||
```csharp
|
||
// Accept all revisions: unwrap w:ins (keep content), remove w:del entirely
|
||
public static void AcceptAllRevisions(WordprocessingDocument doc)
|
||
{
|
||
var body = doc.MainDocumentPart?.Document?.Body;
|
||
if (body == null) return;
|
||
|
||
// Accept insertions: remove w:ins wrapper, keep inner runs
|
||
var insertions = body.Descendants<InsertedRun>().ToList();
|
||
foreach (var ins in insertions)
|
||
{
|
||
var parent = ins.Parent;
|
||
if (parent == null) continue;
|
||
var children = ins.ChildElements.ToList();
|
||
foreach (var child in children)
|
||
{
|
||
child.Remove();
|
||
parent.InsertBefore(child, ins);
|
||
}
|
||
ins.Remove();
|
||
}
|
||
|
||
// Accept deletions: remove entire w:del element
|
||
var deletions = body.Descendants<DeletedRun>().ToList();
|
||
foreach (var del in deletions)
|
||
del.Remove();
|
||
}
|
||
|
||
// Also accept formatting changes:
|
||
// For w:rPrChange: replace the entire RunProperties with the "old" properties inside the change
|
||
// For w:pPrChange: replace with the old properties
|
||
```
|
||
|
||
### 4.11 Rejecting All Revisions Programmatically
|
||
|
||
```csharp
|
||
// Reject all revisions: unwrap w:del (restore text), remove w:ins entirely
|
||
public static void RejectAllRevisions(WordprocessingDocument doc)
|
||
{
|
||
var body = doc.MainDocumentPart?.Document?.Body;
|
||
if (body == null) return;
|
||
|
||
// Reject insertions: remove entire w:ins element and its content
|
||
var insertions = body.Descendants<InsertedRun>().ToList();
|
||
foreach (var ins in insertions)
|
||
ins.Remove();
|
||
|
||
// Reject deletions: unwrap w:del, convert w:delText back to w:t
|
||
var deletions = body.Descendants<DeletedRun>().ToList();
|
||
foreach (var del in deletions)
|
||
{
|
||
var parent = del.Parent;
|
||
if (parent == null) continue;
|
||
foreach (var run in del.Elements<Run>().ToList())
|
||
{
|
||
foreach (var delText in run.Elements<DeletedText>().ToList())
|
||
{
|
||
var text = new Text(delText.Text) { Space = delText.Space };
|
||
delText.InsertAfterSelf(text);
|
||
delText.Remove();
|
||
}
|
||
run.Remove();
|
||
parent.InsertBefore(run, del);
|
||
}
|
||
del.Remove();
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.12 MoveFrom / MoveTo — Tracked Text Moving
|
||
|
||
```csharp
|
||
// MoveFrom (w:moveFrom) marks the origin of moved text
|
||
// MoveTo (w:moveTo) marks the destination
|
||
// Both must have the same w:id
|
||
|
||
// <w:moveFrom w:id="14" w:author="Alice" w:date="...">
|
||
// <w:r><w:t>Text that was moved.</w:t></w:r>
|
||
// </w:moveFrom>
|
||
|
||
// At destination:
|
||
// <w:moveTo w:id="14" w:author="Alice" w:date="...">
|
||
// <w:r><w:t>Text that was moved.</w:t></w:r>
|
||
// </w:moveTo>
|
||
|
||
var movedFrom = new MoveFromRun(
|
||
new Run(new Text("Text that was moved.") { Space = SpaceProcessingModeValues.Preserve })
|
||
)
|
||
{
|
||
Author = "Alice",
|
||
Date = new DateTime(2026, 3, 22, 14, 0, 0, DateTimeKind.Utc),
|
||
Id = "14"
|
||
};
|
||
|
||
var movedTo = new MoveToRun(
|
||
new Run(new Text("Text that was moved.") { Space = SpaceProcessingModeValues.Preserve })
|
||
)
|
||
{
|
||
Author = "Alice",
|
||
Date = new DateTime(2026, 3, 22, 14, 0, 0, DateTimeKind.Utc),
|
||
Id = "14"
|
||
};
|
||
```
|
||
|
||
### 4.13 RevisionId Generation
|
||
|
||
All revision elements need unique, monotonically increasing integer IDs.
|
||
|
||
```csharp
|
||
public static int GetNextRevisionId(Body body)
|
||
{
|
||
int maxId = 0;
|
||
foreach (var elem in body.Descendants<OpenXmlElement>())
|
||
{
|
||
// Check common revision element types for Id attribute
|
||
var idAttr = elem.GetAttributes()
|
||
.FirstOrDefault(a => a.LocalName == "id" &&
|
||
(elem is InsertedRun or DeletedRun or DeletedText or
|
||
MoveFromRun or MoveToRun or RunPropertiesChange or
|
||
ParagraphPropertiesChange or SectionPropertiesChange or
|
||
TableRowInsertionRevision or TableCellInsertionRevision));
|
||
if (idAttr.Value != null && int.TryParse(idAttr.Value, out int id) && id > maxId)
|
||
maxId = id;
|
||
}
|
||
return maxId + 1;
|
||
}
|
||
|
||
// Simpler approach: scan all elements with "id" attribute in the document
|
||
public static int GetNextRevisionIdSimple(Body body)
|
||
{
|
||
int maxId = 0;
|
||
foreach (var elem in body.Descendants<OpenXmlElement>())
|
||
{
|
||
foreach (var attr in elem.GetAttributes())
|
||
{
|
||
if (attr.LocalName == "id" && int.TryParse(attr.Value, out int id) && id > maxId)
|
||
maxId = id;
|
||
}
|
||
}
|
||
return maxId + 1;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Comments (4-File System)
|
||
|
||
### 5.1 Full 4-File Comment System Setup
|
||
|
||
Comments require four XML files plus markers in `document.xml`.
|
||
|
||
```csharp
|
||
// This method creates a complete comment with all 4 files properly initialized
|
||
public static int AddFullComment(
|
||
WordprocessingDocument doc,
|
||
string text,
|
||
string author,
|
||
string initials,
|
||
string rangeText,
|
||
int? existingCommentId = null)
|
||
{
|
||
var mainPart = doc.MainDocumentPart
|
||
?? throw new InvalidOperationException("Document has no MainDocumentPart.");
|
||
|
||
int commentId = existingCommentId ?? GetNextCommentId(doc);
|
||
|
||
// Generate paraId (8-char hex) and durableId (8-digit hex)
|
||
string paraId = Guid.NewGuid().ToString("N")[..8].ToUpperInvariant();
|
||
string durableId = new Random().Next(0x10000000, 0xFFFFFFFF).ToString("X8");
|
||
|
||
var body = mainPart.Document!.Body!;
|
||
|
||
// ─────────────────────────────────────────────────────────────
|
||
// FILE 1: word/comments.xml — Main comment content
|
||
// ─────────────────────────────────────────────────────────────
|
||
var commentsPart = mainPart.WordprocessingCommentsPart
|
||
?? mainPart.AddNewPart<WordprocessingCommentsPart>();
|
||
|
||
if (commentsPart.Comments == null)
|
||
commentsPart.Comments = new Comments();
|
||
|
||
// Create a paragraph for the comment with a unique paraId (via w14:paraId)
|
||
var commentPara = new Paragraph(
|
||
new ParagraphProperties(
|
||
new ParagraphStyleId { Val = "CommentText" },
|
||
// w14:paraId for modern comment threading
|
||
new乳啜攠嘶嘐呓顾纨asiId { Val = paraId }
|
||
),
|
||
new Run(
|
||
new RunProperties(new RunStyle { Val = "CommentReference" }),
|
||
new AnnotationReferenceMark()
|
||
),
|
||
new Run(new Text(text))
|
||
);
|
||
|
||
var comment = new Comment
|
||
{
|
||
Id = commentId.ToString(),
|
||
Author = author,
|
||
Date = DateTime.UtcNow,
|
||
Initials = initials
|
||
};
|
||
comment.Append(commentPara);
|
||
commentsPart.Comments.Append(comment);
|
||
commentsPart.Comments.Save();
|
||
|
||
// ─────────────────────────────────────────────────────────────
|
||
// FILE 2: word/commentsExtended.xml — W15 extensions (paraId, done status)
|
||
// ─────────────────────────────────────────────────────────────
|
||
var commentsExPart = mainPart.WordprocessingCommentsExPart
|
||
?? mainPart.AddNewPart<WordprocessingCommentsExPart>();
|
||
|
||
if (commentsExPart.CommentsEx == null)
|
||
commentsExPart.CommentsEx = new CommentExCollection();
|
||
|
||
// w15:commentEx links the comment to its paragraph and tracks done/resolved
|
||
var commentEx = new CommentEx
|
||
{
|
||
ParaId = new HexBinaryValue(paraId),
|
||
Done = new OnOffValue(false) // done="0" = not resolved
|
||
};
|
||
commentsExPart.CommentsEx.Append(commentEx);
|
||
commentsExPart.CommentsEx.Save();
|
||
|
||
// ─────────────────────────────────────────────────────────────
|
||
// FILE 3: word/commentsIds.xml — Persistent ID mapping
|
||
// ─────────────────────────────────────────────────────────────
|
||
var commentsIdsPart = mainPart.WordprocessingCommentsIdsPart
|
||
?? mainPart.AddNewPart<WordprocessingCommentsIdsPart>();
|
||
|
||
if (commentsIdsPart.CommentsIds == null)
|
||
commentsIdsPart.CommentsIds = new CommentIds();
|
||
|
||
// w16cid:commentId maps paraId to a durable (globally unique) ID
|
||
var commentIdEntry = new CommentId
|
||
{
|
||
ParaId = new HexBinaryValue(paraId),
|
||
DurableId = durableId
|
||
};
|
||
commentsIdsPart.CommentsIds.Append(commentIdEntry);
|
||
commentsIdsPart.CommentsIds.Save();
|
||
|
||
// ─────────────────────────────────────────────────────────────
|
||
// FILE 4: word/commentsExtensible.xml — W16 extensible
|
||
// ─────────────────────────────────────────────────────────────
|
||
var commentsExtPart = mainPart.WordprocessingCommentsExtensiblePart
|
||
?? mainPart.AddNewPart<WordprocessingCommentsExtensiblePart>();
|
||
|
||
if (commentsExtPart.CommentsExtensible == null)
|
||
commentsExtPart.CommentsExtensible = new CommentExtensibleCollection();
|
||
|
||
// w16cex:commentExtensible provides the durable ID with UTC timestamp
|
||
var extensibleEntry = new CommentExtensible
|
||
{
|
||
DurableId = durableId,
|
||
DateUtc = DateTime.UtcNow
|
||
};
|
||
commentsExtPart.CommentsExtensible.Append(extensibleEntry);
|
||
commentsExtPart.CommentsExtensible.Save();
|
||
|
||
// ─────────────────────────────────────────────────────────────
|
||
// document.xml — Insert range markers around the target text
|
||
// ─────────────────────────────────────────────────────────────
|
||
// commentRangeStart and commentRangeEnd bracket the commented text
|
||
// commentReference is a run containing the visible superscript number
|
||
var rangeStart = new CommentRangeStart { Id = commentId.ToString() };
|
||
var rangeEnd = new CommentRangeEnd { Id = commentId.ToString() };
|
||
var refRun = new Run(
|
||
new RunProperties(new RunStyle { Val = "CommentReference" }),
|
||
new CommentReference { Id = commentId.ToString() }
|
||
);
|
||
|
||
// Find the paragraph containing rangeText and insert markers
|
||
// Simple approach: append at end of body
|
||
body.Append(rangeStart);
|
||
body.Append(new Paragraph(new Run(new Text(rangeText))));
|
||
body.Append(rangeEnd);
|
||
body.Append(new Paragraph(refRun)); // The comment ref must be in its own paragraph
|
||
|
||
return commentId;
|
||
}
|
||
|
||
// Helper: get next comment ID
|
||
private static int GetNextCommentId(WordprocessingDocument doc)
|
||
{
|
||
var commentsPart = doc.MainDocumentPart?.WordprocessingCommentsPart;
|
||
if (commentsPart?.Comments == null) return 1;
|
||
int max = 0;
|
||
foreach (var c in commentsPart.Comments.Elements<Comment>())
|
||
if (c.Id?.Value != null && int.TryParse(c.Id.Value, out int id) && id > max)
|
||
max = id;
|
||
return max + 1;
|
||
}
|
||
```
|
||
|
||
**The 4 files at a glance:**
|
||
|
||
| File | Part Class | Content | Key Attributes |
|
||
|------|-----------|---------|----------------|
|
||
| `comments.xml` | `WordprocessingCommentsPart` | Comment text | `w:id`, `w:author`, `w:date`, `w:initials` |
|
||
| `commentsExtended.xml` | `WordprocessingCommentsExPart` | W15 extensions | `w15:paraId`, `w15:done` |
|
||
| `commentsIds.xml` | `WordprocessingCommentsIdsPart` | Persistent IDs | `w16cid:paraId`, `w16cid:durableId` |
|
||
| `commentsExtensible.xml` | `WordprocessingCommentsExtensiblePart` | W16 extensible | `w16cex:durableId`, `w16cex:dateUtc` |
|
||
|
||
### 5.2 Comment Reply (Threaded Comments)
|
||
|
||
```csharp
|
||
// To add a reply, create a new comment and link it to the parent via commentsExtended.xml
|
||
|
||
public static int AddCommentReply(
|
||
WordprocessingDocument doc,
|
||
int parentCommentId,
|
||
string replyText,
|
||
string author,
|
||
string initials)
|
||
{
|
||
var mainPart = doc.MainDocumentPart!;
|
||
|
||
// Get parent's paraId from commentsExtended.xml
|
||
var commentsExPart = mainPart.WordprocessingCommentsExPart;
|
||
var parentParaId = "";
|
||
if (commentsExPart?.CommentsEx != null)
|
||
{
|
||
var parentCommentEx = commentsExPart.CommentsEx
|
||
.Elements<CommentEx>()
|
||
.FirstOrDefault(ce =>
|
||
ce.Parent is Comment c &&
|
||
c.Id?.Value == parentCommentId.ToString());
|
||
// Actually need to cross-reference through paraId...
|
||
// Simpler: look up via comments.xml paraId
|
||
}
|
||
|
||
// Generate new IDs for the reply
|
||
int replyId = GetNextCommentId(doc);
|
||
string replyParaId = Guid.NewGuid().ToString("N")[..8].ToUpperInvariant();
|
||
string durableId = new Random().Next(0x10000000, 0xFFFFFFFF).ToString("X8");
|
||
|
||
// Add to comments.xml (new comment with same structure)
|
||
var commentsPart = mainPart.WordprocessingCommentsPart!;
|
||
var replyComment = new Comment
|
||
{
|
||
Id = replyId.ToString(),
|
||
Author = author,
|
||
Date = DateTime.UtcNow,
|
||
Initials = initials
|
||
};
|
||
replyComment.Append(new Paragraph(
|
||
new ParagraphProperties(new ParagraphStyleId { Val = "CommentText" }),
|
||
new Run(new RunProperties(new RunStyle { Val = "CommentReference" }), new AnnotationReferenceMark()),
|
||
new Run(new Text(replyText))
|
||
));
|
||
commentsPart.Comments!.Append(replyComment);
|
||
commentsPart.Comments.Save();
|
||
|
||
// KEY: In commentsExtended.xml, use paraIdParent to link to parent
|
||
var commentsEx = mainPart.WordprocessingCommentsExPart!;
|
||
var replyEx = new CommentEx
|
||
{
|
||
ParaId = new HexBinaryValue(replyParaId),
|
||
ParaIdParent = new HexBinaryValue(parentParaId), // Link to parent
|
||
Done = new OnOffValue(false)
|
||
};
|
||
commentsEx.CommentsEx!.Append(replyEx);
|
||
commentsEx.CommentsEx.Save();
|
||
|
||
// Add to commentsIds.xml and commentsExtensible.xml (same pattern as parent)
|
||
// ... (same as AddFullComment for these two files)
|
||
|
||
// Note: Replies do NOT need range markers in document.xml
|
||
// They appear threaded under the parent in Word's UI
|
||
|
||
return replyId;
|
||
}
|
||
```
|
||
|
||
### 5.3 Resolving a Comment
|
||
|
||
```csharp
|
||
// To resolve (mark done), set w15:done="1" in commentsExtended.xml
|
||
public static void ResolveComment(WordprocessingDocument doc, int commentId)
|
||
{
|
||
var mainPart = doc.MainDocumentPart!;
|
||
|
||
// Need to find the paraId for this commentId, then update commentsExtended.xml
|
||
// Step 1: Get paraId from comments.xml
|
||
var commentsPart = mainPart.WordprocessingCommentsPart!;
|
||
var comment = commentsPart.Comments!
|
||
.Elements<Comment>()
|
||
.FirstOrDefault(c => c.Id?.Value == commentId.ToString());
|
||
|
||
// Find the paragraph and get its paraId
|
||
string? paraId = null;
|
||
if (comment != null)
|
||
{
|
||
var para = comment.Elements<Paragraph>().FirstOrDefault();
|
||
var paraIdElem = para?.ParagraphProperties?
|
||
.Elements<乳啜攠嘶嘐呓顾纨asiId>().FirstOrDefault();
|
||
paraId = paraIdElem?.Val?.Value;
|
||
}
|
||
|
||
if (paraId == null) return;
|
||
|
||
// Step 2: Update commentsExtended.xml
|
||
var commentsExPart = mainPart.WordprocessingCommentsExPart!;
|
||
var commentEx = commentsExPart.CommentsEx!
|
||
.Elements<CommentEx>()
|
||
.FirstOrDefault(ce => ce.ParaId?.Value == paraId);
|
||
|
||
if (commentEx != null)
|
||
commentEx.Done = new OnOffValue(true); // Sets done="1"
|
||
|
||
commentsExPart.CommentsEx!.Save();
|
||
}
|
||
```
|
||
|
||
### 5.4 Deleting a Comment (All 4 Files)
|
||
|
||
```csharp
|
||
// Must remove from all 4 files AND from document.xml
|
||
public static void DeleteComment(WordprocessingDocument doc, int commentId)
|
||
{
|
||
var mainPart = doc.MainDocumentPart!;
|
||
string commentIdStr = commentId.ToString();
|
||
|
||
// ── Remove from comments.xml ──
|
||
var commentsPart = mainPart.WordprocessingCommentsPart;
|
||
if (commentsPart?.Comments != null)
|
||
{
|
||
var comment = commentsPart.Comments
|
||
.Elements<Comment>()
|
||
.FirstOrDefault(c => c.Id?.Value == commentIdStr);
|
||
if (comment != null)
|
||
{
|
||
// Get paraId before deletion for other files
|
||
string? paraId = null;
|
||
var para = comment.Elements<Paragraph>().FirstOrDefault();
|
||
var paraIdElem = para?.ParagraphProperties?
|
||
.Elements<乳啜攠嘶嘐呓顾纨asiId>().FirstOrDefault();
|
||
paraId = paraIdElem?.Val?.Value;
|
||
|
||
comment.Remove();
|
||
|
||
// ── Remove from commentsExtended.xml ──
|
||
var commentsExPart = mainPart.WordprocessingCommentsExPart;
|
||
if (commentsExPart?.CommentsEx != null && paraId != null)
|
||
{
|
||
var commentEx = commentsExPart.CommentsEx
|
||
.Elements<CommentEx>()
|
||
.FirstOrDefault(ce => ce.ParaId?.Value == paraId);
|
||
commentEx?.Remove();
|
||
commentsExPart.CommentsEx.Save();
|
||
}
|
||
|
||
// ── Remove from commentsIds.xml ──
|
||
var commentsIdsPart = mainPart.WordprocessingCommentsIdsPart;
|
||
if (commentsIdsPart?.CommentsIds != null && paraId != null)
|
||
{
|
||
var cidEntry = commentsIdsPart.CommentsIds
|
||
.Elements<CommentId>()
|
||
.FirstOrDefault(ci => ci.ParaId?.Value == paraId);
|
||
cidEntry?.Remove();
|
||
commentsIdsPart.CommentsIds.Save();
|
||
}
|
||
|
||
// ── Remove from commentsExtensible.xml ──
|
||
// Need to look up by durableId...
|
||
var commentsExtPart = mainPart.WordprocessingCommentsExtensiblePart;
|
||
if (commentsExtPart?.CommentsExtensible != null)
|
||
{
|
||
// Find by matching durableId (must track separately)
|
||
var extEntry = commentsExtPart.CommentsExtensible
|
||
.Elements<CommentExtensible>()
|
||
.FirstOrDefault(); // Match by durableId lookup
|
||
extEntry?.Remove();
|
||
commentsExtPart.CommentsExtensible.Save();
|
||
}
|
||
}
|
||
}
|
||
|
||
// ── Remove from document.xml ──
|
||
var body = mainPart.Document!.Body!;
|
||
|
||
// Remove CommentRangeStart
|
||
var rangeStart = body.Descendants<CommentRangeStart>()
|
||
.FirstOrDefault(crs => crs.Id?.Value == commentIdStr);
|
||
rangeStart?.Remove();
|
||
|
||
// Remove CommentRangeEnd
|
||
var rangeEnd = body.Descendants<CommentRangeEnd>()
|
||
.FirstOrDefault(cre => cre.Id?.Value == commentIdStr);
|
||
rangeEnd?.Remove();
|
||
|
||
// Remove CommentReference run (the superscript marker)
|
||
var commentRefs = body.Descendants<CommentReference>()
|
||
.Where(cr => cr.Id?.Value == commentIdStr)
|
||
.ToList();
|
||
foreach (var cr in commentRefs)
|
||
{
|
||
var run = cr.Parent as Run;
|
||
cr.Remove();
|
||
run?.Remove();
|
||
}
|
||
|
||
commentsPart?.Comments?.Save();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Images — Deep Dive
|
||
|
||
### 6.1 Adding an ImagePart (All Image Types)
|
||
|
||
```csharp
|
||
// All image types supported by AddImagePart:
|
||
void AddImageExamples(MainDocumentPart mainPart, string pngPath, string jpegPath,
|
||
string gifPath, string svgPath, string bmpPath, string tiffPath)
|
||
{
|
||
// PNG
|
||
var pngPart = mainPart.AddImagePart(ImagePartType.Png);
|
||
using (var s = File.OpenRead(pngPath)) pngPart.FeedData(s);
|
||
string pngRelId = mainPart.GetIdOfPart(pngPart);
|
||
|
||
// JPEG
|
||
var jpegPart = mainPart.AddImagePart(ImagePartType.Jpeg);
|
||
using (var s = File.OpenRead(jpegPath)) jpegPart.FeedData(s);
|
||
string jpegRelId = mainPart.GetIdOfPart(jpegPart);
|
||
|
||
// GIF
|
||
var gifPart = mainPart.AddImagePart(ImagePartType.Gif);
|
||
using (var s = File.OpenRead(gifPath)) gifPart.FeedData(s);
|
||
string gifRelId = mainPart.GetIdOfPart(gifPart);
|
||
|
||
// SVG (may require additional handling for fallback)
|
||
var svgPart = mainPart.AddImagePart(ImagePartType.Svg);
|
||
using (var s = File.OpenRead(svgPath)) svgPart.FeedData(s);
|
||
string svgRelId = mainPart.GetIdOfPart(svgPart);
|
||
|
||
// BMP (stored internally as PNG in OOXML)
|
||
var bmpPart = mainPart.AddImagePart(ImagePartType.Bmp);
|
||
using (var s = File.OpenRead(bmpPath)) bmpPart.FeedData(s);
|
||
string bmpRelId = mainPart.GetIdOfPart(bmpPart);
|
||
|
||
// TIFF (similarly converted)
|
||
var tiffPart = mainPart.AddImagePart(ImagePartType.Tiff);
|
||
using (var s = File.OpenRead(tiffPath)) tiffPart.FeedData(s);
|
||
string tiffRelId = mainPart.GetIdOfPart(tiffPart);
|
||
|
||
// Also available: ImagePartType.Icon, ImagePartType.Emf, ImagePartType.Wmf
|
||
}
|
||
```
|
||
|
||
### 6.2 Inline Image (DW.Inline)
|
||
|
||
Inline images are anchored to a specific character position, not floating.
|
||
|
||
```csharp
|
||
// Dimensions: widthPx * 9525 EMU = EMU width, heightPx * 9525 EMU = EMU height
|
||
// Assuming 600x400 pixel image at 96dpi:
|
||
// cx = 600 * 9525 = 5715000 EMU
|
||
// cy = 400 * 9525 = 3810000 EMU
|
||
|
||
long cx = (long)(widthInches * 914400); // From inches to EMU
|
||
long cy = (long)(heightInches * 914400); // From inches to EMU
|
||
|
||
// Or from pixels at 96dpi:
|
||
long cxPx = 600, cyPx = 400;
|
||
long cx = cxPx * 9525L; // 5715000 EMU
|
||
long cy = cyPx * 9525L; // 3810000 EMU
|
||
|
||
// Drawing → DW.Inline → A.Graphic → A.GraphicData → PIC.Picture
|
||
var drawing = new Drawing(
|
||
new DW.Inline(
|
||
// Extent: defines the image's display size in EMU
|
||
new DW.Extent { Cx = cx, Cy = cy },
|
||
// EffectExtent: needed for some effects (set to 0 for basic images)
|
||
new DW.EffectExtent { EffectExtentL = 0, EffectExtentT = 0, EffectExtentR = 0, EffectExtentB = 0 },
|
||
// DocProperties: metadata for the image (Id must be unique in document)
|
||
new DW.DocProperties { Id = 1U, Name = "Image_1", Description = "A sample image" },
|
||
// NonVisualGraphicFrameDrawingProperties: locks and frame settings
|
||
new DW.NonVisualGraphicFrameDrawingProperties(
|
||
new A.GraphicFrameLocks { NoChangeAspect = true }
|
||
),
|
||
// The actual image
|
||
new A.Graphic(
|
||
new A.GraphicData(
|
||
new PIC.Picture(
|
||
// Non-visual properties
|
||
new PIC.NonVisualPictureProperties(
|
||
new PIC.NonVisualDrawingProperties { Id = 0U, Name = "image1" },
|
||
new PIC.NonVisualPictureDrawingProperties()
|
||
),
|
||
// Fill: how the image is stretched to fill its frame
|
||
new PIC.BlipFill(
|
||
// Blip: the actual image data reference
|
||
new A.Blip { Embed = relId, CompressionState = A.BlipCompressionValues.Print },
|
||
// Stretch: how to fill if aspect ratio doesn't match
|
||
new A.Stretch(new A.FillRectangle())
|
||
),
|
||
// ShapeProperties: transform and geometry
|
||
new PIC.ShapeProperties(
|
||
new A.Transform2D(
|
||
new A.Offset { X = 0L, Y = 0L },
|
||
new A.Extents { Cx = cx, Cy = cy }
|
||
),
|
||
new A.PresetGeometry(new A.AdjustValueList())
|
||
{ Preset = A.ShapeTypeValues.Rectangle }
|
||
)
|
||
)
|
||
) { Uri = "http://schemas.openxmlformats.org/drawingml/2006/picture" }
|
||
)
|
||
)
|
||
{
|
||
DistanceFromTop = 0U,
|
||
DistanceFromBottom = 0U,
|
||
DistanceFromLeft = 0U,
|
||
DistanceFromRight = 0U
|
||
}
|
||
);
|
||
|
||
// Append to a paragraph
|
||
var para = new Paragraph(new Run(drawing));
|
||
body.Append(para);
|
||
```
|
||
|
||
### 6.3 Floating / Anchored Image (DW.Anchor)
|
||
|
||
Floating images have text wrapping and can be positioned relative to page, margin, column, or paragraph.
|
||
|
||
```csharp
|
||
// DW.Anchor — positioned floating image with text wrapping
|
||
// Key differences from Inline:
|
||
// - DW.Anchor instead of DW.Inline
|
||
// - DW.PositionH / DW.PositionV for positioning
|
||
// - wrapping element (WrapSquare, WrapTight, etc.)
|
||
// - can have extent on the anchor (effect extent)
|
||
|
||
var floatingDrawing = new Drawing(
|
||
new DW.Anchor(
|
||
// Horizontal positioning
|
||
new DW.SimplePosition { X = 0L, Y = 0L }, // Offset from anchor point
|
||
new DW.HorizontalPosition(
|
||
new DW.PositionOffset((914400L * 2).ToString()) // 2 inches from left
|
||
)
|
||
{ RelativeFrom = DW.HorizontalRelativePositionValues.Page },
|
||
// Vertical positioning
|
||
new DW.VerticalPosition(
|
||
new DW.PositionOffset((914400L * 3).ToString()) // 3 inches from top
|
||
)
|
||
{ RelativeFrom = DW.VerticalRelativePositionValues.Page },
|
||
|
||
// Image extent (size)
|
||
new DW.Extent { Cx = cx, Cy = cy },
|
||
new DW.EffectExtent { EffectExtentL = 0, EffectExtentT = 0, EffectExtentR = 0, EffectExtentB = 0 },
|
||
|
||
new DW.DocProperties { Id = 2U, Name = "Floating_Image" },
|
||
new DW.NonVisualGraphicFrameDrawingProperties(
|
||
new A.GraphicFrameLocks { NoChangeAspect = true }
|
||
),
|
||
|
||
// Text wrapping — several options:
|
||
// WrapSquare: text wraps on all sides (default)
|
||
// WrapTight: text wraps close to image shape
|
||
// WrapThrough: text wraps through the image
|
||
// WrapTopAndBottom: image on its own line, text above and below
|
||
// WrapNone: image behind/in front of text
|
||
new DW.WrapSquare { WrapText = DW.WrapTextValues.RightMargin },
|
||
|
||
// Layout in table cell (if applicable)
|
||
new DW.DocPart Gallery { Val = DW.DocPartGalleryValues.Default },
|
||
|
||
// Change paragraph that the image is anchored to
|
||
// Allow the image to move with the paragraph
|
||
new DW.EditingIndependentFromParagraph { Val = false },
|
||
|
||
// Horizontal anchor: anchor to character/column/margin/page
|
||
new DW.HorizontalAnchor { Val = DW.HorizontalAnchorValues.Page },
|
||
// Vertical anchor: anchor to character/line/margin/page/paragraph
|
||
new DW.VerticalAnchor { Val = DW.VerticalAnchorValues.Page },
|
||
|
||
// Alignment (if using alignment-based positioning)
|
||
new DW.Aligned { Horizontal = DW.HorizontalAlignmentValues.Left,
|
||
Vertical = DW.VerticalAlignmentValues.Top },
|
||
|
||
new A.Graphic(...)
|
||
)
|
||
{
|
||
// Anchor lock: prevents moving in Word UI
|
||
EditId = "1A2B3C",
|
||
BehindDoc = false, // true = behind text, false = in front
|
||
Locked = false,
|
||
LayoutInCell = true, // Allow layout inside table cells
|
||
AllowOverlap = true // Allow overlap with other floating elements
|
||
}
|
||
);
|
||
```
|
||
|
||
### 6.4 Text Wrapping Options
|
||
|
||
```csharp
|
||
// WrapSquare — text surrounds on all sides
|
||
new DW.WrapSquare { WrapText = DW.WrapTextValues.RightMargin }
|
||
|
||
// WrapTight — text follows contour of image (if shape has custom geometry)
|
||
new DW.WrapTight { WrapText = DW.WrapTextValues.LeftMargin }
|
||
|
||
// WrapThrough — text intermingles with image
|
||
new DW.WrapThrough(
|
||
new DW.WrapTextValues.LeftMargin, // Text on left
|
||
new DW.WrapTextValues.RightMargin // Text on right
|
||
)
|
||
|
||
// WrapTopAndBottom — image on own line
|
||
new DW.WrapTopAndBottom()
|
||
|
||
// WrapNone — image is at anchor position, text overlays (or vice versa)
|
||
new DW.WrapNone()
|
||
|
||
// Behind document text:
|
||
var anchor = new DW.Anchor(...){ BehindDoc = true, Locked = false };
|
||
```
|
||
|
||
### 6.5 Image Sizing — EMU Calculations
|
||
|
||
```csharp
|
||
// EMU reference:
|
||
// 1 inch = 914400 EMU
|
||
// 1 cm = 360000 EMU
|
||
// 1 pixel at 96dpi = 9525 EMU
|
||
// 1 pixel at 72dpi = 635 EMU (point, not EMU)
|
||
|
||
public static class ImageSizing
|
||
{
|
||
// From pixel dimensions at given DPI
|
||
public static (long cx, long cy) FromPixels(int widthPx, int heightPx, int dpi = 96)
|
||
{
|
||
long emuPerPixel = 914400L / dpi; // ~9525 at 96dpi
|
||
return (widthPx * emuPerPixel, heightPx * emuPerPixel);
|
||
}
|
||
|
||
// From inches
|
||
public static (long cx, long cy) FromInches(double widthIn, double heightIn)
|
||
{
|
||
return ((long)(widthIn * 914400), (long)(heightIn * 914400));
|
||
}
|
||
|
||
// From centimeters
|
||
public static (long cx, long cy) FromCentimeters(double widthCm, double heightCm)
|
||
{
|
||
return ((long)(widthCm * 360000), (long)(heightCm * 360000));
|
||
}
|
||
|
||
// Maintain aspect ratio given a target width
|
||
public static (long cx, long cy) ScaleToWidth(long originalCx, long originalCy, long targetCx)
|
||
{
|
||
double ratio = (double)originalCy / originalCx;
|
||
return (targetCx, (long)(targetCx * ratio));
|
||
}
|
||
|
||
// Common photo sizes in inches: 4x6, 5x7, 8x10
|
||
public static (long cx, long cy) PhotoSize4x6()
|
||
=> FromInches(4, 6);
|
||
|
||
public static (long cx, long cy) PhotoSize5x7()
|
||
=> FromInches(5, 7);
|
||
|
||
public static (long cx, long cy) PhotoSize8x10()
|
||
=> FromInches(8, 10);
|
||
}
|
||
```
|
||
|
||
### 6.6 Image with Border
|
||
|
||
```csharp
|
||
// Add border to image via PIC.ShapeProperties → A.Outline
|
||
new PIC.ShapeProperties(
|
||
new A.Transform2D(
|
||
new A.Offset { X = 0L, Y = 0L },
|
||
new A.Extents { Cx = cx, Cy = cy }
|
||
),
|
||
new A.PresetGeometry(new A.AdjustValueList())
|
||
{ Preset = A.ShapeTypeValues.Rectangle },
|
||
// The border/outline
|
||
new A.Outline(
|
||
new A.SolidFill(new A.RgbColorModelHex { Val = "000000" }),
|
||
new A.PresetDash { Val = A.PresetLineDashValues.Solid }
|
||
)
|
||
{ Width = 12700 } // 12700 EMU = 1pt, so 25400 = 2pt
|
||
);
|
||
```
|
||
|
||
### 6.7 Image with Alt Text (DocProperties.Description)
|
||
|
||
```csharp
|
||
// Alt text is set via DocProperties.Description
|
||
// Also accessible via Picture's alternative text in Word UI
|
||
|
||
new DW.DocProperties
|
||
{
|
||
Id = 1U,
|
||
Name = "Chart showing growth",
|
||
Description = "Bar chart showing quarterly revenue growth from Q1 to Q4 2025"
|
||
// Title is also available but Description is what Word shows as alt text
|
||
};
|
||
|
||
// Also set via A.Descriptive (for some image types)
|
||
```
|
||
|
||
### 6.8 Image in Header / Footer
|
||
|
||
```csharp
|
||
// Images in headers/footers work the same as in body, just on the respective part
|
||
var headerPart = mainPart.AddNewPart<HeaderPart>();
|
||
|
||
// Logo in header
|
||
var logoDrawing = new Drawing(
|
||
new DW.Inline(
|
||
new DW.Extent { Cx = 914400L, Cy = 457200L }, // 1" x 0.5" logo
|
||
new DW.EffectExtent(),
|
||
new DW.DocProperties { Id = 1U, Name = "HeaderLogo" },
|
||
new DW.NonVisualGraphicFrameDrawingProperties(
|
||
new A.GraphicFrameLocks { NoChangeAspect = true }),
|
||
new A.Graphic(
|
||
new A.GraphicData(
|
||
new PIC.Picture(
|
||
new PIC.NonVisualPictureProperties(
|
||
new PIC.NonVisualDrawingProperties { Id = 0U, Name = "logo" },
|
||
new PIC.NonVisualPictureDrawingProperties()),
|
||
new PIC.BlipFill(
|
||
new A.Blip { Embed = headerLogoRelId },
|
||
new A.Stretch(new A.FillRectangle())),
|
||
new PIC.ShapeProperties(
|
||
new A.Transform2D(
|
||
new A.Offset { X = 0L, Y = 0L },
|
||
new A.Extents { Cx = 914400L, Cy = 457200L }),
|
||
new A.PresetGeometry(new A.AdjustValueList())
|
||
{ Preset = A.ShapeTypeValues.Rectangle }))
|
||
)
|
||
) { Uri = "http://schemas.openxmlformats.org/drawingml/2006/picture" }
|
||
)
|
||
)
|
||
{ DistanceFromTop = 0U, DistanceFromBottom = 0U,
|
||
DistanceFromLeft = 0U, DistanceFromRight = 0U }
|
||
);
|
||
|
||
headerPart.Header = new Header(
|
||
new Paragraph(
|
||
new ParagraphProperties(
|
||
new Justification { Val = JustificationValues.Right }),
|
||
new Run(logoDrawing)
|
||
)
|
||
);
|
||
```
|
||
|
||
### 6.9 Image in Table Cell
|
||
|
||
```csharp
|
||
// Images in table cells use the same patterns
|
||
// With inline: works fine within cell
|
||
// With floating/anchor: set LayoutInCell = true
|
||
|
||
var cellWithImage = new TableCell(
|
||
new TableCellProperties(
|
||
new TableCellWidth { Width = 2000, Type = TableWidthUnitValues.Dxa }
|
||
),
|
||
new Paragraph(
|
||
new Run(
|
||
new Drawing(
|
||
new DW.Inline(
|
||
new DW.Extent { Cx = 914400L, Cy = 914400L }, // 1"x1"
|
||
new DW.EffectExtent(),
|
||
new DW.DocProperties { Id = 5U, Name = "CellImage" },
|
||
new DW.NonVisualGraphicFrameDrawingProperties(
|
||
new A.GraphicFrameLocks { NoChangeAspect = true }),
|
||
new A.Graphic(
|
||
new A.GraphicData(
|
||
new PIC.Picture(...)
|
||
) { Uri = "..." }
|
||
)
|
||
)
|
||
{ DistanceFromTop = 0U, DistanceFromBottom = 0U,
|
||
DistanceFromLeft = 0U, DistanceFromRight = 0U }
|
||
)
|
||
)
|
||
)
|
||
);
|
||
```
|
||
|
||
### 6.10 Replacing an Image (Update Blip.Embed)
|
||
|
||
```csharp
|
||
// To replace an existing image, update the Blip's Embed relationship ID
|
||
// 1. Get the existing image's relationship ID from Blip.Embed
|
||
// 2. Replace the image data in that ImagePart with new data
|
||
// 3. Keep the same relationship ID (so all references remain valid)
|
||
|
||
public static void ReplaceImage(WordprocessingDocument doc, string newImagePath)
|
||
{
|
||
var mainPart = doc.MainDocumentPart!;
|
||
var body = mainPart.Document!.Body!;
|
||
|
||
foreach (var drawing in body.Descendants<Drawing>())
|
||
{
|
||
// Look for inline or anchor images
|
||
var inline = drawing.Descendants<DW.Inline>().FirstOrDefault();
|
||
var anchor = drawing.Descendants<DW.Anchor>().FirstOrDefault();
|
||
|
||
var blipFill = (inline ?? anchor as OpenXmlElement)?
|
||
.Descendants<PIC.BlipFill>().FirstOrDefault();
|
||
|
||
if (blipFill == null) continue;
|
||
|
||
var blip = blipFill.Blip;
|
||
if (blip?.Embed == null) continue;
|
||
|
||
string relId = blip.Embed.Value!;
|
||
|
||
// Get the existing ImagePart
|
||
if (mainPart.GetPartById(relId) is ImagePart existingImagePart)
|
||
{
|
||
// Replace the data
|
||
using (var newData = File.OpenRead(newImagePath))
|
||
existingImagePart.FeedData(newData);
|
||
return; // Replace first found, or loop for all
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.11 SVG with PNG Fallback (SvgBlip)
|
||
|
||
```csharp
|
||
// SVG images use SvgBlip for modern Word apps, with PNG fallback for older versions
|
||
// This is handled through the package structure — Word picks the best supported format
|
||
|
||
// SVG stored as ImagePartType.Svg, but rendered via BlipFill with extension:
|
||
// <a:blip xmlns:a="..." r:embed="rId...">
|
||
// <a:extLst>
|
||
// <a:ext uri="http://schemas.openxmlformats.org/drawingml/2006/svg">
|
||
// <asvg:svg xmlns:asvg="..."/> <!-- SVG-specific data -->
|
||
// </a:ext>
|
||
// </a:extLst>
|
||
// </a:blip>
|
||
|
||
var svgImagePart = mainPart.AddImagePart(ImagePartType.Svg);
|
||
using (var s = File.OpenRead("chart.svg")) svgImagePart.FeedData(s);
|
||
string svgRelId = mainPart.GetIdOfPart(svgImagePart);
|
||
|
||
// Word automatically handles SVG→PNG fallback in older versions
|
||
// No explicit fallback needed in code — the document format handles it
|
||
|
||
// Note: SvgBlip class in SDK 3.x provides direct support
|
||
new A.SvgBlip { Embed = svgRelId };
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Drawing Shapes (Non-Image)
|
||
|
||
### 7.1 WordprocessingShape — Basic Shapes (wsp)
|
||
|
||
WordprocessingShape uses the `wps` namespace for Word's built-in shape library.
|
||
|
||
```csharp
|
||
// Shapes require:
|
||
// - MainDocumentPart.AddNewPart<WordprocessingShapePart>() or
|
||
// - Embedded via DrawingML inside a Drawing element
|
||
// The most common approach is embedding shapes directly in a Drawing element
|
||
|
||
// Shapes in WordprocessingDrawing are placed like images (inline or anchored)
|
||
var shapeDrawing = new Drawing(
|
||
new DW.Inline(
|
||
new DW.Extent { Cx = 1714500L, Cy = 914400L }, // 1.875" x 1" rectangle
|
||
new DW.EffectExtent(),
|
||
new DW.DocProperties { Id = 10U, Name = "Rectangle 1" },
|
||
new DW.NonVisualGraphicFrameDrawingProperties(
|
||
new A.GraphicFrameLocks()),
|
||
// The shape itself
|
||
new A.Graphic(
|
||
new A.GraphicData(
|
||
// WordprocessingShape = wsp:wsp (rectangle, roundedRect, ellipse, etc.)
|
||
new WSP.WordprocessingShape(
|
||
// Non-visual properties
|
||
new WSP.NonVisualDrawingShapeProperties(
|
||
new A.ShapeLocks { NoChangeAspect = true }
|
||
),
|
||
// Shape properties (fill, outline, geometry)
|
||
new WSP.ShapeProperties(
|
||
new A.Transform2D(
|
||
new A.Offset { X = 0L, Y = 0L },
|
||
new A.Extents { Cx = 1714500L, Cy = 914400L }
|
||
),
|
||
// PresetGeometry determines the shape type
|
||
new A.PresetGeometry(new A.AdjustValueList())
|
||
{
|
||
Preset = A.ShapeTypeValues.Rectangle
|
||
// Other values: RoundedRectangle, Ellipse, Triangle, etc.
|
||
},
|
||
// Fill color (solid)
|
||
new A.SolidFill(
|
||
new A.RgbColorModelHex { Val = "4472C4" }
|
||
),
|
||
// Outline
|
||
new A.Outline(
|
||
new A.NoFill() // No outline
|
||
// Or: new A.SolidFill(new A.RgbColorModelHex { Val = "000000" })
|
||
// { Width = 12700 } for 1pt border
|
||
)
|
||
),
|
||
// Text box content
|
||
new WSP.TextBoxInfo2(
|
||
new TextBoxContent(
|
||
new Paragraph(
|
||
new ParagraphProperties(
|
||
new Justification { Val = JustificationValues.Center }),
|
||
new Run(
|
||
new RunProperties(
|
||
new Color { Val = "FFFFFF" },
|
||
new Bold()),
|
||
new Text("Hello World"))
|
||
)
|
||
)
|
||
)
|
||
)
|
||
) { Uri = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape" }
|
||
)
|
||
)
|
||
{ DistanceFromTop = 0U, DistanceFromBottom = 0U,
|
||
DistanceFromLeft = 0U, DistanceFromRight = 0U }
|
||
);
|
||
```
|
||
|
||
**Preset shape types (`A.ShapeTypeValues`):**
|
||
- `Rectangle`, `RoundedRectangle`, `Ellipse`, `Triangle`, `RightTriangle`
|
||
- `Parallelogram`, `Trapezoid`, `Pentagon`, `Hexagon`, `Octagon`
|
||
- `Star4`, `Star5`, `Star6`, `Star8`, `Star10`, `Star12`
|
||
- `Heart`, `ArrowRight`, `ArrowLeft`, `ArrowUp`, `ArrowDown`
|
||
- `Callout1`, `Callout2`, `Callout3` (with tail)
|
||
- `FlowChartProcess`, `FlowChartDecision`, `FlowChartDocument`
|
||
|
||
### 7.2 Shape with Gradient Fill
|
||
|
||
```csharp
|
||
new WSP.ShapeProperties(
|
||
new A.Transform2D(...),
|
||
new A.PresetGeometry(new A.AdjustValueList())
|
||
{ Preset = A.ShapeTypeValues.RoundedRectangle },
|
||
// Gradient fill
|
||
new A.GradientFill(
|
||
new A.LinearGradientFill(
|
||
new A.Stop { Offset = "0", Color = new A.RgbColorModelHex { Val = "4472C4" } },
|
||
new A.Stop { Offset = "100000", Color = new A.RgbColorModelHex { Val = "2F5496" } }
|
||
)
|
||
{ Rotation = 5400000 } // 54° = diagonal
|
||
)
|
||
// OR: A.RadialGradientFill for radial gradient
|
||
);
|
||
```
|
||
|
||
### 7.3 Shape Positioning (Anchored)
|
||
|
||
```csharp
|
||
// Anchored (floating) shapes use DW.Anchor with the shape inside
|
||
var anchoredShape = new Drawing(
|
||
new DW.Anchor(
|
||
new DW.SimplePosition { X = 0L, Y = 0L },
|
||
new DW.HorizontalPosition(
|
||
new DW.PositionOffset((914400L * 1).ToString())) // 1 inch from left
|
||
{ RelativeFrom = DW.HorizontalRelativePositionValues.Margin },
|
||
new DW.VerticalPosition(
|
||
new DW.PositionOffset((914400L * 2).ToString())) // 2 inches from top
|
||
{ RelativeFrom = DW.VerticalRelativePositionValues.Page },
|
||
new DW.Extent { Cx = 914400L, Cy = 914400L },
|
||
new DW.EffectExtent(),
|
||
new DW.DocProperties { Id = 11U, Name = "AnchoredShape" },
|
||
new DW.NonVisualGraphicFrameDrawingProperties(new A.GraphicFrameLocks()),
|
||
new DW.WrapSquare(),
|
||
new A.Graphic(new A.GraphicData(
|
||
new WSP.WordprocessingShape(...)
|
||
) { Uri = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape" })
|
||
)
|
||
{ BehindDoc = false, LayoutInCell = true }
|
||
);
|
||
```
|
||
|
||
### 7.4 Grouped Shapes (GroupShape)
|
||
|
||
```csharp
|
||
// GroupShape combines multiple shapes into one manipulable unit
|
||
// Uses a different URI: "http://schemas.microsoft.com/office/word/2010/wordprocessingGroupShape"
|
||
|
||
var groupShapeDrawing = new Drawing(
|
||
new DW.Inline(
|
||
new DW.Extent { Cx = 4572000L, Cy = 2286000L }, // 5" x 2.5"
|
||
new DW.EffectExtent(),
|
||
new DW.DocProperties { Id = 12U, Name = "Shape Group" },
|
||
new DW.NonVisualGraphicFrameDrawingProperties(new A.GraphicFrameLocks()),
|
||
new A.Graphic(
|
||
new A.GraphicData(
|
||
new WPG.GroupShape(
|
||
// Child shapes are positioned relative to group origin
|
||
// Shape 1 at (0,0)
|
||
new WSP.WordprocessingShape(
|
||
new WSP.NonVisualDrawingShapeProperties(
|
||
new A.ShapeLocks { NoChangeAspect = true }),
|
||
new WSP.ShapeProperties(
|
||
new A.Transform2D(
|
||
new A.Offset { X = 0L, Y = 0L },
|
||
new A.Extents { Cx = 914400L, Cy = 914400L }),
|
||
new A.PresetGeometry(new A.AdjustValueList())
|
||
{ Preset = A.ShapeTypeValues.Ellipse },
|
||
new A.SolidFill(new A.RgbColorModelHex { Val = "FF0000" })),
|
||
new WSP.TextBoxInfo2(
|
||
new TextBoxContent(new Paragraph(
|
||
new Run(new Text("Red Circle")))))
|
||
),
|
||
// Shape 2 offset to the right
|
||
new WSP.WordprocessingShape(
|
||
new WSP.NonVisualDrawingShapeProperties(
|
||
new A.ShapeLocks { NoChangeAspect = true }),
|
||
new WSP.ShapeProperties(
|
||
new A.Transform2D(
|
||
new A.Offset { X = 914400L, Y = 0L }, // 1" to the right
|
||
new A.Extents { Cx = 914400L, Cy = 914400L }),
|
||
new A.PresetGeometry(new A.AdjustValueList())
|
||
{ Preset = A.ShapeTypeValues.Rectangle },
|
||
new A.SolidFill(new A.RgbColorModelHex { Val = "00FF00" })),
|
||
new WSP.TextBoxInfo2(
|
||
new TextBoxContent(new Paragraph(
|
||
new Run(new Text("Green Square")))))
|
||
)
|
||
)
|
||
) { Uri = "http://schemas.microsoft.com/office/word/2010/wordprocessingGroupShape" }
|
||
)
|
||
)
|
||
{ DistanceFromTop = 0U, DistanceFromBottom = 0U,
|
||
DistanceFromLeft = 0U, DistanceFromRight = 0U }
|
||
);
|
||
```
|
||
|
||
### 7.5 Shape Effects — Shadow, Reflection
|
||
|
||
```csharp
|
||
// Shadow effect
|
||
new WSP.ShapeProperties(
|
||
new A.Transform2D(...),
|
||
new A.PresetGeometry(new A.AdjustValueList())
|
||
{ Preset = A.ShapeTypeValues.RoundedRectangle },
|
||
new A.SolidFill(new A.RgbColorModelHex { Val = "4472C4" }),
|
||
// Shadow via EffectList
|
||
new A.EffectList(
|
||
new A.OuterShadow(
|
||
new A.RgbColorModelHex { Val = "000000" }
|
||
)
|
||
{
|
||
BlurRadius = 50800L, // 4pt blur (50800 EMU = 4pt at 12700EMU/pt)
|
||
Distance = 38100L, // 3pt offset
|
||
Direction = 2700000, // 45° (in 60000ths of a degree)
|
||
Alignment = A.RectangleAlignmentValues.BottomRight
|
||
}
|
||
)
|
||
);
|
||
|
||
// Reflection
|
||
new A.EffectList(
|
||
new A.Reflection(
|
||
new A.ReflectionEffect()
|
||
{
|
||
ReflectionBlurRadius = 63500L, // 5pt
|
||
ReflectionDistance = 76200L, // 6pt
|
||
ReflectionFade = 50000, // 50% fade
|
||
ReflectionOverlap = 25000 // 25% overlap
|
||
}
|
||
)
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Math / Equations (OMML)
|
||
|
||
### 8.1 OfficeMath Container — Basic Setup
|
||
|
||
```csharp
|
||
// All math equations must be inside an OfficeMath container
|
||
// OfficeMath can be inline (in a run) or display (in its own paragraph)
|
||
|
||
// Inline equation in a run
|
||
var inlineMathPara = new Paragraph(
|
||
new Run(
|
||
new RunProperties(new RunFonts { Ascii = "Cambria Math", HighAnsi = "Cambria Math" }),
|
||
// Inline math: use OfficeMath directly in Run
|
||
new OfficeMath(
|
||
new M.Fraction(
|
||
new M.Numerator(
|
||
new M.Run(new M.Text("1"))
|
||
),
|
||
new M.Denominator(
|
||
new M.Run(new M.Text("2"))
|
||
)
|
||
)
|
||
)
|
||
)
|
||
);
|
||
|
||
// Display equation (on its own centered paragraph)
|
||
var displayMathPara = new Paragraph(
|
||
new ParagraphProperties(
|
||
new Justification { Val = JustificationValues.Center }
|
||
),
|
||
new Run(
|
||
new OfficeMath(
|
||
new M.Fraction(
|
||
new M.Numerator(
|
||
new M.Run(new M.Text("x"))
|
||
),
|
||
new M.Denominator(
|
||
new M.Run(new M.Text("y"))
|
||
)
|
||
)
|
||
)
|
||
)
|
||
);
|
||
|
||
// To make a display equation centered with extra spacing:
|
||
var displayEquationPara = new Paragraph(
|
||
new ParagraphProperties(
|
||
new SpacingBetweenLines { Before = "240", After = "240" },
|
||
new Justification { Val = JustificationValues.Center }
|
||
),
|
||
new Run(new OfficeMath(
|
||
// Equation content here
|
||
))
|
||
);
|
||
```
|
||
|
||
### 8.2 Fraction (M.Fraction)
|
||
|
||
```csharp
|
||
// \frac{x}{y} pattern
|
||
new M.Fraction(
|
||
new M.Numerator(
|
||
new M.Run(
|
||
new M.RunText("x") { Space = SpaceProcessingModeValues.Preserve }
|
||
)
|
||
),
|
||
new M.Denominator(
|
||
new M.Run(
|
||
new M.RunText("y") { Space = SpaceProcessingModeValues.Preserve }
|
||
)
|
||
)
|
||
);
|
||
|
||
// Nested fraction: (a+b)/(c+d)
|
||
new M.Fraction(
|
||
new M.Numerator(
|
||
new M.Run(new M.Text("a")) { FontSize = 24 },
|
||
new M.Run(new M.Text("+")) { FontSize = 24 },
|
||
new M.Run(new M.Text("b")) { FontSize = 24 }
|
||
),
|
||
new M.Denominator(
|
||
new M.Run(new M.Text("c")) { FontSize = 24 },
|
||
new M.Run(new M.Text("+")) { FontSize = 24 },
|
||
new M.Run(new M.Text("d")) { FontSize = 24 }
|
||
)
|
||
);
|
||
|
||
// Display fraction (skips 1 as numerator/denominator style)
|
||
new M.Fraction(
|
||
new M.Numerator(...),
|
||
new M.Denominator(...),
|
||
new M.FractionPr(
|
||
new M.Type { Val = M.FractionValues.Skewed } // or Normal, Linear,丝
|
||
)
|
||
);
|
||
```
|
||
|
||
### 8.3 Superscript and Subscript
|
||
|
||
```csharp
|
||
// Superscript: x²
|
||
new M.Superscript(
|
||
new M.Base(
|
||
new M.Run(new M.Text("x")))
|
||
),
|
||
new M.SuperscriptOperand(
|
||
new M.Run(new M.Text("2")))
|
||
)
|
||
);
|
||
|
||
// Subscript: x₁
|
||
new M.Subscript(
|
||
new M.Base(
|
||
new M.Run(new M.Text("x")))
|
||
),
|
||
new M.SubscriptOperand(
|
||
new M.Run(new M.Text("1")))
|
||
)
|
||
);
|
||
|
||
// Pre-sub/superscript: _b^a (baseline then super)
|
||
// or use M.SubscriptSuperscript for combined
|
||
|
||
// SubscriptSuperscript (both at once): _b^a C
|
||
new M.SubscriptSuperscript(
|
||
new M.Base(new M.Run(new M.Text("C"))),
|
||
new M.Subscript(new M.Run(new M.Text("b"))),
|
||
new M.Superscript(new M.Run(new M.Text("a")))
|
||
);
|
||
```
|
||
|
||
### 8.4 Square Root and Nth Root
|
||
|
||
```csharp
|
||
// Square root: √x
|
||
new M.Radical(
|
||
new M.Root(
|
||
new M.Run(new M.Text("x")))
|
||
)
|
||
);
|
||
|
||
// Square root with degree hidden (just √)
|
||
new M.Radical(
|
||
new M.Root(
|
||
new M.Run(new M.Text("x")))
|
||
),
|
||
new M.RadicalPr(
|
||
new M.Degree { Val = false } // Hide the root index
|
||
)
|
||
);
|
||
|
||
// Nth root: ∛(x+1) — cube root of (x+1)
|
||
new M.Radical(
|
||
new M.Root(
|
||
new M.Fraction(
|
||
new M.Numerator(new M.Run(new M.Text("1"))),
|
||
new M.Denominator(new M.Run(new M.Text("3")))
|
||
)
|
||
), // This is the "3" for cube root
|
||
new M.Root(
|
||
new M.Run(new M.Text("x"))),
|
||
new M.Run(new M.Text("+"))),
|
||
new M.Run(new M.Text("1")))
|
||
)
|
||
);
|
||
// Actually, for nth root: first Root is the index (degree), second is the radicand
|
||
new M.Radical(
|
||
new M.Root(new M.Run(new M.Text("3"))), // The index: 3rd root
|
||
new M.Root(
|
||
new M.Run(new M.Text("x")),
|
||
new M.Run(new M.Text("+")),
|
||
new M.Run(new M.Text("1"))
|
||
)
|
||
);
|
||
```
|
||
|
||
### 8.5 N-ary Operators — Integral, Summation, Product
|
||
|
||
```csharp
|
||
// Integral ∫ from a to b of f(x) dx
|
||
new M.Nary(
|
||
new M.NaryProperties(
|
||
new M.NaryType { Val = M.NaryValues.Integral } // ∫
|
||
)
|
||
{
|
||
SubSuperscript = M.SubSuperscriptValues.NoSubSuperscript
|
||
},
|
||
new M.Base(
|
||
new M.Run(new M.Text("f(x)")))
|
||
),
|
||
new M.Subscript(
|
||
new M.Run(new M.Text("a")))
|
||
),
|
||
new M.Superscript(
|
||
new M.Run(new M.Text("b")))
|
||
)
|
||
);
|
||
|
||
// Summation Σ from i=1 to n of i²
|
||
new M.Nary(
|
||
new M.NaryProperties(
|
||
new M.NaryType { Val = M.NaryValues.Sum }, // Σ
|
||
new M.GrowBindings = true
|
||
),
|
||
new M.Base(
|
||
new M.SubscriptSuperscript(
|
||
new M.Base(new M.Run(new M.Text("i"))),
|
||
new M.Subscript(new M.Run(new M.Text("1"))),
|
||
new M.Superscript(new M.Run(new M.Text("n")))
|
||
)
|
||
),
|
||
new M.Subscript(
|
||
new M.Run(new M.Text("i")))
|
||
),
|
||
new M.Superscript(
|
||
new M.Run(new M.Text("2")))
|
||
)
|
||
);
|
||
|
||
// Product ∏ from i=1 to n
|
||
new M.Nary(
|
||
new M.NaryProperties(
|
||
new M.NaryType { Val = M.NaryValues.Product } // ∏
|
||
),
|
||
new M.Base(
|
||
new M.SubscriptSuperscript(
|
||
new M.Base(new M.Run(new M.Text("i"))),
|
||
new M.Subscript(new M.Run(new M.Text("1"))),
|
||
new M.Superscript(new M.Run(new M.Text("n")))
|
||
)
|
||
),
|
||
new M.Subscript(
|
||
new M.Run(new M.Text("i")))
|
||
),
|
||
new M.Superscript(
|
||
new M.Run(new M.Text("2")))
|
||
)
|
||
);
|
||
|
||
// N-ary type values: Integral, Sum, Product, Union, Intersection, etc.
|
||
```
|
||
|
||
### 8.6 Matrix
|
||
|
||
```csharp
|
||
// 2x2 matrix
|
||
// [a b]
|
||
// [c d]
|
||
new M.Matrix(
|
||
new M.MatrixRows(
|
||
// Row 1
|
||
new M.MatrixRow(
|
||
new M.MatrixCell(
|
||
new M.Run(new M.Text("a"))
|
||
),
|
||
new M.MatrixCell(
|
||
new M.Run(new M.Text("b"))
|
||
)
|
||
),
|
||
// Row 2
|
||
new M.MatrixRow(
|
||
new M.MatrixCell(
|
||
new M.Run(new M.Text("c"))
|
||
),
|
||
new M.MatrixCell(
|
||
new M.Run(new M.Text("d"))
|
||
)
|
||
)
|
||
),
|
||
new M.MatrixProperties(
|
||
new M.Jc { Val = M.JustificationValues.Center }, // Centered
|
||
new M.Structure { Val = M.MathStructureValues.SinglePUNCT },
|
||
new M.RowSpacing { Val = 120 }, // Row spacing in twips
|
||
new M.RowSpacing1 { Val = 120 }
|
||
)
|
||
)
|
||
```
|
||
|
||
### 8.7 Delimiter (Parentheses/Brackets/Braces)
|
||
|
||
```csharp
|
||
// (a + b) or [a + b] or {a + b}
|
||
new M.Delimiter(
|
||
new M.DelimiterProperties(
|
||
new M.Begin(new M.Text("(")), // Opening char
|
||
new M.End(new M.Text(")")), // Closing char
|
||
new M.Separator(new M.Text(",")), // Separator between elements
|
||
new M.Structure { Val = M.MathStructureValues.Minimal }
|
||
),
|
||
new M.DelimiterContents(
|
||
new M.Run(new M.Text("a")),
|
||
new M.Run(new M.Text("+")),
|
||
new M.Run(new M.Text("b"))
|
||
)
|
||
);
|
||
|
||
// {a, b, c} with curly braces
|
||
new M.Delimiter(
|
||
new M.DelimiterProperties(
|
||
new M.Begin(new M.Text("{")),
|
||
new M.End(new M.Text("}")),
|
||
new M.Separator(new M.Text(","))
|
||
),
|
||
new M.DelimiterContents(
|
||
new M.Run(new M.Text("a")),
|
||
new M.Run(new M.Text("b")),
|
||
new M.Run(new M.Text("c"))
|
||
)
|
||
);
|
||
|
||
// 2x2 matrix in parentheses
|
||
new M.Delimiter(
|
||
new M.DelimiterProperties(
|
||
new M.Begin(new M.Text("(")),
|
||
new M.End(new M.Text(")"))
|
||
),
|
||
new M.DelimiterContents(
|
||
// Inline 2x2 using subscripts
|
||
new M.SubscriptSuperscript(...)
|
||
)
|
||
);
|
||
```
|
||
|
||
### 8.8 Equation Array (Aligned Equations)
|
||
|
||
```csharp
|
||
// EquationArray (M.EquationArray) creates a series of equations aligned at markers
|
||
// Like \begin{align} in LaTeX
|
||
|
||
new M.EquationArray(
|
||
new M.EquationArrayProperties(
|
||
new M.Jc { Val = M.JustificationValues.Left },
|
||
new M.RowSpacing { Val = 240 },
|
||
new M.RowSpacing1 { Val = 240 }
|
||
),
|
||
// Each equation is a Paragraph inside the array
|
||
new Paragraph(new Run(new M.Text("x") { Space = SpaceProcessingModeValues.Preserve })),
|
||
new Paragraph(
|
||
new Run(new M.Text("+") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new M.Text("y") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new M.Text("=") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new Run(new M.Text("z") { Space = SpaceProcessingModeValues.Preserve })
|
||
)
|
||
);
|
||
|
||
// Or use M.Break with AlignmentTab for manual alignment points
|
||
```
|
||
|
||
### 8.9 Greek Letters and Math Symbols
|
||
|
||
```csharp
|
||
// Greek letters via M.RunText with Symbol font or Unicode
|
||
// Common Greek letters and their uses:
|
||
|
||
// α (alpha)
|
||
new M.Run(new M.Text("\u03B1")) // or use Unicode directly
|
||
|
||
// β (beta)
|
||
new M.Run(new M.Text("\u03B2"))
|
||
|
||
// γ (gamma)
|
||
new M.Run(new M.Text("\u03B3"))
|
||
|
||
// π (pi) — use Greek small letter pi
|
||
new M.Run(new M.Text("\u03C0"))
|
||
|
||
// σ (sigma)
|
||
new M.Run(new M.Text("\u03C3"))
|
||
|
||
// Σ (Sigma, capital) — summation symbol
|
||
new M.Run(new M.Text("\u03A3"))
|
||
|
||
// θ (theta)
|
||
new M.Run(new M.Text("\u03B8"))
|
||
|
||
// ∞ (infinity)
|
||
new M.Run(new M.Text("\u221E"))
|
||
|
||
// ≤ (less than or equal)
|
||
new M.Run(new M.Text("\u2264"))
|
||
|
||
// ≥ (greater than or equal)
|
||
new M.Run(new M.Text("\u2265"))
|
||
|
||
// ≠ (not equal)
|
||
new M.Run(new M.Text("\u2260"))
|
||
|
||
// ± (plus-minus)
|
||
new M.Run(new M.Text("\u00B1"))
|
||
|
||
// × (multiplication)
|
||
new M.Run(new M.Text("\u00D7"))
|
||
|
||
// ÷ (division)
|
||
new M.Run(new M.Text("\u00F7"))
|
||
|
||
// For best results, set the font to "Cambria Math" on math runs
|
||
new M.Run(
|
||
new RunFonts { Ascii = "Cambria Math", HighAnsi = "Cambria Math" },
|
||
new M.Text("\u03C0")
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Numbering System — Deep Dive
|
||
|
||
### 9.1 Architecture Overview
|
||
|
||
```
|
||
NumberingDefinitionsPart (numbering.xml)
|
||
└── <w:numbering>
|
||
├── <w:abstractNum> (templates)
|
||
│ ├── <w:lvl> × 9 (levels 0-8)
|
||
│ └── <w:pPr><w:numPr> links to this abstractNum
|
||
└── <w:num> (instances)
|
||
└── <w:abstractNumId val="N"/>
|
||
```
|
||
|
||
**Key rule**: `AbstractNum` must appear BEFORE `NumberingInstance` in the XML root.
|
||
|
||
### 9.2 AbstractNum with Multi-Level Decimal Numbering
|
||
|
||
```csharp
|
||
// AbstractNum: the numbering template (what it looks like)
|
||
// NumberingInstance: a specific use of that template (how it's applied)
|
||
|
||
var numberingPart = mainPart.AddNewPart<NumberingDefinitionsPart>();
|
||
var numbering = new Numbering();
|
||
|
||
// ─────────────────────────────────────────────────────────────
|
||
// Step 1: Define AbstractNum (the template)
|
||
// ─────────────────────────────────────────────────────────────
|
||
var abstractNum = new AbstractNum { AbstractNumberId = 1 };
|
||
// MultiLevelType specifies this is a multi-level list
|
||
abstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
|
||
|
||
// Level 0: "1." — decimal, bold number
|
||
abstractNum.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||
new LevelText { Val = "%1." },
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "360", Hanging = "360" } // 0.25" hanging indent
|
||
),
|
||
new NumberingSymbolRunProperties(
|
||
new Bold(),
|
||
new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
|
||
new Color { Val = "2F5496" }
|
||
)
|
||
) { LevelIndex = 0 });
|
||
|
||
// Level 1: "1.1." — indent 0.5"
|
||
abstractNum.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||
new LevelText { Val = "%1.%2." },
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "720", Hanging = "360" }
|
||
),
|
||
new NumberingSymbolRunProperties(
|
||
new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
|
||
)
|
||
) { LevelIndex = 1 });
|
||
|
||
// Level 2: "1.1.1."
|
||
abstractNum.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||
new LevelText { Val = "%1.%2.%3." },
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "1080", Hanging = "360" }
|
||
),
|
||
new NumberingSymbolRunProperties(
|
||
new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
|
||
)
|
||
) { LevelIndex = 2 });
|
||
|
||
// ─────────────────────────────────────────────────────────────
|
||
// Step 2: Create NumberingInstance (a reference to the template)
|
||
// ─────────────────────────────────────────────────────────────
|
||
var numInstance = new NumberingInstance(
|
||
new AbstractNumId { Val = 1 } // Points to abstractNum above
|
||
) { NumberID = 1 };
|
||
|
||
// ─────────────────────────────────────────────────────────────
|
||
// Step 3: Assemble — AbstractNum BEFORE NumberingInstance!
|
||
// ─────────────────────────────────────────────────────────────
|
||
numbering.Append(abstractNum);
|
||
numbering.Append(numInstance);
|
||
numberingPart.Numbering = numbering;
|
||
numberingPart.Numbering.Save();
|
||
|
||
// ─────────────────────────────────────────────────────────────
|
||
// Step 4: Apply to a paragraph
|
||
// ─────────────────────────────────────────────────────────────
|
||
var numberedPara = new Paragraph(
|
||
new ParagraphProperties(
|
||
new NumberingProperties(
|
||
new NumberingLevelReference { Val = 0 }, // Use level 0 of numId 1
|
||
new NumberingId { Val = 1 } // Use numbering instance 1
|
||
)
|
||
),
|
||
new Run(new Text("First item"))
|
||
);
|
||
|
||
// For level 1 sub-item:
|
||
var subItemPara = new Paragraph(
|
||
new ParagraphProperties(
|
||
new NumberingProperties(
|
||
new NumberingLevelReference { Val = 1 }, // Use level 1
|
||
new NumberingId { Val = 1 }
|
||
)
|
||
),
|
||
new Run(new Text("Sub-item"))
|
||
);
|
||
```
|
||
|
||
### 9.3 Bullet Lists with Custom Symbols
|
||
|
||
```csharp
|
||
// Bullet numbering uses NumberFormatValues.Bullet
|
||
// The bullet character is defined in LevelText and NumberingSymbolRunProperties
|
||
|
||
var bulletAbstractNum = new AbstractNum { AbstractNumberId = 2 };
|
||
bulletAbstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
|
||
|
||
// Level 0 bullet: ● (Unicode bullet)
|
||
bulletAbstractNum.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.Bullet }, // Key: Bullet format
|
||
new LevelText { Val = "\u2022" }, // ● bullet character
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "720", Hanging = "360" }
|
||
),
|
||
new NumberingSymbolRunProperties(
|
||
new RunFonts { Ascii = "Symbol", HighAnsi = "Symbol" }
|
||
// Symbol font maps ● to character 0xD8 in Symbol encoding
|
||
)
|
||
) { LevelIndex = 0 });
|
||
|
||
// Level 1 bullet: ○ (white circle)
|
||
bulletAbstractNum.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.Bullet },
|
||
new LevelText { Val = "\u25CB" }, // ○ Unicode
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "1080", Hanging = "360" }
|
||
),
|
||
new NumberingSymbolRunProperties(
|
||
new RunFonts { Ascii = "Courier New", HighAnsi = "Courier New" }
|
||
)
|
||
) { LevelIndex = 1 });
|
||
|
||
// Level 2 bullet: ■ (black square)
|
||
bulletAbstractNum.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.Bullet },
|
||
new LevelText { Val = "\u25A0" }, // ■
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "1440", Hanging = "360" }
|
||
),
|
||
new NumberingSymbolRunProperties(
|
||
new RunFonts { Ascii = "Arial", HighAnsi = "Arial" }
|
||
)
|
||
) { LevelIndex = 2 });
|
||
|
||
var bulletNumInstance = new NumberingInstance(
|
||
new AbstractNumId { Val = 2 }
|
||
) { NumberID = 2 };
|
||
|
||
numbering.Append(bulletAbstractNum);
|
||
numbering.Append(bulletNumInstance);
|
||
```
|
||
|
||
**Common bullet characters:**
|
||
|
||
| Symbol | Character | Unicode | Common Font |
|
||
|--------|-----------|---------|-------------|
|
||
| ● Filled circle | Bullet | U+2022 | Symbol |
|
||
| ○ Empty circle | White circle | U+25CB | Arial |
|
||
| ■ Filled square | Black square | U+25A0 | Arial |
|
||
| □ Empty square | White square | U+25A1 | Arial |
|
||
| ➢ Right arrow | Right arrow | U+27A2 | Wingdings |
|
||
| ✓ Checkmark | Check mark | U+2713 | Wingdings |
|
||
| ✗ Cross | Ballot X | U+2717 | Wingdings |
|
||
| ▶ Play | Right triangle | U+25B6 | Arial |
|
||
|
||
### 9.4 Restart Numbering at Specific Point
|
||
|
||
```csharp
|
||
// Method 1: StartOverride on a specific paragraph
|
||
// Use LevelOverride + StartOverride to restart at a specific level
|
||
|
||
var restartNumInstance = new NumberingInstance(
|
||
new AbstractNumId { Val = 1 }
|
||
) { NumberID = 3 };
|
||
|
||
// Override level 0 to start at 5 instead of 1
|
||
restartNumInstance.Append(new LevelOverride { LevelIndex = 0 },
|
||
new StartOverrideNumberingValue { Val = 5 }
|
||
);
|
||
|
||
// Apply this to a paragraph — this paragraph starts numbering at 5
|
||
var restartPara = new Paragraph(
|
||
new ParagraphProperties(
|
||
new NumberingProperties(
|
||
new NumberingLevelReference { Val = 0 },
|
||
new NumberingId { Val = 3 } // Use the restart instance
|
||
)
|
||
),
|
||
new Run(new Text("Item 5 (restarted)"))
|
||
);
|
||
```
|
||
|
||
### 9.5 Continue Numbering from Previous List
|
||
|
||
```csharp
|
||
// By default, Word continues numbering across lists using the same AbstractNum.
|
||
// To force continuation, ensure the list uses the same numId.
|
||
|
||
// If you need explicit continuation control:
|
||
var continuedNumInstance = new NumberingInstance(
|
||
new AbstractNumId { Val = 1 }
|
||
) { NumberID = 4 };
|
||
|
||
// When multiple NumberingInstances share the same AbstractNumId,
|
||
// they share the same numbering state (continuation)
|
||
|
||
// To prevent continuation (start fresh), use a new AbstractNum:
|
||
var freshAbstractNum = new AbstractNum { AbstractNumberId = 5 };
|
||
freshAbstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
|
||
// ... define levels ...
|
||
var freshNumInstance = new NumberingInstance(
|
||
new AbstractNumId { Val = 5 }
|
||
) { NumberID = 5 };
|
||
// This starts at 1 again, independent of the previous list
|
||
```
|
||
|
||
### 9.6 Link Numbering to Heading Styles (Outline Numbering)
|
||
|
||
```句话说，link numbering to heading styles so that Heading1 starts a new numbering sequence, Heading2 is a sub-item, etc.
|
||
|
||
```csharp
|
||
// This links styles to numbering levels automatically via StyleLink
|
||
var abstractNumForOutline = new AbstractNum { AbstractNumberId = 10 };
|
||
abstractNumForOutline.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
|
||
abstractNumForOutline.Append(new StyleLink { Val = "Heading1" }); // Links level 0 to Heading1
|
||
abstractNumForOutline.Append(new StyleLink { Val = "Heading2" }); // Links level 1 to Heading2
|
||
abstractNumForOutline.Append(new StyleLink { Val = "Heading3" }); // Links level 2 to Heading3
|
||
|
||
// Level 0 for Heading1
|
||
abstractNumForOutline.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||
new LevelText { Val = "Chapter %1" },
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "360", Hanging = "360" }
|
||
),
|
||
new NumberingSymbolRunProperties(
|
||
new Bold(),
|
||
new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
|
||
new FontSize { Val = "28" }
|
||
)
|
||
) { LevelIndex = 0 });
|
||
|
||
// Level 1 for Heading2
|
||
abstractNumForOutline.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||
new LevelText { Val = "%1.%2" },
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "720", Hanging = "360" }
|
||
),
|
||
new NumberingSymbolRunProperties(
|
||
new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
|
||
)
|
||
) { LevelIndex = 1 });
|
||
|
||
// Level 2 for Heading3
|
||
abstractNumForOutline.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||
new LevelText { Val = "%1.%2.%3" },
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "1080", Hanging = "360" }
|
||
),
|
||
new NumberingSymbolRunProperties(
|
||
new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
|
||
)
|
||
) { LevelIndex = 2 });
|
||
|
||
// Now when you apply Heading1/2/3 styles, numbering follows automatically
|
||
var heading1Para = new Paragraph(
|
||
new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
|
||
new Run(new Text("Introduction")) // Automatically gets "Chapter 1" prefix
|
||
);
|
||
var heading2Para = new Paragraph(
|
||
new ParagraphProperties(new ParagraphStyleId { Val = "Heading2" }),
|
||
new Run(new Text("Background")) // Automatically gets "1.1" prefix
|
||
);
|
||
```
|
||
|
||
### 9.7 NumberingFormat Values Reference
|
||
|
||
```csharp
|
||
// NumberFormatValues enum — all supported numbering formats:
|
||
NumberFormatValues.Decimal // 1, 2, 3...
|
||
NumberFormatValues.LowerRoman // i, ii, iii...
|
||
NumberFormatValues.UpperRoman // I, II, III...
|
||
NumberFormatValues.LowerLetter // a, b, c...
|
||
NumberFormatValues.UpperLetter // A, B, C...
|
||
NumberFormatValues.Ordinal // 1st, 2nd, 3rd... (locale-dependent)
|
||
NumberFormatValues.OrdinalText // First, Second, Third... (locale-dependent)
|
||
NumberFormatValues.Hex // 0, 1, 2... F, 10, 11... (hexadecimal)
|
||
NumberFormatValues.ChicagoManual // Chapter numbering (I, A, 1, a)
|
||
NumberFormatValues.Kanji // 漢数字
|
||
NumberFormatValues.KanjiDigit // 一, 二, 三...
|
||
NumberFormatValues.DoubleByte // Ideographic: 一, 二, 三
|
||
NumberFormatValues.ArabicFullWidth // Full-width: １, ２, ３
|
||
NumberFormatValues.Bullet // Custom symbol (●, ✓, etc.)
|
||
NumberFormatValues.None // No number
|
||
```
|
||
|
||
### 9.8 IsLegalNumberingStyle — Using Arabic with Nested Levels
|
||
|
||
```csharp
|
||
// IsLegalNumberingStyle=false (default): each level can have its own format
|
||
// IsLegalNumberingStyle=true: forces all sub-levels to use Arabic numerals
|
||
|
||
// This is important for legal/formal numbering where you want:
|
||
// 1. level 1 = A, B, C (alphabetic)
|
||
// 2. level 2 = 1, 2, 3 (Arabic) — NOT a, b, c
|
||
// Without IsLegalNumberingStyle=false, level 2 would inherit alphabetic
|
||
|
||
var legalAbstractNum = new AbstractNum { AbstractNumberId = 20 };
|
||
legalAbstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
|
||
legalAbstractNum.Append(new IsLegalNumberingStyle()); // No val = true (default when element present)
|
||
|
||
// Level 0: A. B. C.
|
||
legalAbstractNum.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.UpperLetter },
|
||
new LevelText { Val = "%1." },
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "360", Hanging = "360" }
|
||
)
|
||
) { LevelIndex = 0 });
|
||
|
||
// Level 1: 1. 2. 3. (NOT a. b. c.)
|
||
legalAbstractNum.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||
new LevelText { Val = "%2." },
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "720", Hanging = "360" }
|
||
)
|
||
) { LevelIndex = 1 });
|
||
|
||
// Level 2: (a) (b) (c)
|
||
legalAbstractNum.Append(new Level(
|
||
new StartNumberingValue { Val = 1 },
|
||
new NumberingFormat { Val = NumberFormatValues.LowerLetter },
|
||
new LevelText { Val = "(%3)" },
|
||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||
new ParagraphProperties(
|
||
new Indentation { Left = "1080", Hanging = "360" }
|
||
)
|
||
) { LevelIndex = 2 });
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Document Protection & Encryption
|
||
|
||
### 10.1 DocumentProtection — Basic Forms
|
||
|
||
```csharp
|
||
// DocumentProtection is placed in DocumentSettingsPart
|
||
var settingsPart = mainPart.AddNewPart<DocumentSettingsPart>();
|
||
settingsPart.Settings = new Settings();
|
||
|
||
// ReadOnly: prevents editing, allows reading
|
||
settingsPart.Settings.Append(new DocumentProtection
|
||
{
|
||
Edit = DocumentProtectionValues.ReadOnly,
|
||
Enforcement = true
|
||
});
|
||
|
||
// Comments: can only add/edit comments (not modify body text)
|
||
settingsPart.Settings.Append(new DocumentProtection
|
||
{
|
||
Edit = DocumentProtectionValues.Comments,
|
||
Enforcement = true
|
||
});
|
||
|
||
// TrackedChanges: can only edit with track changes ON
|
||
settingsPart.Settings.Append(new DocumentProtection
|
||
{
|
||
Edit = DocumentProtectionValues.TrackedChanges,
|
||
Enforcement = true
|
||
});
|
||
|
||
// Forms: only form fields are editable
|
||
settingsPart.Settings.Append(new DocumentProtection
|
||
{
|
||
Edit = DocumentProtectionValues.Forms,
|
||
Enforcement = true
|
||
});
|
||
```
|
||
|
||
### 10.2 Password Hashing for DocumentProtection
|
||
|
||
Modern Word uses SHA-512 with salt for password hashing (ECMA-376 standard).
|
||
|
||
```csharp
|
||
// SHA-512 password hashing for strong protection
|
||
// CryptographicProviderType must be "rsaAES" or "rsaAES" for SHA-512
|
||
|
||
settingsPart.Settings.Append(new DocumentProtection
|
||
{
|
||
Edit = DocumentProtectionValues.ReadOnly,
|
||
Enforcement = true,
|
||
CryptographicProviderType = CryptProviderValues.RsaAES,
|
||
CryptographicAlgorithmClass = CryptAlgorithmClassValues.Hash,
|
||
CryptographicAlgorithmType = CryptAlgorithmValues.TypeAny,
|
||
CryptographicAlgorithmSid = 14, // SHA-512
|
||
CryptographicSpinCount = 100000U,
|
||
Hash = "base64-encoded-hash-here",
|
||
Salt = "base64-encoded-salt-here"
|
||
});
|
||
|
||
// Generate hash in .NET:
|
||
public static (string hash, string salt) GeneratePasswordHash(string password, int spinCount = 100000)
|
||
{
|
||
byte[] saltBytes = new byte[16];
|
||
using (var rng = System.Security.Cryptography.RandomNumberGenerator.Create())
|
||
rng.GetBytes(saltBytes);
|
||
|
||
// PBKDF2 with SHA-512, 100000 iterations
|
||
using var pbkdf2 = new System.Security.Cryptography.Rfc2898DeriveBytes(
|
||
password, saltBytes, spinCount, System.Security.Cryptography.HashAlgorithmName.SHA512);
|
||
byte[] hash = pbkdf2.GetBytes(64); // 512 bits
|
||
|
||
return (Convert.ToBase64String(hash), Convert.ToBase64String(saltBytes));
|
||
}
|
||
```
|
||
|
||
### 10.3 WriteProtection — Recommend Opening as Read-Only
|
||
|
||
```csharp
|
||
// WriteProtection is different from DocumentProtection
|
||
// It recommends (but doesn't enforce) that users open as read-only
|
||
// Found in extended properties (docProps/custom.xml or settings)
|
||
|
||
settingsPart.Settings.Append(new WriteProtection
|
||
{
|
||
Recommended = true // "Recommend opening as read-only"
|
||
});
|
||
|
||
// Or force read-only recommendation with a specific application name
|
||
settingsPart.Settings.Append(new WriteProtection
|
||
{
|
||
Recommended = true,
|
||
ApplicationName = "Microsoft Word"
|
||
});
|
||
```
|
||
|
||
### 10.4 Restrict Editing to Form Fields Only
|
||
|
||
```csharp
|
||
// This protects the document but allows editing in form field content controls
|
||
settingsPart.Settings = new Settings(
|
||
new DocumentProtection
|
||
{
|
||
Edit = DocumentProtectionValues.Forms,
|
||
Enforcement = true
|
||
},
|
||
// Also set to allow editing only in form fields
|
||
new EditingRestrictions { Val = EditingRestrictionValues.Forms }
|
||
);
|
||
```
|
||
|
||
### 10.5 PermStart / PermEnd — Editable Regions in Protected Document
|
||
|
||
Allow specific regions (ranges) to be edited even when the document is protected.
|
||
|
||
```csharp
|
||
// <w:permStart w:id="1" w:editor="everyone"/>
|
||
// <w:r><w:t>Editable text</w:t></w:r>
|
||
// <w:permEnd w:id="1"/>
|
||
|
||
// Even when document protection is on, this range can be edited by everyone
|
||
|
||
var editableRegion = new Paragraph(
|
||
new ParagraphProperties(
|
||
new PermStart { Id = 1, EditorGroup = RangePermissionEditingGroupValues.Everyone }
|
||
),
|
||
new Run(new Text("This text can be edited even in a protected document.") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new ParagraphProperties(
|
||
new PermEnd { Id = 1 }
|
||
)
|
||
);
|
||
|
||
// EditorGroup values:
|
||
// Everyone — anyone can edit
|
||
// Administrators — only administrators
|
||
// Contributors — only contributors
|
||
// Editors — only editors
|
||
// Owners — only document owners
|
||
// Nobody — nobody can edit (use with w:perm sbz="1" for "does not include")
|
||
|
||
// Use specific user name:
|
||
// <w:permStart w:id="2" w:author="Alice"/>
|
||
|
||
// For tracked changes review scenario (allow comments but not direct editing):
|
||
var commentableRegion = new Paragraph(
|
||
new ParagraphProperties(
|
||
new PermStart { Id = 2, EditorGroup = RangePermissionEditingGroupValues.Everyone }
|
||
),
|
||
new Run(new Text("This region allows comments and tracked changes.") { Space = SpaceProcessingModeValues.Preserve }),
|
||
new ParagraphProperties(
|
||
new PermEnd { Id = 2 }
|
||
)
|
||
);
|
||
```
|
||
|
||
### 10.6 Full Document Protection with Password and Salt
|
||
|
||
```csharp
|
||
public static void ProtectDocument(
|
||
WordprocessingDocument doc,
|
||
string password,
|
||
DocumentProtectionValues protectionType)
|
||
{
|
||
var settingsPart = doc.MainDocumentPart!.AddNewPart<DocumentSettingsPart>();
|
||
if (settingsPart.Settings == null)
|
||
settingsPart.Settings = new Settings();
|
||
|
||
// Generate password hash
|
||
byte[] salt = new byte[16];
|
||
using (var rng = System.Security.Cryptography.RandomNumberGenerator.Create())
|
||
rng.GetBytes(salt);
|
||
|
||
int spinCount = 100000;
|
||
using var pbkdf2 = new System.Security.Cryptography.Rfc2898DeriveBytes(
|
||
password, salt, spinCount, System.Security.Cryptography.HashAlgorithmName.SHA512);
|
||
byte[] hash = pbkdf2.GetBytes(64);
|
||
|
||
var protection = new DocumentProtection
|
||
{
|
||
Edit = protectionType,
|
||
Enforcement = true,
|
||
CryptographicProviderType = CryptProviderValues.RsaAES,
|
||
CryptographicAlgorithmClass = CryptAlgorithmClassValues.Hash,
|
||
CryptographicAlgorithmType = CryptAlgorithmValues.TypeAny,
|
||
CryptographicAlgorithmSid = 14, // SHA-512
|
||
CryptographicSpinCount = (UInt32Value)spinCount,
|
||
Hash = Convert.ToBase64String(hash),
|
||
Salt = Convert.ToBase64String(salt)
|
||
};
|
||
|
||
settingsPart.Settings.Append(protection);
|
||
settingsPart.Settings.Save();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Quick Reference: Common Element Order in OpenXML
|
||
|
||
When building complex elements, remember these ordering rules:
|
||
|
||
### Run Elements Order (inside RunProperties):
|
||
`RunFonts` → `Bold`/`Italic` → `Color` → `FontSize` → `Underline` → `VerticalTextAlignment` → `Emphasis` → (any other)
|
||
|
||
### Paragraph Elements Order (inside ParagraphProperties):
|
||
`ParagraphStyleId` → `KeepNext` → `KeepLines` → `PageBreakBefore` → `FrameProperties` → `WidowControl` → `NumPr` → `Indentation` → `SpacingBetweenLines` → `Justification` → `SectionProperties`
|
||
|
||
### Table Properties Order:
|
||
`TableWidth` → `TextDirection` → `Borders` → `Shading` → `TableLayout` → `TableCellMarginDefault`
|
||
|
||
### SectionProperties Order:
|
||
`FootnotePr` → `EndnotePr` → `Type` → `PageSize` → `PageMargin` → `PaperSource` → `PageBorders` → `LineNumberRestart` → `PageNumberFormat` → `TitlePage` → `TextDirection`
|
||
|
||
---
|
||
|
||
*Generated for DocumentFormat.OpenXml 3.x / .NET 8+ / C# 12*
|
||
*Last updated: 2026-03-22*
|