Class LogDefinition

Namespace

LogAssertions

Assembly

LogAssertions.dll

The captured shape of one log call: event ID, level, message template, formatted placeholder values, and exception. Created via Capture(Action<ILogger>), which invokes a logging delegate once against a private probe logger and records what it emitted, so a [LoggerMessage] source-generated definition (or any other log call) becomes a reusable, string-free assertion value. Store instances in static readonly fields and match them on the assertion chain via Matching(definition), or build filters directly with Matching(LogDefinition).

public sealed class LogDefinition

Inheritance

object

LogDefinition

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Examples

private static readonly LogDefinition OrderShipped =
    LogDefinition.Capture(log => LogMessages.OrderShipped(log, 0, ""));

await Assert.That(collector).HasLogged().Matching(OrderShipped).Once();

The argument values inside the Capture(Action<ILogger>) lambda are throwaway: identity matching keys on the event ID (numeric ID plus name) and the message template, never on the argument values or the level. To additionally pin argument values, chain WithProperty, or use the exact-call form (MatchingCall on the chain / MatchingCall(LogDefinition)).

Remarks

Identity requires the message template to match; two definitions that share a numeric event ID are still distinguished by their templates. The residual ambiguity: two [LoggerMessage] methods with the same method name (in different classes, both with generator-assigned IDs) and the same template: produces log records that are indistinguishable by design, because the records themselves carry identical identity.

The probe invocation is side-effect free: a [LoggerMessage] method only formats and logs to the logger it is handed, and Capture(Action<ILogger>) hands it a throwaway in-memory logger. Production code never references this package; the capture lambda executes the production logging method in the test process only.

Properties

Exception

The exception instance the captured call supplied, or null.

public Exception? Exception { get; }

Property Value

Exception

Id

The captured event ID: numeric ID plus event name. For a [LoggerMessage] definition the name is the method name and the numeric ID is the attribute's EventId (or a stable generator-assigned value when omitted).

public EventId Id { get; }

Property Value

EventId

Level

The level the captured call logged at. Not part of identity matching: a definition taking LogLevel as a runtime parameter would capture the probe call's level, so level constraints belong on the chain (AtLevel etc.).

public LogLevel Level { get; }

Property Value

LogLevel

Properties

The captured placeholder key/value pairs (formatted strings, invariant culture; {OriginalFormat} excluded), in capture order.

public IReadOnlyList<KeyValuePair<string, string?>> Properties { get; }

Property Value

IReadOnlyList<KeyValuePair<string, string>>

Template

The captured message template (the pre-substitution {OriginalFormat} value), or null when the call carried none.

public string? Template { get; }

Property Value

string

Methods

Capture(Action<ILogger>)

Invokes invocation once against a private probe logger and returns the captured call shape. The probe collects every level (including disabled-level records), so an IsEnabled gate inside generated logging code cannot suppress the capture.

public static LogDefinition Capture(Action<ILogger> invocation)

Parameters

invocation Action<ILogger>

A delegate that performs exactly one log call on the supplied logger: typically a [LoggerMessage] method invocation with throwaway argument values. Must be non-null.

Returns

LogDefinition

The captured shape.

Exceptions

ArgumentNullException

invocation is null.

ArgumentException

invocation logged zero records (nothing to capture) or more than one record (ambiguous: pass a lambda that emits exactly one log call).

ToString()

Renders the identity as Name#Id "template" (name falls back to ? when the record carried none), for failure-message descriptions and diagnostics.

public override string ToString()

Returns

string

The rendered identity.