Working with Text

Text in a Word document is organized into Run nodes (contiguous characters sharing the same font formatting) grouped inside Paragraph nodes. Aspose.Words FOSS for .NET exposes both directly, along with Font for character formatting, ParagraphFormat for paragraph-level formatting, and Range for reading or replacing text over any part of the tree. This guide covers runs and fonts, paragraph formatting, reading and replacing text, comments, and paragraph-level list formatting.

Runs and Character Formatting

A Run represents a span of text that shares one set of formatting; its Text property holds the plain-text content and its Font property (a Font object) holds character-level formatting — Name, Size, Bold, Italic, Underline, Color, HighlightColor, Subscript/Superscript, StrikeThrough, and many more. Font.ClearFormatting() resets a run’s font back to defaults. A paragraph’s runs are available through its Runs property, a RunCollection.

Paragraphs and Paragraph Formatting

Paragraph is a composite node containing the runs (and other inline content) of one paragraph; a document’s or body’s paragraphs are exposed as a ParagraphCollection (Body.Paragraphs). Paragraph.ParagraphFormat (a ParagraphFormat object) controls paragraph-level layout — Alignment, indents (LeftIndent, RightIndent, FirstLineIndent), spacing (SpaceBefore, SpaceAfter, LineSpacing, LineSpacingRule), and pagination behavior (KeepTogether, KeepWithNext, PageBreakBefore, WidowControl). ParagraphFormat.ClearFormatting() resets these back to defaults, and Paragraph.JoinRunsWithSameFormatting() merges adjacent runs that carry identical formatting.

Reading and Replacing Text with Range

Every node that contains content — a Document, Section, Paragraph, or Run — exposes a Range. Range.Text returns the plain text of everything within that range, and Range.Replace(pattern, replacement) performs a find-and-replace scoped to just that range, so you can, for example, replace text inside one paragraph without touching the rest of the document. Range.Delete() removes the range’s content outright.

Comments

A Comment node anchors a comment to a location in the text; construct one with new Comment(doc, author, initial, dateTime) and set its body text with SetText(text), then insert it into the document like any other node. Comment.AddReply(author, initial, dateTime, text) attaches a threaded reply, and RemoveReply(reply) / RemoveAllReplies() remove them. A document’s comments are collected in a CommentCollection.

List Formatting at the Paragraph Level

Paragraph.ListFormat (a ListFormat object) reports and controls whether a paragraph is part of a list: IsListItem and ListLevelNumber report its current state, ApplyBulletDefault() and ApplyNumberDefault() turn a paragraph into a default bulleted or numbered list item, ListIndent() / ListOutdent() change its list nesting level, and RemoveNumbers() turns it back into a regular paragraph.

Tips and Best Practices

Set font properties on DocumentBuilder.Font before writing text with the builder rather than writing text first and reformatting individual Run objects afterward.
Scope Range.Replace to the smallest range that covers what you actually want changed — call it on a Paragraph or Section’s range instead of the whole document when the change should not apply document-wide.
Call Paragraph.JoinRunsWithSameFormatting() after a series of programmatic edits to avoid an unnecessarily fragmented run structure.
Use ListFormat.ApplyBulletDefault() / ApplyNumberDefault() for a quick default list rather than constructing list definitions manually when the built-in defaults are sufficient.
Read Comment.AddReply results as Comment nodes themselves — replies are full comment objects, not plain strings.

Common Issues

Issue	Cause	Fix
Formatting a `Run`’s `Font` doesn’t visually change adjacent text	Adjacent text is in a different `Run` with its own `Font` instance	Locate and format every affected `Run`, or set formatting via `DocumentBuilder.Font` before writing
`Range.Replace` changes text outside the intended area	`Replace` was called on `Document.Range` instead of a narrower node’s range	Call `Replace` on the specific `Paragraph`, `Section`, or other node’s `Range`
A paragraph looks like a list item but `IsListItem` is false	The bullet/number is manual text, not real list formatting	Apply real list formatting with `ListFormat.ApplyBulletDefault()` or `ApplyNumberDefault()` instead of typed characters
Document has many more `Run` nodes than expected	Repeated small edits split runs without rejoining them	Call `Paragraph.JoinRunsWithSameFormatting()` after batches of edits

FAQ

What’s the difference between `Run` and `Paragraph`?

A Run is a span of text sharing one set of character formatting (Font); a Paragraph is the composite node that contains one or more runs (and other inline content) plus paragraph-level formatting (ParagraphFormat).

How do I read all the text in a document or section?

Read the Text property of that node’s Range — for example, document.Range.Text or section.Range.Text.

How do I find and replace text in just one paragraph?

Call Replace(pattern, replacement) on that Paragraph’s Range rather than on Document.Range.

How do I add a comment to a document?

Create it with new Comment(doc, author, initial, dateTime), set its text with SetText(text), and insert it into the tree; reply to it with Comment.AddReply(author, initial, dateTime, text).

How do I turn a paragraph into a bulleted list item?

Call ApplyBulletDefault() on that paragraph’s ListFormat; use ApplyNumberDefault() for a numbered list instead.

API Reference Summary

Class/Method	Description
`Run`	A span of text sharing one set of character formatting.
`Font`	Character-level formatting — name, size, bold, italic, color, and more.
`Paragraph`	Composite node containing the runs and formatting of one paragraph.
`ParagraphFormat`	Paragraph-level formatting — alignment, indents, spacing, pagination.
`ParagraphCollection`	Typed collection of `Paragraph` nodes, e.g. `Body.Paragraphs`.
`Range`	A contiguous area of the document; supports `Text`, `Replace`, and `Delete`.
`Comment`	A threaded comment anchored to a location in the text.
`CommentCollection`	The document’s collection of comments.
`ListFormat`	Controls whether and how a paragraph participates in a list.

Working with Text