Handle errors

Every failure DocWright raises derives from DocWrightException (namespace DocWright.Core), so one catch handles them all. Catch the specific types first when you want to respond differently, for example to tell a user that their upload is not a Word document.

The code

using DocWright;
using DocWright.Core;

var converter = new DocWrightConverter();

var options = new ConvertOptions();
options.Limits.MaxInputBytes = 50L * 1024 * 1024;          // refuse inputs over 50 MB
options.Limits.MaxWallClockTime = TimeSpan.FromSeconds(30);

try
{
    using FileStream input = File.OpenRead("upload.docx");
    using var output = new MemoryStream();
    converter.Convert(input, output, options);
}
catch (ResourceLimitExceededException ex)
{
    Console.WriteLine($"Too big or too slow: {ex.LimitName} = {ex.ObservedValue}");
}
catch (InvalidDocumentException ex)
{
    Console.WriteLine($"Not a document we can read: {ex.Message}");
}
catch (DocWrightException ex)
{
    // Every DocWright failure derives from DocWrightException.
    Console.WriteLine($"Conversion failed: {ex.Message}");
}

Output, for an upload that is not a document:

Not a document we can read: No registered document reader recognized the input stream.

The exception types

Exception	Thrown when
`InvalidDocumentException`	The input is not a document DocWright can read, or an edit was refused.
`ResourceLimitExceededException`	A limit in `ConvertOptions.Limits` was exceeded. `LimitName` and `ObservedValue` say which and by how much.
`DocumentEncryptedException`	The document is encrypted and no password was given, or the scheme is not supported.
`InvalidPasswordException`	A password was given and it is wrong.
`DocumentIntegrityException`	The password was right but the encrypted content was altered or truncated.
`FontResolutionException`	A required font could not be found or substituted.
`UnsupportedFeatureException`	`StrictMode` is on and the document uses something DocWright cannot render. `DiagnosticCode` says what.
`OutputConformanceException`	PDF/A was requested and the document cannot meet it.
`MergeTemplateException`	A mail-merge template is malformed. `RegionName` says where.
`ContentControlEditException`, `ContentControlBindingException`, `FormFieldEditException`	An edit to a content control or form field was refused, and nothing was changed.

Protect a service with limits

A document from outside your organisation can be built to exhaust memory, disk or time. The classic example is a ZIP bomb disguised as a .docx. ConvertOptions.Limits caps every expensive dimension, and any cap that trips throws ResourceLimitExceededException instead of taking the process down.

Set at least these two for anything uploaded:

options.Limits.MaxInputBytes    = 50L * 1024 * 1024;          // refuse inputs over 50 MB
options.Limits.MaxWallClockTime = TimeSpan.FromSeconds(30);   // give up after 30 seconds

Some limits are already on by default, because their worst case does not depend on file size: password-hashing spin counts, and nesting, object and decompression limits for PDF input. Hardening untrusted input lists every limit and its default.

Degradations are reported, not thrown

Most documents contain something no renderer draws perfectly: a missing font, an unsupported effect. DocWright does not fail on these. It renders the best result it can and reports a diagnostic you can log. Set ConvertOptions.Diagnostics to collect them, or turn on StrictMode to throw UnsupportedFeatureException instead. Diagnostics shows both.

You have the basics. Continue with a tutorial, or browse the guides for a specific task.

Table of Contents

Handle errors

The code

The exception types

Protect a service with limits

Degradations are reported, not thrown

Next