API Host Exceptions

Exceptions and Diagnostics

Overview of the AuroraScript host exception hierarchy and the diagnostic types it carries.

Back to .NET Host API Reference

Overview

AuroraScript's exception hierarchy starts with AuroraException. Compilation failures use AuroraCompilationException and its diagnostics; runtime failures use AuroraRuntimeException and script stack frames.

Each exception page documents the full member list; this page shows how the types fit together at a host boundary.

Quick Reference

Type	Thrown by	Carries
AuroraException	Any engine operation	Message and optional inner exception.
AuroraCompilationException	BuildAsync, CompileBlock	One or more AuroraCompilationDiagnostic entries.
AuroraRuntimeException	Execute, closure invocation	Module name, line, and AuroraStackTrace frames.

try
{
    await engine.BuildAsync("main.as");
    using var domain = engine.CreateDomain();
    domain.Execute("MAIN", "run");
}
catch (AuroraCompilationException ex)
{
    Console.Error.WriteLine($"{ex.FileName}:{ex.LineNumber}:{ex.ColumnNumber}");
    Console.Error.WriteLine(ex.FirstDiagnostic.Message);
}
catch (AuroraRuntimeException ex)
{
    Console.Error.WriteLine($"{ex.ModuleName}:{ex.LineNumber}");
    foreach (var frame in ex.StackTrace)
        Console.Error.WriteLine(frame);
}

AuroraException

AuroraException()
AuroraException(string message)
AuroraException(string message, Exception innerException)

Base engine exception.

Parameters

Name	Type	Required	Description
message	string	No	Error description.
innerException	Exception	No	Optional inner exception.

Returns

A new AuroraException instance.

throw new AuroraException("Engine configuration is invalid.");

AuroraCompilationException

AuroraCompilationException(IEnumerable<AuroraCompilationDiagnostic> diagnostics)

Aggregate compilation exception.

Parameters

Name	Type	Required	Description
diagnostics	IEnumerable<AuroraCompilationDiagnostic>	Yes	One or more diagnostics.

Returns

A new AuroraCompilationException instance.

Members

Diagnostics, Count, FirstDiagnostic, FileName, LineNumber, ColumnNumber, and ToString() read all or the first compilation diagnostic plus display-friendly file and location details.

catch (AuroraCompilationException ex)
{
    Console.WriteLine($"{ex.FileName}:{ex.LineNumber}:{ex.ColumnNumber}");
    Console.WriteLine(ex.Diagnostics[0].Message);
}

AuroraCompilationDiagnostic

Members

Message, Location, FileName, LineNumber, ColumnNumber, and ToString() provide the error text, its SourceSpan, and a display location.

AuroraCompilationDiagnostic diagnostic = ex.FirstDiagnostic;
Console.WriteLine(diagnostic.ToString());

AuroraRuntimeException

AuroraRuntimeException(Exception ex, IReadOnlyList<AuroraStackTrace> stackTrace)
AuroraRuntimeException(string message)
AuroraRuntimeException(ScriptError error)

Runtime exception with script context.

Parameters

Name	Type	Required	Description
ex	Exception	Yes	Underlying exception. Required by the first overload.
stackTrace	IReadOnlyList<AuroraStackTrace>	Yes	Script stack frames. Required by the first overload.
message	string	Yes	Error description. Required by the second overload.
error	ScriptError	Yes	Script error value. Required by the third overload.

Returns

A new AuroraRuntimeException instance.

Members

ModuleName, LineNumber, StackTrace, and ToString() display the runtime error origin, line, and script call stack.

catch (AuroraRuntimeException ex)
{
    Console.WriteLine($"{ex.ModuleName}:{ex.LineNumber}");
    foreach (var frame in ex.StackTrace) Console.WriteLine(frame);
}

SourceSpan

Members

None, StartLine, StartColumn, EndLine, EndColumn, Offset, Length, FileName, and ToString() describe a source range. See SourceSpan.

var location = diagnostic.Location;
Console.WriteLine($"{location.FileName}:{location.StartLine}:{location.StartColumn}");

AuroraStackTrace

AuroraStackTrace(string path, string method, int line)

Single script stack frame.

Parameters

Name	Type	Required	Description
path	string	Yes	Script path.
method	string	Yes	Method name.
line	int	Yes	Line number.

Members

FileName, FullPath, Method, Line, and ToString(). See AuroraStackTrace.

var frame = new AuroraStackTrace("scripts/main.as", "run", 12);
Console.WriteLine(frame.ToString());