API Host TypedDocumentException

TypedDocumentException

TDoc diagnostic exception

Namespace: AuroraScript.Runtime.Serialization. Kind: sealed class inheriting AuroraException. Applies to 4.0.0.

Back to .NET Host API Reference

Overview

TypedDocumentException represents TDoc syntax, type-binding, value-range, or a host writing-configuration error that cannot safely continue. Beyond the normal Message, it provides source, line/column, and data-path information for configuration UIs and logs.

This exception is thrown by TypedDocumentSerializer and AuroraTypedDocument; TDoc.parse and TDoc.stringify convert it to AuroraRuntimeException on the script side.

Quick Reference

// Given a configured AuroraEngine named engine:
using System;

try
{
    _ = TypedDocumentSerializer.Deserialize(
        engine,
        "Object { Int8Array bytes [0, 255] }");
}
catch (TypedDocumentException error)
{
    Console.WriteLine($"{error.SourceName} {error.Line}:{error.Column} {error.DataPath}");
    Console.WriteLine(error.Message);
}

Properties

SourceName

string SourceName

Returns the diagnostic source name. The direct text API defaults to "<tdoc>"; ReadFile automatically uses the file path as its source.

Parameters

None.

Returns

Source name.

Simple Example

Console.WriteLine(error.SourceName); // <tdoc>

Line

int Line

Returns a one-based line number. It is greater than zero for syntax or binding errors from text; it can be 0 for an error discovered only while writing configuration.

Parameters

None.

Returns

One-based line number, or 0.

Simple Example

if (error.Line > 0)
{
    Console.WriteLine($"Line {error.Line}");
}

Column

int Column

Returns a one-based column number. Its behavior matches Line: writing-configuration errors can report 0.

Parameters

None.

Returns

One-based column number, or 0.

Simple Example

Console.WriteLine($"Column {error.Column}");

DataPath

string DataPath

Returns a data path relative to the root value. The root is $, object properties use .name, and array elements use [index].

Parameters

None.

Returns

TDoc data path.

Simple Example

if (error.DataPath == "$.bytes[1]")
{
    Console.WriteLine("The second byte is invalid.");
}

Error-handling Guidance

Preserve SourceName, Line, Column, and DataPath when displaying Message, rather than showing only underlying exception text. Do not retry CLR/CIL types through reflection or an alternate alias after catching this error; fix the host registration or document contract. File, permission, encoding, and stream errors are not this type and should be handled as their corresponding .NET I/O exceptions.

Related APIs

• TypedDocumentSerializer
• AuroraTypedDocument
• TypedDocumentOptions