Working with Document Settings

Working with Document Settings

Beyond content, a Word document carries application-level settings – legacy compatibility switches, hyphenation preferences, the stored mail-merge configuration, view options, and write-protection state. Aspose.Words FOSS for .NET exposes these through the Aspose.Words.Settings namespace and a handful of properties on Document. This page covers each settings group and what it does and does not control.

Compatibility Options

Document.CompatibilityOptions is a CompatibilityOptions instance holding dozens of boolean switches that reproduce specific older-Word layout and spacing behaviors – for example GrowAutofit, UseWord2010TableStyleRules, UseWord2002TableStyleRules, AdjustLineHeightInTable, AlignTablesRowByRow, NoExtraLineSpacing, SuppressSpacingAtTopOfPage, SpacingInWholePoints, UseFELayout, and BalanceSingleByteDoubleByteWidth. Set the properties you need directly to match a specific Word version’s rendering quirks in downstream tooling that reads the document.

Hyphenation Preferences

Document.HyphenationOptions is a HyphenationOptions instance (AutoHyphenation, ConsecutiveHyphenLimit, HyphenateCaps, HyphenationZone) that stores Word’s hyphenation preferences for the document. These properties round-trip the request; because this edition does not include the page-layout engine, Aspose.Words FOSS does not itself compute hyphenation breaks – Word applies them when it opens and paginates the file.

Mail Merge Configuration

Document.MailMergeSettings is a MailMergeSettings instance that stores the mail-merge configuration recorded in the document: MainDocumentType, CheckErrors, Destination, DataSource, DataType, Query, ConnectString, MailSubject, MailAsAttachment, ActiveRecord, and ViewMergedData, plus Clear() and Clone(). For external data sources connected through Word’s Office Data Source Object mechanism, MailMergeSettings.Odso exposes an Odso instance (DataSource, DataSourceType, TableName, ColumnDelimiter, FirstRowContainsColumnNames) whose FieldMapDatas (OdsoFieldMapDataCollection of OdsoFieldMapData: Name, MappedName, Column, Type) and RecipientDatas (OdsoRecipientDataCollection of OdsoRecipientData: Active, Column, Hash, UniqueTag) describe the field mapping and recipient list.

Document View Settings

Document.ViewOptions is a ViewOptions instance controlling how Word displays the file when it is opened: ViewType, ZoomType, ZoomPercent, DisplayBackgroundShape, DoNotDisplayPageBoundaries, and FormsDesign. These properties only affect Word’s own display of the document – they have no effect on how Aspose.Words FOSS itself processes it.

Write Protection

Document.WriteProtection is a WriteProtection instance (IsWriteProtected, ReadOnlyRecommended) with SetPassword() to establish a protection password and ValidatePassword() to check a candidate password against it.

Measurement Units

The MeasurementUnits enum specifies the unit of measurement Word should use in its interface for a document.

Tips and Best Practices

• CompatibilityOptions.OptimizeFor(MsWordVersion) is present on the class but its implementation is not complete in this build – it throws NotImplementedException. Set the individual CompatibilityOptions boolean properties you need directly instead of relying on OptimizeFor to apply a whole version profile at once.
• MailMergeSettings and Odso store the mail-merge configuration that was recorded in the document – reading and writing that configuration is supported, but executing a mail merge (populating fields from a live data source) is not included in this open-source edition.
• HyphenationOptions and ViewOptions are both display/UI preferences that Word itself applies – do not expect calling Document.Save() to change how the text wraps or appears based on these settings, since this edition does not include the page-layout engine.
• Call WriteProtection.SetPassword() before enabling IsWriteProtected, and use ValidatePassword() to check a candidate password rather than storing or comparing the raw string yourself.
• CompatibilityOptions, HyphenationOptions, MailMergeSettings, ViewOptions, and WriteProtection are all reachable directly from Document – there is no need to search the node tree for them.

Common Issues

FAQ

Can I use Aspose.Words FOSS to run an actual mail merge?

No. MailMergeSettings and Odso let you read and write the merge configuration stored in a document, but executing a mail merge – populating fields from a data source – is not included in this open-source edition.

Does CompatibilityOptions.OptimizeFor() work?

No – it throws NotImplementedException in this build. Set the individual CompatibilityOptions properties you need directly instead.

How do I password-protect a document against edits?

Call WriteProtection.SetPassword() on Document.WriteProtection, then set IsWriteProtected to enable protection.

Do HyphenationOptions and ViewOptions change how the document is laid out?

No. Both are stored preferences that Microsoft Word applies when it opens and displays the file. This edition does not include the page-layout engine, so these settings pass through without Aspose.Words FOSS itself computing layout from them.

API Reference Summary