Loading Documents with LoadOptions

Loading Documents with LoadOptions

This guide shows how to control document loading beyond a bare file path or stream, using the LoadOptions class. Document has constructor overloads that accept a LoadOptions instance — Document(fileName, loadOptions) and Document(stream, loadOptions) — so any of the settings described here apply at load time, before the document object is handed back to your code.

The LoadOptions Class

LoadOptions carries the settings Aspose.Words FOSS needs while loading a document into a Document object. Its constructors include a parameterless LoadOptions(), LoadOptions(password) for opening a password-protected file directly, and LoadOptions(loadFormat, password, baseUri) for specifying the format explicitly. Beyond Password and BaseUri (used to resolve relative references such as linked resources), LoadOptions exposes Encoding for text-based formats, TempFolder for large-document processing, MswVersion to specify which Word version’s format conventions apply, and UpdateDirtyFields, IgnoreOleData, and UseSystemLcid for finer control over load behavior. LoadOptions.FontSettings lets you supply FontSettings at load time rather than configuring fonts only after the document is loaded.

Format-Specific Load Options

Some formats have their own LoadOptions subclass exposing settings specific to that format. TxtLoadOptions (for plain text) adds AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection, and separate LeadingSpacesOptions/TrailingSpacesOptions of type TxtLeadingSpacesOptions/TxtTrailingSpacesOptions for controlling how leading and trailing whitespace on each line is handled. MarkdownLoadOptions adds PreserveEmptyLines, ImportUnderlineFormatting, and SoftLineBreakCharacter for controlling how Markdown’s line-break conventions map onto document paragraphs and runs. Both subclasses inherit every general LoadOptions property, so a password or resource-loading callback set on a TxtLoadOptions or MarkdownLoadOptions instance behaves the same as on the base class.

Resource Loading Callbacks

LoadOptions.ResourceLoadingCallback accepts an implementation of IResourceLoadingCallback, which is notified as the loader resolves external resources referenced by the document being loaded. The callback receives a ResourceLoadingArgs describing the ResourceType of the resource being loaded, and returns a ResourceLoadingAction to tell the loader whether to load the resource normally, skip it, or substitute custom data. This is the extension point for controlling or intercepting resource resolution during loading, independent of which format is being read.

Language, Direction, and Recovery Settings

LoadOptions.LanguagePreferences is a LanguagePreferences object whose DefaultEditingLanguage (an EditingLanguage enum value) sets the language Aspose.Words FOSS assumes when a document doesn’t specify one explicitly; AddEditingLanguage(language) and AddEditingLanguages(languages) register additional languages the document may use. DocumentDirection (also exposed directly on TxtLoadOptions) is an enum with LeftToRight, RightToLeft, and Auto values for controlling text flow direction on load. LoadOptions.RecoveryMode takes a DocumentRecoveryMode value, which controls how the loader responds when it encounters a malformed or partially corrupt document.

Progress and Warning Callbacks

Beyond resource loading, LoadOptions.WarningCallback and LoadOptions.ProgressCallback accept callback implementations that are notified of non-fatal issues encountered while loading and of load progress, respectively — useful for surfacing recoverable problems to calling code or reporting progress on large documents without polling.

Tips and Best Practices

• Pass LoadOptions(password) (or set LoadOptions.Password) rather than catching a load exception and retrying — Aspose.Words FOSS needs the password before it can parse the document at all.
• Set LanguagePreferences.DefaultEditingLanguage when loading documents whose language metadata is missing or unreliable, so downstream language-dependent processing behaves predictably.
• Prefer the format-specific options class (TxtLoadOptions, MarkdownLoadOptions) over the base LoadOptions when loading those formats, since the specific subclass exposes format-relevant settings the base class does not.
• Implement IResourceLoadingCallback when you need to redirect, cache, or block external resource resolution during loading rather than after the document is already in memory.
• Set LoadOptions.RecoveryMode deliberately for pipelines that process documents from untrusted or third-party sources, rather than relying on default recovery behavior.

Common Issues

FAQ

How do I load a password-protected document?

Construct LoadOptions with the password — new LoadOptions(password) — or set LoadOptions.Password, then pass it to new Document(fileName, loadOptions) or new Document(stream, loadOptions).

Do I need a format-specific LoadOptions subclass, or is the base class enough?

The base LoadOptions class covers settings common to every format (password, encoding, callbacks). Use a format-specific subclass such as TxtLoadOptions or MarkdownLoadOptions when you need settings specific to that format, such as whitespace handling for text files or line-break conventions for Markdown.

How do I intercept or redirect resources a document references while loading?

Implement IResourceLoadingCallback and assign it to LoadOptions.ResourceLoadingCallback before loading. The callback receives a ResourceLoadingArgs per resource and returns a ResourceLoadingAction deciding how the loader proceeds.

How do I control what language Aspose.Words FOSS assumes for a loaded document?

Set LoadOptions.LanguagePreferences.DefaultEditingLanguage to an EditingLanguage value before loading; use AddEditingLanguage/AddEditingLanguages to register additional languages the document may contain.

What happens if the loader encounters a malformed document?

Behavior is controlled by LoadOptions.RecoveryMode, a DocumentRecoveryMode value that determines how the loader responds to structural problems in the source document.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation