Development documentation · Some APIs may be unreleased Published release →

Guides

Logging (development)

Neo.Logging.Abstractions.dll supplies provider-neutral contracts and helpers. Neo.Logging.dll supplies the synchronous default implementation and DI integration. Import Neo.Logging.*; the abstraction assembly references only System.Runtime. The implementation also references Neo.DependencyInjection.Abstractions. It preserves the generic state boundary of Microsoft.Extensions.Logging, following Raven's convention of interfaces without an I prefix.

Type Contract
LogLevel Trace=0, Debug=1, Information=2, Warning=3, Error=4, Critical=5, None=6. None never enables logging.
EventId Value with Id and optional Name. Constructors accept id or id/name. Equality and hashing use only Id; ToString uses Name when non-null, otherwise the numeric Id.
Logger Log<TState>(level, eventId, state, error, formatter), IsEnabled(level), BeginScope<TState>(state).
Logger<T> Logger with a declared category type.
LoggerProvider CreateLogger(categoryName) and Dispose.
LoggerFactory CreateLogger(categoryName), AddProvider(provider), Dispose.
DefaultLoggerFactory Empty provider set and Information threshold by default; overload accepts a minimum LogLevel, including None. Invalid thresholds fault.
DefaultLogger<T> Adapter constructed with a LoggerFactory; uses typeof(T).DisplayName as its category.
ConsoleLoggerProvider Default Console.WriteLine sink, or supplied (string) -> unit sink. Synchronous output; disposing disables its loggers and leaves the sink open.
NullLogger, NullLogger<T> Instance singleton; always disabled, never evaluates formatters, returns a reusable no-op scope.
NullLoggerFactory Instance singleton; returns NullLogger, ignores providers without taking ownership, and permits no-op disposal.

Log<TState> takes (TState, Error?) -> string as its formatter and an optional System.Error. The default factory filters before invoking providers; enabled providers decide when to render state. Each enabled console write produces level: category[id] message, followed by an optional formatted diagnostic on a new line. No stack trace is captured implicitly. Category and message retain UTF-8 text. Event names do not change numeric console event identifiers.

The factory caches category loggers using ordinal, case-sensitive names. Added providers immediately participate in existing categories. Every AddProvider registration transfers disposal ownership; registering twice produces two outputs and two disposal calls. Factory disposal is idempotent and disables existing aggregate loggers. CreateLogger and AddProvider after disposal fault.

BeginScope forwards state to every provider, including providers currently disabled for a severity. Null handles mean unsupported scopes. The aggregate handle disposes every returned handle once, in registration order. The default console provider does not render scopes. There is no ambient async scope flow.

LoggerExtensions provides literal Log overloads and LogTrace, LogDebug, LogInformation, LogWarning, LogError and LogCritical. Braces are literal text; message-template parsing is not implemented. LoggerFactoryExtensions adds CreateLogger<T>(); ConsoleLoggingExtensions adds AddConsole().

Try it

Create a factory, add the console provider, then write through a category logger. The factory owns its providers; use disposes them.

module Examples.Extensions.Introductions.Logging

import Neo.Logging.*

func Main() -> int {
    use factory = DefaultLoggerFactory()
    factory.AddConsole()
    let logger = factory.CreateLogger("Introduction")
    logger.LogInformation("Hello from logging")
    return 0
}

Complete sample project · Build and run instructions

Dependency injection

ServiceCollection.AddLogging() registers a container-owned singleton DefaultLoggerFactory and singleton open-generic Logger<> -> DefaultLogger<>. AddLogging(factory) registers a caller-owned factory instead. Both return Result<unit, ServiceError>, preserve existing registrations, and can be repeated. Resolve LoggerFactory to add providers during startup. Explicit typed logger registrations take precedence over the open-generic fallback.

Native reflection activation needs constructor retention for consumers, Neo.Logging.DefaultLoggerFactory, and Neo.Logging.DefaultLogger`1. The project builder accepts these exact names via --reflection-constructor-type.

The foundation requires serialized access. Configuration integration, concurrent mutation, ambient scopes, generated logging, provider exception aggregation and message templates remain gaps. Typed generic category spelling can differ from .NET; pass an explicit string category for a stable external name. See the design and comparison and feature overview.

The initial typed logger contract is invariant; .NET typed-category covariance and EventId implicit integer conversion are not yet provided. Scope generic parameters do not encode the CLR nullable-analysis notnull constraint.

Contracts, levels/EventId, DefaultLogger<T>, literal helpers and null implementations live in Neo.Logging.Abstractions; the default factory, console provider and DI registration remain in Neo.Logging. Namespaces stay unchanged; rebuild consumers after the assembly split. See the integrated sample.