Exceptions

A call to the TX Text Control .NET class library that can't be carried out ends with an exception. Standard .NET exceptions report a wrong argument or a call at the wrong time, and the library's own exception classes report errors of the text engine, the document filters, the license, table formulas and mail merge. The sections below name each exception, what throws it and how your code can react.

Exceptions at a Glance

TextEditorException, FilterException and LicenseLevelException were introduced in version 24.0, FormulaException and NumberFormatException in version 26.0. All of them derive from System.Exception.

Argument Exceptions

The class library throws ArgumentException, ArgumentNullException or ArgumentOutOfRangeException when a method receives a wrong parameter or a property is set to a wrong value. The reference names these cases:

A few members throw an exception without the reference naming its type: FrameBase.InsertionMode for a combination of FrameInsertionMode values that isn't allowed, and MergeBlockInfo.Apply and MergeBlockInfo.MergeFields on a MergeBlockInfo that wasn't created from an existing subtext part.

A header that may be missing is a typical case. Catch the exception instead of letting it end the request:

using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();
    tx.Load("letter.docx", StreamType.WordprocessingML);

    try
    {
        HeaderFooter header = tx.HeadersAndFooters.GetItem(HeaderFooterType.Header);
        Console.WriteLine($"The header has {header.Paragraphs.Count} paragraphs.");
    }
    catch (ArgumentException)
    {
        // The document has no header
        Console.WriteLine("The document has no header.");
    }
}

The code works as follows:

• ServerTextControl.HeadersAndFooters returns the headers and footers of the document.
• GetItem with HeaderFooterType Header throws an ArgumentException when the document has no header.

InvalidOperationException

InvalidOperationException means that the object isn't in a state in which the call is allowed. The reference doesn't list the members that throw it. When it occurs, check the order of your calls: an instance of ServerTextControl needs Create before any other member, as ServerTextControl explains.

TextEditorException

TextEditorException reports an error of the text engine while a document is edited. With the Core engine, creating the first ServerTextControl throws it with the message "The default font installation failed." when the Fonts folder of the package is missing next to the application. The Default Font Installation Failed shows the fix.

FilterException

FilterException is thrown when a document filter can't load, save or convert a document, for example by ServerTextControl.Load and ServerTextControl.Save. Its FilterException.Reason property names the cause as a value of FilterException.FilterError:

Filter the exception by its reason to handle the cases your application can resolve, such as a PDF document that needs a password:

using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();

    try
    {
        tx.Load("statement.pdf", StreamType.AdobePDF);
    }
    catch (FilterException exception) when (exception.Reason == FilterException.FilterError.InvalidPassword)
    {
        // Ask the user for the password and load the document again
        Console.WriteLine("The PDF document is protected with a password.");
    }
    catch (FilterException exception)
    {
        Console.WriteLine($"The document can't be loaded: {exception.Reason}");
    }
}

The code works as follows:

• The first catch block handles only the reason InvalidPassword; Load Password-Protected PDF Documents shows how to load the document with its password.
• The second catch block handles every other reason.

The message of a FilterException also contains an error number, which gives more detail than the reason. Text Control's Error Navigator looks it up, as the blog article Text Control Error Navigator Launched explains. Document Conversion in Troubleshooting covers the common conversion problems.

LicenseLevelException

LicenseLevelException is thrown when code uses a feature that the licensed product level doesn't include. Its message names the level the feature requires. A Feature Throws LicenseLevelException lists the messages and shows how to read the product level with GetVersionInfo.

FormulaException and NumberFormatException

Both exceptions report an error in a string of a table:

• FormulaException reports an invalid syntax or missing parameters in a formula, the value of TableCell.Formula.
• NumberFormatException reports an invalid syntax in a number format that displays a formula result, the value of TableCellFormat.NumberFormat.

Both have a CharacterIndex property, FormulaException.CharacterIndex and NumberFormatException.CharacterIndex, with the one-based index of the first invalid character in the string. Use it to point the user at the error. Tables shows how formulas and number formats are set, and Formula Functions lists the functions a formula can call.

Mail Merge Exceptions

MailMerge.Merge throws MergeCanceledException when a handler of the DataRowMerged event has set DataRowMergedEventArgs.Cancel to cancel the merge.

MailMerge.MergeJsonData throws a class derived from ParserException when the JSON string can't be parsed: UnexpectedEndOfInputException, UnexpectedTokenException, InvalidNumberFormatException, InvalidCodePointException, UnknownLiteralNameTokenException or UnknownParseErrorException. Catch ParserException to handle all of them; Data Sources shows the code.

Related Pages

• Classes by Task: the classes of the library sorted by task.
• Document Conversion: the reasons of a FilterException and their fixes.
• Licensing: license errors and LicenseLevelException.
• REST Services: turn exceptions into HTTP status codes.