Find and Replace

Find and Replace

Aspose.Words FOSS for .NET provides regular-expression-based find and replace through Range.Replace(), configurable via FindReplaceOptions and, for advanced scenarios, a custom IReplacingCallback implementation from the Aspose.Words.Replacing namespace.

Basic Find and Replace

Range.Replace(pattern, replacement) runs a regular-expression search-and-replace across the range — the whole document, when called on Document.Range. The Replace(pattern, replacement, options) overload accepts a FindReplaceOptions object for finer control: MatchCase and FindWholeWordsOnly adjust the match behavior, Direction (a FindReplaceDirection value, Forward or Backward) controls the search direction, and ApplyFont / ApplyParagraphFormat let a replacement carry new formatting rather than only new text.

Formatting-Aware and Structural Options

FindReplaceOptions includes several flags that determine which document constructs a match may cross or ignore: IgnoreDeleted and IgnoreInserted control whether tracked-change content participates in matching, IgnoreFields and IgnoreFieldCodes control whether field result text and field codes are searched, IgnoreFootnotes excludes footnote/endnote content, and IgnoreStructuredDocumentTags and IgnoreShapes exclude content controls and shape text respectively. UseSubstitutions enables regular-expression substitution syntax (like $1) in the replacement string. LegacyMode and UseLegacyOrder preserve older matching behavior for compatibility with documents processed by earlier logic.

Custom Replace Logic with IReplacingCallback

For replacement logic that can’t be expressed as a fixed replacement string, implement IReplacingCallback and its single Replacing(args) method, then assign the implementation to FindReplaceOptions.ReplacingCallback (or pass it directly to the FindReplaceOptions(replacingCallback) constructor). The callback receives a ReplacingArgs object for each match, exposing Match (the underlying regular-expression match), MatchNode / MatchEndNode (the document nodes containing the match), MatchOffset, and a settable Replacement string. Returning a ReplaceAction value from the callback — Replace, Skip, or Stop — controls whether that particular match is replaced, left alone, or halts the entire find/replace operation.

Tips and Best Practices

• Call Replace() on Document.Range for document-wide replacement, or on a narrower Range (such as a single section’s range) to scope the operation.
• Set FindWholeWordsOnly = true to avoid matching a search term as a substring of a longer word.
• Use IgnoreFieldCodes = true when you want replacement to operate on displayed field results, not on the underlying field instruction text.
• Prefer IReplacingCallback over post-processing when the replacement text depends on the match context (surrounding node, formatting, or position) rather than being a fixed string.
• Return ReplaceAction.Stop from a callback to end a find/replace operation early once a condition is met, rather than processing every remaining match.

Common Issues

FAQ

Does Range.Replace() support regular expressions?

Yes — the pattern argument is a regular expression, matched against the range’s text.

How do I replace text only within a specific section, not the whole document?

Call Replace() on that section’s Range instead of Document.Range.

How do I make replacement text depend on what was matched?

Implement IReplacingCallback, read the match details from ReplacingArgs, set ReplacingArgs.Replacement to the computed text, and return ReplaceAction.Replace.

Can find/replace search backward through the document?

Yes — set FindReplaceOptions.Direction to FindReplaceDirection.Backward.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation