Introduction
Aspose.Words FOSS for .NET includes the same text-formatting object model as the commercial Aspose.Words engine: Font for run-level attributes, ParagraphFormat for paragraph-level attributes, ListFormat for numbered and bulleted lists, FrameFormat for positioned text frames, and Range.Replace for find-and-replace. This guide looks specifically at that layer — formatting and rewriting text that already exists in a document — rather than at building a document’s structure from scratch (see the introduction post for an overview of the release).
The library is MIT-licensed with no native dependencies and targets .NET Standard 2.0, so it runs on .NET Framework 4.6.2+ and .NET 6, 8, and 10. A NuGet package has not been published yet; build it from source instead (see Quick Start below). Everything described here works against .docx, .docm, .dotx, .dotm, and Flat OPC files loaded with new Document(fileName), or against documents built in memory with DocumentBuilder.
Because Aspose.Words FOSS for .NET is the genuine Aspose.Words codebase reduced to a free core rather than a rewrite, the Font, ParagraphFormat, ListFormat, and FrameFormat object model carries over directly to the commercial Aspose.Words for .NET if a project later needs page layout, rendering, or the additional format converters that this edition excludes.
Key Features
Run-Level Formatting with Font
Every Run exposes a Font property, and DocumentBuilder.Font sets the font that will be applied to text written next. Besides the obvious Bold, Italic, and Underline (an Underline enum with values including Single, Double, Dotted, Dash, Wavy, and their *Heavy variants), Font covers StrikeThrough, DoubleStrikeThrough, Superscript, Subscript, SmallCaps, AllCaps, Hidden, Shadow, Outline, Emboss, Engrave, Color, HighlightColor, Spacing, Position, Kerning, Scaling, and EmphasisMark. Font.Style, Font.StyleName, and Font.StyleIdentifier tie a run back to a character style, and Font.ClearFormatting() resets direct formatting on a run back to its style defaults. DocumentBuilder also exposes Bold, Italic, and Underline directly as shortcuts, plus PushFont() and PopFont() to save and restore the builder’s current font state around a temporary formatting change.
Paragraph Formatting with ParagraphFormat
ParagraphFormat (reachable through Paragraph.ParagraphFormat or DocumentBuilder.ParagraphFormat) controls alignment through the ParagraphAlignment enum (Left, Center, Right, Justify, Distributed, plus Arabic kashida and Thai-distributed variants), indentation through LeftIndent, RightIndent, and FirstLineIndent (with CharacterUnit* equivalents for East Asian layouts), and spacing through SpaceBefore, SpaceAfter, and LineSpacingRule/LineSpacing. Pagination behavior is controlled with KeepTogether, KeepWithNext, PageBreakBefore, and WidowControl, and Bidi marks a paragraph as right-to-left. Custom tab stops live in ParagraphFormat.TabStops, a TabStopCollection of TabStop objects, each with a Position, a TabAlignment (Left, Center, Right, Decimal, Bar), and a TabLeader (None, Dots, Dashes, Line, Heavy, MiddleDot). As with Font, ParagraphFormat.Style and StyleName link the paragraph to a named Style, and ClearFormatting() clears direct paragraph formatting.
Lists with ListFormat
ListFormat (on Paragraph.ListFormat or DocumentBuilder.ListFormat) applies list formatting to a paragraph: ApplyBulletDefault() and ApplyNumberDefault() switch it to a default bulleted or numbered list, RemoveNumbers() removes list formatting entirely, and ListIndent()/ListOutdent() move it between list levels. ListFormat.List returns the underlying List definition, and ListFormat.ListLevel returns the ListLevel in effect for that paragraph, which carries per-level settings such as NumberStyle, NumberFormat, Alignment (a ListLevelAlignment of Left, Center, or Right), StartAt, RestartAfterLevel, a level-specific Font, and TrailingCharacter (a ListTrailingCharacter of Tab, Space, or Nothing) controlling the gap between the list label and the paragraph text. New list definitions come from ListCollection.Add(listTemplate) using one of the built-in ListTemplate presets (BulletDefault, NumberArabicDot, NumberUppercaseRomanDot, and similar), or AddSingleLevelList for a single-level list; a document’s lists are enumerated through Document.Lists.
Text Frames with FrameFormat
Paragraph.FrameFormat is a read-only reporting object: every property on it reflects a paragraph’s current frame state rather than letting you set it directly. IsFrame reports whether the paragraph is currently a frame; Width, Height, and HeightRule report its size; HorizontalPosition and VerticalPosition, together with RelativeHorizontalPosition and RelativeVerticalPosition, report where it is anchored relative to the page, margin, column, or paragraph; and HorizontalDistanceFromText/VerticalDistanceFromText report the gap between the frame and the surrounding body text. HorizontalAlignment and VerticalAlignment report how content aligns within the frame.
Find and Replace with Range and IReplacingCallback
Range.Replace — available on Document.Range for a whole-document pass, or on the Range of any node — has overloads for a plain pattern/replacement pair and for a pattern/replacement pair combined with a FindReplaceOptions instance, supporting regex-based matching. FindReplaceOptions.MatchCase and FindWholeWordsOnly narrow what counts as a match; Direction (FindReplaceDirection.Forward or Backward) sets scan order; ApplyFont and ApplyParagraphFormat let a replace pass carry formatting onto the replacement text; and a set of Ignore* flags (IgnoreDeleted, IgnoreInserted, IgnoreFields, IgnoreFieldCodes, IgnoreFootnotes, IgnoreStructuredDocumentTags, IgnoreShapes, IgnoreOfficeMath) exclude specific content categories from the match. For replacement logic that a fixed string can’t express, implement IReplacingCallback.Replacing(args) and set it as FindReplaceOptions.ReplacingCallback (or pass it to one of the FindReplaceOptions constructors that accepts a callback directly); the args parameter is a ReplacingArgs exposing Match, MatchNode, MatchOffset, and a settable Replacement string so the callback can compute a value per match. A related ReplaceAction enum (Replace, Skip, Stop) describes the possible outcomes for a single match during the operation.
Quick Start
A NuGet package has not been published yet; build the library from source:
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
Then add a project reference to Aspose.Words.csproj. To format text as you author it, set DocumentBuilder.Font properties (Bold, Italic, Underline), DocumentBuilder.ParagraphFormat properties (Alignment, indents, spacing), and DocumentBuilder.ListFormat (ApplyBulletDefault(), ApplyNumberDefault()) before calling Write(), Writeln(), or InsertParagraph() — the builder applies its current formatting state to everything written until you change it again, or wrap a temporary change in PushFont()/PopFont(). To reformat or rewrite text already in a document, open it with new Document(fileName) and call Range.Replace() on doc.Range — either the plain pattern/replacement overload, or the overload that takes a FindReplaceOptions with MatchCase, FindWholeWordsOnly, or a custom IReplacingCallback — then Save() the result.
Supported Formats
| Format | Extension | Read | Write |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (all variants) | (various) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
The formatting classes above apply the same way regardless of which of these formats a document is loaded from or saved to. This edition does not support DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, or WordML for reading or writing, and does not support PDF, XPS, or image export, since page layout and rendering are outside its scope.
Open Source & Licensing
Aspose.Words FOSS for .NET is released under the MIT license, free for commercial and personal use with no royalties or redistribution restrictions. The full source, including the Font, ParagraphFormat, ListFormat, FrameFormat, and Range implementations described above, is available on GitHub in the Aspose.Words FOSS for .NET repository.