API Host TypedDocumentException

TypedDocumentException

TDoc diagnostic exception

命名空间：AuroraScript.Runtime.Serialization。类型：sealed class，继承 AuroraException。适用版本：4.0.0。

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

.NET Host API 目录 · TDoc 格式

.NET Host API Directory · TDoc Format

介绍

Introduction

TypedDocumentException 表示 TDoc 的语法、类型绑定、值范围，或无法安全继续的宿主写入配置错误。它在普通 Message 之外提供来源、行列和数据路径，便于宿主将错误显示给配置作者或写入日志。

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.

该异常由 TypedDocumentSerializer 与 AuroraTypedDocument 抛出；TDoc.parse 与 TDoc.stringify 在脚本侧会将它转换为 AuroraRuntimeException。

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

快速开始

Quick Start

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);
}

成员

Members

string SourceName

返回诊断来源名称。直接文本 API 的默认值是 "<tdoc>"；使用 ReadFile 时，来源会自动为文件路径。

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>

int Line

返回一基行号。对于来自文本的语法或绑定错误，值大于零；对于仅在写入配置时发现的错误，可能为 0。

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

一基行号，或 0。

One-based line number, or 0.

简单示例

Simple Example

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

int Column

返回一基列号。语义与 Line 相同：写入配置错误可能为 0。

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

Parameters:

• 无。

  None.

Returns

一基列号，或 0。

One-based column number, or 0.

简单示例

Simple Example

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

string DataPath

返回相对于根值的数据路径。根为 $，对象属性使用 .name，数组元素使用 [index]。

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 数据路径。

TDoc data path.

简单示例

Simple Example

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

错误处理建议

Error-handling Guidance

• 显示 Message 时保留 SourceName、Line、Column 与 DataPath，避免只显示底层异常文本。

  Preserve SourceName, Line, Column, and DataPath when displaying Message, rather than showing only underlying exception text.

• 不要在捕获后通过反射或替代别名重试 CLR/CIL 类型；应修正宿主注册或文档契约。

  Do not retry CLR/CIL types through reflection or an alternate alias after catching this error; fix the host registration or document contract.

• 文件、权限、编码和流异常不是此类型的一部分，应按相应的 .NET I/O 异常处理。

  File, permission, encoding, and stream errors are not this type and should be handled as their corresponding .NET I/O exceptions.

相关 API

Related APIs

• TypedDocumentSerializer

  TypedDocumentSerializer

• AuroraTypedDocument

  AuroraTypedDocument

• TypedDocumentOptions

  TypedDocumentOptions