OfficeIMO.Word 3.0.0

OfficeIMO.Word - Word documents for .NET

OfficeIMO.Word is the main Word document package in the OfficeIMO family. It creates, edits, inspects, converts, and saves .docx files, and can import and write supported legacy .doc files, without COM automation and without Microsoft Office installed.

If OfficeIMO saves you time, please consider supporting the work through GitHub Sponsors or PayPal. PowerShell users should use PSWriteOffice for the PowerShell-facing experience.

Install

dotnet add package OfficeIMO.Word

Quick start

using OfficeIMO.Word;

using var document = WordDocument.Create("report.docx");

document.AddParagraph("Quarterly report").Style = WordParagraphStyles.Heading1;
document.AddParagraph("Created with OfficeIMO.Word.");

var table = document.AddTable(2, 2, WordTableStyle.TableGrid);
table.Rows[0].Cells[0].Paragraphs[0].Text = "Area";
table.Rows[0].Cells[1].Paragraphs[0].Text = "Status";
table.Rows[1].Cells[0].Paragraphs[0].Text = "Documents";
table.Rows[1].Cells[1].Paragraphs[0].Text = "Generated";
table.RepeatHeaderRowAtTheTopOfEachPage = true;
table.Style = WordTableStyle.TableGrid;

document.Save();

What it does

• Creates, loads, edits, saves, and appends .docx documents.
• Opens supported Word 97-2003 .doc files through the normal WordDocument.Load(...) path and projects them into the regular OfficeIMO Word model.
• Writes native .doc files for the currently supported simple-document subset, with preflight checks that block unsupported content before saving.
• Converts supported .doc and .docx files with WordDocument.Convert(...), using the same import diagnostics and save preflight as normal load/save workflows.
• Works with paragraphs, runs, styles, sections, headers, footers, page numbers, tables, images, hyperlinks, bookmarks, fields, footnotes, endnotes, content controls, charts, shapes, and document protection.
• Applies optional shared package-security policy before parsing Open XML or compound DOC files, and preflights read, edit, template, render, and save capabilities.
• Inspects and manages VBA and embedded package/OLE/ActiveX payload bytes without executing active content.
• Exports estimated document page ranges as dependency-free PNG or SVG previews through ExportImages(...), SaveAsImages(...), and ToImages().
• Keeps Office automation out of the runtime path, making it suitable for services, scheduled jobs, CI, desktop apps, and automation hosts.
• Provides fluent helpers for common authoring flows while keeping the lower-level Word object model available.
• Uses OfficeIMO.Drawing for shared colors, image metadata, page rendering, and the reusable math expression tree.

For untrusted files, capability preflight, binary DOC/XLS/XLSB loss policies, macro and embedded-payload handling, and the executable compatibility corpus, see the Word and Excel interoperability guide.

Examples

The quick start shows the smallest useful document. These examples show the kinds of document work that belong in OfficeIMO.Word itself.

Paragraphs and runs

var paragraph = document.AddParagraph("Status: ");
paragraph.AddText("Approved").Bold = true;
paragraph.AddText(" on ");
paragraph.AddText(DateTime.Today.ToString("yyyy-MM-dd")).Italic = true;

Tables with structure

var table = document.AddTable(3, 3);
table.Rows[0].Cells[0].Paragraphs[0].Text = "Area";
table.Rows[0].Cells[1].Paragraphs[0].Text = "Owner";
table.Rows[0].Cells[2].Paragraphs[0].Text = "Status";
table.RepeatHeaderRowAtTheTopOfEachPage = true;
table.Style = WordTableStyle.TableGrid;

table.Rows[1].Cells[0].Paragraphs[0].Text = "Documents";
table.Rows[1].Cells[1].Paragraphs[0].Text = "Operations";
table.Rows[1].Cells[2].Paragraphs[0].Text = "Ready";

table.MergeCells(rowIndex: 2, columnIndex: 0, rowSpan: 1, colSpan: 3);
table.Rows[2].Cells[0].Paragraphs[0].Text = "Generated by OfficeIMO.Word";

Headers and footers

document.HeaderDefaultOrCreate.AddParagraph("Internal report");
document.FooterDefaultOrCreate.AddParagraph()
    .AddText("Page ")
    .AddPageNumber();

Images

var paragraph = document.AddParagraph();
paragraph.AddImage("logo.png", width: 160, height: 64);

Hyperlinks and bookmarks

document.AddParagraph("Jump target").AddBookmark("target-section");
document.AddParagraph()
    .AddHyperLink("Open project site", new Uri("https://github.com/EvotecIT/OfficeIMO"));
document.AddParagraph()
    .AddHyperLink("Jump inside document", "target-section", addStyle: true);

Fields and table of contents

document.AddParagraph("Chapter 1").Style = WordParagraphStyles.Heading1;
document.AddParagraph("Section 1.1").Style = WordParagraphStyles.Heading2;
document.Paragraphs[0].AddField(WordFieldType.TOC);

Mail merge fields

var merge = document.AddParagraph();
merge.AddText("Customer: ");
merge.AddField(new WordFieldBuilder(WordFieldType.MergeField)
    .AddInstruction("CustomerName"));

var totalField = new WordFieldBuilder(WordFieldType.MergeField)
    .AddInstruction("OrderTotal")
    .SetFormat(WordFieldFormat.Numeric);
merge.AddField(totalField);

Content controls

document.FillContentControlValues(new Dictionary<string, object?> {
    ["Name"] = "Ada Lovelace",
    ["Approved"] = true,
    ["DueDate"] = DateTime.Today
});

Dictionary<string, object?> values = document.ExtractContentControlValues();
document.ValidateContentControlValues(values).EnsureValid();

Legacy DOC files

using OfficeIMO.Word;
using OfficeIMO.Word.LegacyDoc;

using WordDocument document = WordDocument.Load("legacy-input.doc");
document.Save("converted-output.docx");

WordDocument.Convert("legacy-input.doc", "converted-output.docx");
WordDocument.Convert("openxml-input.docx", "legacy-output.doc");

using LegacyDocLoadResult result = WordDocument.LoadLegacyDocWithReport("legacy-input.doc");
if (result.HasDocument) {
    result.EnsureNoConversionLoss();
    result.Document.Save("converted-output.docx");
    string report = result.CreateAdvancedImportReport().ToMarkdown();
}

Legacy .doc support is first-party and dependency-free at runtime. The current reader projects supported Word 97-2003 body paragraphs, simple zero-length, same-paragraph, and cross-paragraph body bookmarks plus simple table-cell, header/footer, and footnote/endnote paragraph bookmarks, simple external and internal bookmark hyperlink fields with supported text, tab, soft/no-break hyphen, and break display runs, simple static date/time and document-property field display results, common run and paragraph formatting including proofing exclusion, bidirectional paragraph layout, mirror indents, contextual spacing, East Asian typography and punctuation spacing flags, and automatic hyphenation suppression, built-in and custom paragraph styles, simple tables, paragraph-boundary sections, page setup, simple header/footer stories with tabs, text-wrapping and column breaks, supported direct run formatting, and supported paragraph formatting, simple footnote/endnote bodies with supported direct run and paragraph formatting and soft/no-break hyphen runs, section note numbering and placement settings, and document properties into the normal WordDocument model. Native .doc saving is available for the supported simple subset: paragraphs, simple zero-length, same-paragraph, and cross-paragraph body bookmarks plus simple table-cell, header/footer, and footnote/endnote paragraph bookmarks, simple external and internal bookmark hyperlinks with supported text, tab, soft/no-break hyphen, break display runs, simple static date/time and document-property fields with static display text and supported inline result characters including inside flattened inline content controls, simple inline content-control display text, and simple block content controls with nested simple block controls plus nested inline content controls in body/table/header/footer/footnote/endnote stories, common run and paragraph formatting including proofing exclusion, bidirectional paragraph layout, mirror indents, contextual spacing, East Asian typography and punctuation spacing flags, and automatic hyphenation suppression, tabs, soft/no-break hyphen runs, line/carriage-return/page/column breaks, simple body tables with common formatting, including simple depth-2 nested tables, supported table-style border, shading, layout, paragraph formatting, run formatting, default-cell expansion, conditional table/cell border, shading, paragraph formatting, run formatting, cell-layout expansion, and conditional row height/header/no-split formatting, paragraph-boundary sections, page setup, simple header/footer stories with tabs, soft/no-break hyphen runs, text-wrapping, carriage-return, and column breaks, supported direct run formatting, and supported paragraph formatting, simple footnote/endnote bodies with supported direct run and paragraph formatting and soft/no-break hyphen runs, supported section note settings, and scalar document properties. Unsupported features such as macros, embedded OLE objects, comments, text boxes, images, bookmark ranges outside supported body/table-cell/header/footer/footnote/endnote paragraphs, richer content-control children, richer visual table style effects, deeper or richer nested table shapes, richer note body structures, and richer header/footer or section shapes are diagnosed or blocked rather than silently flattened. WordDocument.Convert(...) uses those same load and save paths and blocks legacy sources with unsupported or preserve-only content by default. Set LossPolicy to WordConversionLossPolicy.Allow on WordDocumentConversionOptions or WordSaveOptions only when that loss has been reviewed and is intentional. See DOC and DOCX compatibility for the current capability matrix, safety contract, and breaking API migration.

Protection

using DocumentFormat.OpenXml.Wordprocessing;

document.Settings.ProtectionPassword = "owner-password";
document.Settings.ProtectionType = DocumentProtectionValues.ReadOnly;

Editable equations from the shared math model

using OfficeIMO.Drawing;

OfficeMathExpression equation = OfficeMath.Fraction(
    OfficeMath.Superscript(OfficeMath.Identifier("x"), OfficeMath.Number("2")),
    OfficeMath.Number("2"));

WordParagraph paragraph = document.AddEquation(equation);
paragraph.AddText(" is editable Word math.");

WordDocument.AddEquation(...) and WordParagraph.AddEquation(...) map the shared expression directly to native OMML. Existing equations expose ToExpression(), SetExpression(...), and ToDrawing(...); WordMathMarkup converts between OMML and OfficeMathExpression. The adapter covers matrices and multi-column equation arrays, left/right scripts, centered limits, skewed fractions, delimiter lists, n-ary operators, and decorations. Display-equation replacement retains oMathParaPr presentation metadata. Shared Stack and StretchStack nodes fail closed because OMML has no lossless equivalent; use OfficeMath.EquationArray(...) explicitly if that alternate layout is acceptable. The reusable AST stays in OfficeIMO.Drawing, while Word owns only the OMML adapter.

Convert with adjacent packages

using OfficeIMO.Word.Html;
using OfficeIMO.Word.Markdown;
using OfficeIMO.Word.Pdf;

string html = document.ToHtml(new WordToHtmlOptions { IncludeDefaultCss = true });
string markdown = document.ToMarkdown(new WordToMarkdownOptions());
document.SaveAsPdf("report.pdf");

Managed image export

Word page previews use the shared Drawing renderer and can be returned as PNG, JPEG, TIFF, lossless WebP, or SVG without Office automation:

using OfficeIMO.Drawing;

byte[] webp = document.ToWebp(new WordImageExportOptions { PageIndex = 0, Scale = 1.5 });

document.ToImage()
    .Page(0)
    .AsJpeg()
    .WithRasterEncoding(raster => raster.Jpeg.Quality = 90)
    .Save("page-1.jpg");

The document package owns Word pagination and diagnostics; OfficeIMO.Drawing owns pixels and encoding. SaveAsJpeg, SaveAsTiff, and SaveAsWebp are thin convenience wrappers over the same builder.

Adjacent packages

OfficeIMO.Word owns the Word model. Conversion and export packages stay separate so consumers only take the dependencies they need:

Boundaries

• PowerShell examples and cmdlets belong in PSWriteOffice, not this package README.
• Long capability inventories and roadmap notes belong in focused docs under Docs/.
• PDF layout behavior belongs in OfficeIMO.Word.Pdf and OfficeIMO.Pdf.

Targets and license

• Targets: netstandard2.0, net8.0, net10.0; net472 is included when building on Windows.
• License: MIT.
• Repository: EvotecIT/OfficeIMO

Runnable samples live under OfficeIMO.Examples/Word.

Dependency footprint

• External: Open XML SDK for .docx package mechanics. Microsoft BCL compatibility packages are used on older targets.
• OfficeIMO: OfficeIMO.Drawing. The fluent model, native OMML adapter, legacy .doc reader/writer, lifecycle, validation, and PNG/JPEG/TIFF/WebP/SVG export are first-party.

See the complete OfficeIMO package map for related formats and conversion paths.