Configuration Options Reference

Configuration Options Reference

Most loading, saving, and conversion operations in Aspose.PDF FOSS for .NET accept an *Options object that configures the behavior of that operation. LoadOptions and SaveOptions are the two abstract roots of this family: every format-specific loader (HtmlLoadOptions, MdLoadOptions, TxtLoadOptions, SvgLoadOptions) derives from LoadOptions, and every format-specific writer (PdfSaveOptions, HtmlSaveOptions, SvgSaveOptions) derives from SaveOptions. This page explains how the family fits together and documents the options classes not already covered by the Conversion and Optimization guide.

Loading Documents with LoadOptions

Every *LoadOptions subclass shares WarningHandler, WarningHandlerName, DisableFontLicenseVerifications, and LoadFormat from the LoadOptions base class, then adds properties specific to its source format.

// HTML: resolve relative images/CSS against a base path
var htmlOptions = new HtmlLoadOptions("assets/");
htmlOptions.IsEmbedFonts = true;
using var htmlDoc = new Document("input.html", htmlOptions);

// Markdown: apply custom CSS while rendering to PDF
var mdOptions = new MdLoadOptions();
mdOptions.CssStyles = "body { font-family: sans-serif; }";
using var mdDoc = new Document("input.md", mdOptions);

// Plain text: control the rendered font size
var txtOptions = new TxtLoadOptions();
txtOptions.FontSize = 11;
using var txtDoc = Document.Open("input.txt", txtOptions);

// SVG: let the page size follow the artwork dimensions
var svgOptions = new SvgLoadOptions();
svgOptions.AdjustPageSize = true;
using var svgDoc = new Document("input.svg", svgOptions);

Saving to PDF with PdfSaveOptions

PdfSaveOptions controls font handling and temporary-file placement when writing a Document back out as PDF. It inherits CloseResponse, SaveFullPath, WarningHandler, CacheGlyphs, and SaveFormat from the shared SaveOptions base.

using var doc = Document.Open("input.pdf");

var pdfOptions = new PdfSaveOptions();
pdfOptions.DefaultFontName = "Arial";
pdfOptions.TempPath = "temp/";

doc.Save("output.pdf", pdfOptions);

Exporting to HTML and SVG

HtmlSaveOptions and SvgSaveOptions both derive from UnifiedSaveOptions. Beyond the image/font/layout controls covered in the conversion guide, HtmlSaveOptions also lets you pick the document flavor and pagination strategy, while SvgSaveOptions relies entirely on the inherited SaveOptions/UnifiedSaveOptions members.

using var doc = Document.Open("input.pdf");

// Fixed-layout HTML5 output, split one file per page
var htmlOptions = new HtmlSaveOptions(HtmlDocumentType.Html5, fixedLayout: true);
htmlOptions.SplitIntoPages = true;
htmlOptions.ImageResolution = 150;
htmlOptions.Title = "Converted Document";
doc.Save("output.html", htmlOptions);

// SVG export configured through the shared SaveOptions members
var svgOptions = new SvgSaveOptions();
svgOptions.SaveFullPath = false;
doc.Save("output.svg", svgOptions);

One-Step Conversion with Document.Convert

Document.Convert accepts a source LoadOptions and destination SaveOptions together in a single static call, so you can convert between formats without manually opening, converting, and disposing a Document.

var loadOptions = new HtmlLoadOptions();
var saveOptions = new PdfSaveOptions();

Document.Convert("input.html", loadOptions, "output.pdf", saveOptions);

Text Extraction Options

TextExtractionOptions controls how TextAbsorber (and TextDevice) format extracted text, independent of which absorber or device class performs the extraction.

using var doc = Document.Open("input.pdf");

var extractionOptions = new TextExtractionOptions(TextFormattingMode.Raw);
extractionOptions.ScaleFactor = 1.0;
extractionOptions.IgnoreResourceFontErrors = true;

var absorber = new TextAbsorber(extractionOptions);
doc.Pages[1].Accept(absorber);

string text = absorber.Text;

Optimizing Output with OptimizationOptions

OptimizationOptions is a separate, format-independent mechanism for reducing file size. It is applied through Document.OptimizeResources, not through a *SaveOptions class, so it can be combined with any save path.

using var doc = Document.Open("input.pdf");

var optimizationOptions = new OptimizationOptions();
optimizationOptions.RemoveUnusedObjects = true;
optimizationOptions.CompressObjects = true;
optimizationOptions.SubsetFonts = true;
optimizationOptions.ImageCompressionOptions.CompressImages = true;
optimizationOptions.ImageCompressionOptions.ImageQuality = 80;

doc.OptimizeResources(optimizationOptions);
doc.Save("optimized.pdf");

Tips and Best Practices

• Every *LoadOptions and *SaveOptions subclass inherits WarningHandler/WarningHandlerName - set both together to capture recoverable diagnostics.
• Prefer a format-specific *LoadOptions/*SaveOptions instance over relying on extension-based format inference, especially when working with streams instead of file paths.
• Use Document.Convert(srcFileName, loadOptions, dstFileName, saveOptions) for one-shot conversions instead of manually opening and re-saving a Document.
• OptimizationOptions is independent of the *SaveOptions family - call OptimizeResources before Save to shrink output regardless of target format.
• Reuse a single options instance across multiple documents when the same settings apply, rather than reconstructing it each time.

Common Issues

FAQ

What is the difference between LoadOptions and SaveOptions?

LoadOptions configures how a document is read from a non-PDF source format (HTML, Markdown, text, SVG); SaveOptions configures how a Document is written to an output format (PDF, HTML, SVG). Every format-specific options class derives from exactly one of these two roots.

Do I need to specify LoadOptions when opening a native PDF?

No. Document.Open and the Document constructor accept a plain file path or stream for native PDF input. *LoadOptions subclasses are only required when importing a non-PDF source format such as HTML, Markdown, text, or SVG.

Can I reuse the same SaveOptions instance across multiple Save calls?

Yes. An options instance is just a plain configuration object; it holds no per-document state, so the same PdfSaveOptions or HtmlSaveOptions instance can be passed to Save for several documents that share the same settings.

How is OptimizationOptions different from the format-specific SaveOptions classes?

OptimizationOptions is consumed by Document.OptimizeResources, a separate step from saving. It removes unused objects/streams and recompresses images in place, and can be applied before calling Save with any *SaveOptions subclass.

Does every source/target format have both a LoadOptions and a SaveOptions class?

Not necessarily symmetric. For example, Markdown and plain text currently expose MdLoadOptions/TxtLoadOptions for import but no matching *SaveOptions counterpart, reflecting which direction each format is supported for conversion.

API Reference Summary

See Also

• Conversion and Optimization
• Aspose.PDF for .NET Enterprise Product