Saving and Exporting Documents

Saving and Exporting Documents

Document.Save writes a document to a file or stream in a target format. The format is either inferred from a file extension, given explicitly as a SaveFormat value, or driven by a SaveOptions subclass — OoxmlSaveOptions, MarkdownSaveOptions, or TxtSaveOptions — for format-specific control. This guide covers the Save overloads, the SaveFormat enum, OOXML save options, Markdown and plain-text export, and detecting a format before converting.

Saving with Document.Save

The simplest call, Document.Save(fileName), infers the target format from the file’s extension. Save(fileName, saveFormat) makes the format explicit regardless of extension, and Save(fileName, saveOptions) (or the matching Stream overloads) accepts a SaveOptions subclass for format-specific settings. SaveOptions.CreateSaveOptions(saveFormat) is a static factory that returns the right options subclass for a given SaveFormat with its defaults already set.

Choosing a Format with SaveFormat

The SaveFormat enum lists every save-format identifier the library recognizes. Document.Save writes fully both to and from this edition’s core document formats — DOCX, DOCM, DOTX, DOTM, and Flat OPC (plus its macro-enabled and template variants) — as well as Markdown and plain text. FileFormatUtil.SaveFormatToExtension(saveFormat) and ExtensionToSaveFormat(extension) convert between the enum and a file extension string.

Some SaveFormat values exist in the enum for API completeness but correspond to formats this reduced, open-source edition does not implement a working reader or writer for — attempting to save to one of those produces output that isn’t equivalent to the source document. Stick to the formats named above for reliable round-tripping.

OOXML Options: DOCX, DOCM, DOTX, DOTM, and Flat OPC

OoxmlSaveOptions configures saving to any of the Open XML formats. Its SaveFormat property selects which specific variant to write; Password sets an open password on the saved file (independent of Document.Protect’s editing restrictions); Compliance selects the OOXML strictness level; and CompressionLevel / Zip64Mode control the underlying ZIP packaging. Construct one with new OoxmlSaveOptions(saveFormat) or via SaveOptions.CreateSaveOptions(saveFormat).

Exporting to Markdown

MarkdownSaveOptions controls a Markdown export: ListExportMode and LinkExportMode govern how lists and hyperlinks are rendered, ImagesFolder / ImagesFolderAlias control where extracted images are written and how they’re referenced, ExportImagesAsBase64 embeds them inline instead, and TableContentAlignment affects generated table markup. Pass a MarkdownSaveOptions instance to Document.Save(fileName, saveOptions) with a .md file name, or set its SaveFormat explicitly.

Exporting to Plain Text

TxtSaveOptions (via its base TxtSaveOptionsBase, shared with MarkdownSaveOptions) controls plain-text export: Encoding sets the character encoding, ParagraphBreak sets the line-ending string, MaxCharactersPerLine wraps long lines, SimplifyListLabels normalizes list bullets/numbers to plain characters, and PreserveTableLayout attempts to keep table columns aligned using spaces.

Detecting a Format Before Converting

Before converting a file whose format you don’t already know, FileFormatUtil.DetectFileFormat(fileName) returns a FileFormatInfo with the detected LoadFormat. Combine this with FileFormatUtil.LoadFormatToSaveFormat(loadFormat) to decide whether a round-trip through this edition’s supported formats is possible before attempting Document.Save.

Tips and Best Practices

• Use Save(fileName, saveOptions) instead of the plain Save(fileName, saveFormat) overload whenever you need to control format-specific behavior like Markdown list rendering or OOXML compression.
• Set OoxmlSaveOptions.Password for an open-password-protected file; that’s separate from Document.Protect, which restricts editing but does not encrypt the file.
• Choose MarkdownSaveOptions.ExportImagesAsBase64 for a single self-contained Markdown file, or ImagesFolder when you want a folder of extracted image files alongside the Markdown.
• Call SaveOptions.CreateSaveOptions(saveFormat) instead of picking the concrete options class manually when the target format is determined at runtime.
• Verify a target format with FileFormatUtil before conversion rather than relying on a bare file extension, which can be wrong or misleading.

Common Issues

FAQ

How do I save a document to a specific format regardless of its file extension?

Call Save(fileName, saveFormat) with an explicit SaveFormat value, or Save(fileName, saveOptions) with a matching SaveOptions subclass.

Which formats does this edition read and write both ways?

DOCX, DOCM, DOTX, DOTM, Flat OPC (plus its macro-enabled and template variants), Markdown, and plain text.

How do I password-protect a saved file?

Set Password on an OoxmlSaveOptions instance and pass it to Document.Save(fileName, saveOptions).

How do I control the line endings in an exported text file?

Set ParagraphBreak on a TxtSaveOptions instance before saving.

How do I check what format a file is before converting it?

Call FileFormatUtil.DetectFileFormat(fileName) and read the returned FileFormatInfo.LoadFormat.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation