Class WordDocument

Represents a Word document containing text, formatting, and other content elements.

Inheritance

System.Object

WordDocument

Implements

IronSoftware.Abstractions.Word.IWordDocument

IronSoftware.Abstractions.IDocument

IronSoftware.Abstractions.IParent<IronSoftware.Abstractions.Word.IWordDocumentObjectCollection, IronSoftware.Abstractions.Word.IWordDocumentObject>

Namespace: IronWord

Assembly: IronWord.dll

Syntax

public class WordDocument : Object

WordDocument is the object you hold whenever you create, edit, read, or save a .docx file in C#. It models a whole Word document, and almost every IronWord task starts by constructing one and ends by saving it. Reach for it when a project needs to build a report from code, fill an existing template, or pull text and images back out of a document a user uploaded.

Construct it four ways: new WordDocument() for an empty document, new WordDocument(string filePath) or new WordDocument(byte[] bytes) to load an existing file, and new WordDocument(params ContentElement[] children) to assemble one from elements you already built. Once you hold the instance, you mutate it in memory and then write it out, so the same object spans the full create-edit-save sequence.

The members group into a few clear jobs. For **content authoring**, AddText, AddParagraph, AddRun, AddTable, AddImage, AddShape, AddSection, AddMultiLevelTextList, and AddChild append elements to the body. For **reading the structure**, the Paragraphs, Runs, Tables, Texts, Sections, Children, and MultiLevelTextLists collections expose what the document already contains, and PageCount reports its length. For **extraction and search**, ExtractText, ExtractTextFromPage, ExtractTextFromPages, ExtractImages, ExtractShapes, FindText, ReplaceText, and Remove mine and edit existing content. For **persistence**, Save and SaveAs write .docx to a path (Save() returns bytes), ToPdf exports straight to PDF, ToJson serializes the model, and LogObjectTree prints the element hierarchy for debugging. MailMerge reaches the template-merge surface.

using IronWord;
using IronWord.Models;

var document = new WordDocument();
document.AddText("Quarterly Report");
document.SaveAs("report.docx");

The add text how-to walks through writing content, the extract text how-to reads it back, and the Word to PDF how-to covers the PDF export path.

Constructors

WordDocument()

Initializes a new instance of the WordDocument class, creating a new blank document.

Declaration

public WordDocument()

WordDocument(ContentElement[])

Initializes a new instance of the WordDocument class with the specified content elements.

Declaration

public WordDocument(params ContentElement[] children)

Parameters

Type	Name	Description
ContentElement[]	children	The child content elements to be added to the document.

WordDocument(Byte[])

Initializes a new instance of the WordDocument class from an existing document file.

Declaration

public WordDocument(byte[] bytes)

Parameters

Type	Name	Description
System.Byte[]	bytes	The bytes of the document file.

Exceptions

Type	Condition
System.ArgumentNullException	bytes is null.

WordDocument(Stream)

Initializes a new instance of the WordDocument class from an existing document contained in a System.IO.Stream.

Declaration

public WordDocument(Stream stream)

Parameters

Type	Name	Description
System.IO.Stream	stream	The stream containing the document. Cannot be null.

Remarks

The document is read from the stream's current position to the end; the stream is left positioned at its end and is not closed by this constructor.

Exceptions

Type	Condition
System.ArgumentNullException	stream is null.

WordDocument(String)

Initializes a new instance of the WordDocument class from an existing document file.

Declaration

public WordDocument(string filePath)

Parameters

Type	Name	Description
System.String	filePath	The path to the document file.

Properties

Children

Children of the word document.

Declaration

public IWordDocumentObjectCollection Children { get; }

Property Value

Type	Description
IronSoftware.Abstractions.Word.IWordDocumentObjectCollection

MailMerge

Gets the MailMerge facade for performing mail merge operations on this document.

Declaration

public MailMerge MailMerge { get; }

Property Value

Type	Description
MailMerge

MultiLevelTextLists

Gets a list of all MultiLevelTextList elements contained within the document.

Declaration

public List<MultiLevelTextList> MultiLevelTextLists { get; }

Property Value

Type	Description
System.Collections.Generic.List<MultiLevelTextList>	A List object containing all MultiLevelTextList elements.

PageCount

Declaration

public int PageCount { get; }

Property Value

Type	Description
System.Int32

Paragraphs

Gets a list of all Paragraph elements contained within the document.

Declaration

public List<Paragraph> Paragraphs { get; }

Property Value

Type	Description
System.Collections.Generic.List<Paragraph>	A List object containing all Paragraph elements.

Runs

Gets a list of all Run elements contained within the document.

Declaration

public List<Run> Runs { get; }

Property Value

Type	Description
System.Collections.Generic.List<Run>	A List object containing all Run elements.

Sections

Gets a list of all DocumentSection elements contained within the document.

Declaration

public List<DocumentSection> Sections { get; }

Property Value

Type	Description
System.Collections.Generic.List<DocumentSection>	A List object containing all DocumentSection elements.

Tables

A list of all table elements contained within this element or its children

Declaration

public List<Table> Tables { get; }

Property Value

Type	Description
System.Collections.Generic.List<Table>

Texts

A list of all text elements contained within this element or its children

Declaration

public List<TextContent> Texts { get; }

Property Value

Type	Description
System.Collections.Generic.List<TextContent>

Methods

AddChild(ContentElement[])

Adds one or more child content elements to the current document.

Declaration

public void AddChild(params ContentElement[] children)

Parameters

Type	Name	Description
ContentElement[]	children	The content elements to be added as children.

AddImage(AnyBitmap)

Adds an image to this document from an IronSoftware.Drawing.AnyBitmap object.

Declaration

public ImageContent AddImage(AnyBitmap anyBitmap)

Parameters

Type	Name	Description
IronSoftware.Drawing.AnyBitmap	anyBitmap

Returns

Type	Description
ImageContent

AddImage(ImageContent)

Adds a new Image object to the document.

Declaration

public ImageContent AddImage(ImageContent imageContent)

Parameters

Type	Name	Description
ImageContent	imageContent	The Image object to be added.

Returns

Type	Description
ImageContent

AddImage(Stream)

Adds an image to the document.

Declaration

public ImageContent AddImage(Stream imageStream)

Parameters

Type	Name	Description
System.IO.Stream	imageStream	The stream image to be loaded.

Returns

Type	Description
ImageContent	The added Image.

AddImage(String)

Adds an image to the document.

Declaration

public ImageContent AddImage(string imagePath)

Parameters

Type	Name	Description
System.String	imagePath	The physical path of Image to be loaded.

Returns

Type	Description
ImageContent	The added Image.

AddMultiLevelTextList(MultiLevelTextList)

Adds a new multiLevelTextList object to the document.

Declaration

public MultiLevelTextList AddMultiLevelTextList(MultiLevelTextList multiLevelTextList)

Parameters

Type	Name	Description
MultiLevelTextList	multiLevelTextList	The multiLevelTextList object to be added.

Returns

Type	Description
MultiLevelTextList	A instance of the added MultiLevelTextList.

AddParagraph(Paragraph)

Adds a new Paragraph object to the document.

Declaration

public Paragraph AddParagraph(Paragraph paragraph)

Parameters

Type	Name	Description
Paragraph	paragraph	The Paragraph object to be added.

Returns

Type	Description
Paragraph

AddRun(Run)

Adds a run to the last paragraph of the document.

Declaration

public Run AddRun(Run run)

Parameters

Type	Name	Description
Run	run	The run to be added.

Returns

Type	Description
Run

AddSection()

Adds a new document section to this document.

Declaration

public void AddSection()

AddSection(DocumentSection)

Creates a new DocumentSection object with the specified type and adds it to the document.

Declaration

public void AddSection(DocumentSection documentSection)

Parameters

Type	Name	Description
DocumentSection	documentSection	The type of the section to be added.

AddShape(ShapeContent)

Adds a new Shape object to the document.

Declaration

public ShapeContent AddShape(ShapeContent shapeContent)

Parameters

Type	Name	Description
ShapeContent	shapeContent	The Shape object to be added.

Returns

Type	Description
ShapeContent

AddTable(Table)

Adds a new Table object to the document.

Declaration

public Table AddTable(Table table)

Parameters

Type	Name	Description
Table	table	The Table object to be added.

Returns

Type	Description
Table

AddText(TextContent)

Adds a new TextRun object to the last paragraph of the document.

Declaration

public TextContent AddText(TextContent textContentRun)

Parameters

Type	Name	Description
TextContent	textContentRun	The TextRun object to be added.

Returns

Type	Description
TextContent

AddText(String)

Adds a text to the last paragraph of document.

Declaration

public TextContent AddText(string text)

Parameters

Type	Name	Description
System.String	text	The text to be added.

Returns

Type	Description
TextContent

ExtractImages()

Declaration

public List<ImageContent> ExtractImages()

Returns

Type	Description
System.Collections.Generic.List<ImageContent>

ExtractShapes()

Declaration

public List<ShapeContent> ExtractShapes()

Returns

Type	Description
System.Collections.Generic.List<ShapeContent>

ExtractText()

Declaration

public string ExtractText()

Returns

Type	Description
System.String

ExtractTextFromPage(Int32)

Declaration

public string ExtractTextFromPage(int PageIndex)

Parameters

Type	Name	Description
System.Int32	PageIndex

Returns

Type	Description
System.String

ExtractTextFromPages(IEnumerable<Int32>)

Declaration

public string ExtractTextFromPages(IEnumerable<int> PageIndices)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.Int32>	PageIndices

Returns

Type	Description
System.String

FindText(String)

Declaration

public TextContent FindText(string find)

Parameters

Type	Name	Description
System.String	find

Returns

Type	Description
TextContent

LoadAsync(Stream, CancellationToken)

Asynchronously creates a new WordDocument from a document contained in a System.IO.Stream.

Declaration

public static Task<WordDocument> LoadAsync(Stream stream, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
System.IO.Stream	stream	The stream containing the document. Cannot be null.
System.Threading.CancellationToken	cancellationToken	A token to observe while awaiting the read.

Returns

Type	Description
System.Threading.Tasks.Task<WordDocument>	A task that resolves to the loaded document.

Remarks

The document is read from the stream's current position to the end; the stream is left positioned at its end and is not closed. The read is asynchronous; parsing the loaded bytes is a synchronous, CPU-bound operation that cancellationToken cannot interrupt (the token is observed before parsing begins).

Exceptions

Type	Condition
System.ArgumentNullException	stream is null.

LoadAsync(String, CancellationToken)

Asynchronously creates a new WordDocument from an existing document file.

Declaration

public static Task<WordDocument> LoadAsync(string filePath, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
System.String	filePath	The path to the document file.
System.Threading.CancellationToken	cancellationToken	A token to observe while awaiting the read.

Returns

Type	Description
System.Threading.Tasks.Task<WordDocument>	A task that resolves to the loaded document.

Remarks

The file read is asynchronous; parsing the loaded bytes is a synchronous, CPU-bound operation that cancellationToken cannot interrupt (the token is observed before parsing begins).

Exceptions

Type	Condition
System.ArgumentNullException	filePath is null.

LogObjectTree()

Initiates logging of the object tree by traversing from the current object.

Declaration

public void LogObjectTree()

Remove(TextContent)

Declaration

public bool Remove(TextContent element)

Parameters

Type	Name	Description
TextContent	element

Returns

Type	Description
System.Boolean

ReplaceText(String, String)

Declaration

public void ReplaceText(string find, string replace)

Parameters

Type	Name	Description
System.String	find
System.String	replace

Save()

Saves the current document and returns its bytes. When the document was loaded from a file, the changes are also written back to that original file.

Declaration

public byte[] Save()

Returns

Type	Description
System.Byte[]	The saved document as a System.Byte array.

Save(Stream)

Saves the current document to a System.IO.Stream.

Declaration

public void Save(Stream stream)

Parameters

Type	Name	Description
System.IO.Stream	stream	The destination stream. Cannot be null.

Remarks

The bytes are written at the stream's current position; the stream length is not changed. When reusing a stream that already holds more data than the new document, reset or truncate it first, otherwise stale trailing bytes remain and corrupt the output. The caller retains ownership of the stream; it is neither flushed nor closed by this method.

Exceptions

Type	Condition
System.ArgumentNullException	stream is null.

Save(String)

Saves the current document to a specific file path.

Declaration

public void Save(string filePath)

Parameters

Type	Name	Description
System.String	filePath	The full path to the file where the document will be saved.

Exceptions

Type	Condition
System.Exception	filePath is null or empty.

SaveAs(String)

Saves the current document as a new file with the specified name.

Declaration

public void SaveAs(string filePath)

Parameters

Type	Name	Description
System.String	filePath	The file path for the new document file.

SaveAsAsync(String, CancellationToken)

Asynchronously saves the current document as a new file with the specified name.

Declaration

public Task SaveAsAsync(string filePath, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
System.String	filePath	The file path for the new document file.
System.Threading.CancellationToken	cancellationToken	A token to observe before serialization and the write.

Returns

Type	Description
System.Threading.Tasks.Task

Remarks

Serialization runs synchronously and cannot be interrupted by cancellationToken; the token is observed before serialization begins and before the destination file is opened, so a canceled call never truncates an existing file. A single WordDocument instance is not thread-safe.

SaveAsync(Stream, CancellationToken)

Asynchronously saves the current document to a System.IO.Stream.

Declaration

public Task SaveAsync(Stream stream, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
System.IO.Stream	stream	The destination stream. Cannot be null.
System.Threading.CancellationToken	cancellationToken	A token to observe before serialization and the write.

Returns

Type	Description
System.Threading.Tasks.Task

Remarks

The bytes are written at the stream's current position; the stream length is not changed. When reusing a stream that already holds more data than the new document, reset or truncate it first, otherwise stale trailing bytes remain and corrupt the output. The caller retains ownership of the stream; it is neither flushed nor closed by this method. Serialization runs synchronously and cannot be interrupted by cancellationToken; the token is observed before serialization begins and around the write. A single WordDocument instance is not thread-safe.

Exceptions

Type	Condition
System.ArgumentNullException	stream is null.

SaveAsync(String, CancellationToken)

Asynchronously saves the current document to a specific file path.

Declaration

public Task SaveAsync(string filePath, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
System.String	filePath	The full path to the file where the document will be saved.
System.Threading.CancellationToken	cancellationToken	A token to observe before serialization and the write.

Returns

Type	Description
System.Threading.Tasks.Task

Remarks

Serialization runs synchronously and cannot be interrupted by cancellationToken; the token is observed before serialization begins and before the destination file is opened, so a canceled call never truncates an existing file. A single WordDocument instance is not thread-safe.

Exceptions

Type	Condition
System.Exception	filePath is null or empty.

ToJson()

Declaration

public string ToJson()

Returns

Type	Description
System.String

ToPdf(String)

Converts word document to PDF.

Declaration

public void ToPdf(string fileName)

Parameters

Type	Name	Description
System.String	fileName	The name of the output file.

Remarks

Requires IronPDF to work.

Implements

IronSoftware.Abstractions.Word.IWordDocument

IronSoftware.Abstractions.IDocument

IronSoftware.Abstractions.IParent<, >