Importing Nodes with NodeImporter

Importing Nodes with NodeImporter

This guide shows how to move content between two different Document instances in Aspose.Words FOSS for .NET using the dedicated NodeImporter class and fine-grained ImportFormatOptions, for scenarios where you need to import many nodes efficiently or control import behavior beyond the basic ImportFormatMode choice. For the simpler Document.ImportNode, Document.AppendDocument, and DocumentBuilder.InsertDocument convenience methods, see the Working with Documents guide.

NodeImporter: Repeated Imports Without Repeated Setup

NodeImporter is built for repeated import of nodes from one document to another, avoiding the per-call setup cost of a single-use import. Construct one with new NodeImporter(srcDoc, dstDoc, importFormatMode) — or the overload new NodeImporter(srcDoc, dstDoc, importFormatMode, importFormatOptions) for finer control — once, then call ImportNode(srcNode, isImportChildren) on that same instance for every node you need to bring across. Reusing one NodeImporter instance across many calls avoids the setup cost that a per-call convenience import incurs each time.

Fine-Grained Import Control with ImportFormatOptions

ImportFormatOptions supplements the basic ImportFormatMode choice (UseDestinationStyles, KeepSourceFormatting, KeepDifferentStyles) with finer switches: SmartStyleBehavior (bool) controls how styles with equal names in the source and destination are imported. KeepSourceNumbering (bool) controls how numbering is imported when it clashes between source and destination. IgnoreTextBoxes and IgnoreHeaderFooter (bool) suppress source formatting for textbox and header/footer content specifically when KeepSourceFormatting is in effect. MergePastedLists (bool) merges pasted lists with surrounding lists instead of keeping them separate. ForceCopyStyles (bool) copies conflicting styles instead of reusing the destination’s version, in KeepSourceFormatting mode. AdjustSentenceAndWordSpacing (bool) automatically adjusts spacing. AppendDocumentWithNewPage (bool) forces the first imported section’s type to NewPage.

Tips and Best Practices

• Create a single NodeImporter instance and reuse it across a loop of ImportNode calls when importing many nodes — constructing a new importer per node repeats setup work unnecessarily.
• Pass an ImportFormatOptions instance to the NodeImporter constructor overload when the plain ImportFormatMode choice isn’t precise enough — for example, to keep source list numbering with KeepSourceNumbering while still using KeepSourceFormatting overall.
• Set IgnoreTextBoxes or IgnoreHeaderFooter when KeepSourceFormatting pulls in more source styling than you want for just those content types.
• NodeImporter.ImportNode(srcNode, isImportChildren) mirrors the document-level import call in signature and behavior; the difference is reuse efficiency, not import semantics.

Common Issues

FAQ

When should I use NodeImporter instead of a single import call?

When importing many nodes in a loop — construct one NodeImporter up front and call ImportNode repeatedly, rather than paying setup cost on each call.

What does ImportFormatOptions add beyond ImportFormatMode?

Finer switches such as SmartStyleBehavior, KeepSourceNumbering, IgnoreTextBoxes, IgnoreHeaderFooter, MergePastedLists, ForceCopyStyles, AdjustSentenceAndWordSpacing, and AppendDocumentWithNewPage, layered on top of the base ImportFormatMode choice.

Does NodeImporter.ImportNode behave differently from importing at the document level?

No — both take a source node and an isImportChildren flag and import it into the destination document; NodeImporter exists so that setup is done once and reused across many calls.

How do I keep the source document’s list numbering intact when importing?

Construct NodeImporter with an ImportFormatOptions where KeepSourceNumbering is true.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation