Message Management

HiNc applications use three independent message categories. Each category serves a distinct purpose and should not be mixed.

Categories

1. Diagnostic — `IProgress<IMessage>`

Operation-scoped progress and diagnostic messages. The caller provides an IProgress<IMessage> sink to the callee, which reports progress, warnings, and errors through it. Every IMessage carries a Severity, a Category, and a filterable id.

Session-scoped: ShellProgress feeds the Session Message Panel; StepDiagnosticProgress retains step-anchored diagnostics and NcDiagnosticProgress retains NC-parsing diagnostics.
XML IO chain: XFactory threads IProgress<IMessage> through all deserialization calls so that parsing errors are reported to the caller rather than a global handler.
Script-level: ShellProgress exposes the session sink to user scripts.
Per-call: inject a MessageCollector to buffer one call's messages and read them back afterwards (e.g., to return them inline in an HTTP response).

Use the MessageUtil id-first helpers (SystemError, SystemWarning, ValidationWarning, ConfigurationWarning, …) to report typed messages.

2. UI Error Notification — `MessageBoardUtil`

Toast-style popups for immediate user attention (e.g., “File saved”, “Load failed”). MessageBoardUtil triggers the ShowMessageBoard event consumed by the GUI layer.

Note

MessageBoardUtil is not yet mature for all scenarios. In practice, ILogger with level-filtered treatment is often applied instead.

3. App Log — `ILogger`

Standard .NET ILogger for application-level logging. Use ActionProgress<T>.FromLogger to bridge IProgress<object> APIs to an ILogger instance:

IProgress<object> progress = ActionProgress<object>.FromLogger(logger);

This routes each reported IMessage (or raw Exception) to the appropriate log level (LogError, LogWarning, LogInformation) based on its severity.

Basic-Component / Utility Level

Low-level utilities (e.g., in Hi.Common, Hi.Geom) cannot assume which category the caller intends. These APIs accept Action<Exception> or IProgress<IMessage> as parameters so the caller decides how to handle messages:

await task.CatchExceptions(ex => progress?.Report(ex));

Design Rationale

Static/global message sinks mix the three categories, making it unclear whether a message is diagnostic, UI notification, or app log. The current pattern threads the handler explicitly through the call chain so each caller decides the appropriate category.

Table of Contents