Table of Contents

Class LogFilter

Namespace
LogAssertions
Assembly
LogAssertions.dll

Static factory for composable ILogRecordFilter instances. The fluent chain on HasLogged()/HasNotLogged()/HasLoggedSequence() creates filters internally; this class exposes the same primitives for users who want to build reusable filter objects, share them across tests, or compose them via All(params ILogRecordFilter[]) / Any(params ILogRecordFilter[]) / Not(ILogRecordFilter).

public static class LogFilter
Inheritance
LogFilter
Inherited Members

Examples

// Reusable filter shared across many tests:
static readonly ILogRecordFilter CriticalDbError = LogFilter.All(
    LogFilter.AtLevel(LogLevel.Critical),
    LogFilter.WithException<DbException>());

// Use via WithFilter on the assertion chain:
await Assert.That(collector).HasLogged().WithFilter(CriticalDbError).AtLeast(1);

Methods

All(params ILogRecordFilter[])

Conjunction: records matching every one of filters.

public static ILogRecordFilter All(params ILogRecordFilter[] filters)

Parameters

filters ILogRecordFilter[]

The filters to AND together. May be empty (matches every record).

Returns

ILogRecordFilter

A filter accepting records that match every child filter.

Exceptions

ArgumentNullException

filters is null.

Any(params ILogRecordFilter[])

Disjunction: records matching any one of filters.

public static ILogRecordFilter Any(params ILogRecordFilter[] filters)

Parameters

filters ILogRecordFilter[]

The filters to OR together. May be empty (matches no record).

Returns

ILogRecordFilter

A filter accepting records that match at least one child filter.

Exceptions

ArgumentNullException

filters is null.

AtLevel(LogLevel)

Records at exactly level.

public static ILogRecordFilter AtLevel(LogLevel level)

Parameters

level LogLevel

The log level to match.

Returns

ILogRecordFilter

A filter accepting records whose level equals level.

AtLevel(params LogLevel[])

Records whose level is any of levels.

public static ILogRecordFilter AtLevel(params LogLevel[] levels)

Parameters

levels LogLevel[]

The set of log levels to match. Must be non-null.

Returns

ILogRecordFilter

A filter accepting records whose level appears in the set.

Exceptions

ArgumentNullException

levels is null.

AtLevelOrAbove(LogLevel)

Records whose level is greater than or equal to level.

public static ILogRecordFilter AtLevelOrAbove(LogLevel level)

Parameters

level LogLevel

The minimum log level (inclusive).

Returns

ILogRecordFilter

A filter accepting records at or above the specified level.

AtLevelOrBelow(LogLevel)

Records whose level is less than or equal to level.

public static ILogRecordFilter AtLevelOrBelow(LogLevel level)

Parameters

level LogLevel

The maximum log level (inclusive).

Returns

ILogRecordFilter

A filter accepting records at or below the specified level.

Containing(string, StringComparison)

Records whose formatted message contains substring.

public static ILogRecordFilter Containing(string substring, StringComparison comparison)

Parameters

substring string

The substring to look for. Must be non-null.

comparison StringComparison

The string comparison.

Returns

ILogRecordFilter

A filter accepting records whose message contains the substring.

Exceptions

ArgumentNullException

substring is null.

ContainingAll(StringComparison, params string[])

Records whose formatted message contains every one of substrings.

public static ILogRecordFilter ContainingAll(StringComparison comparison, params string[] substrings)

Parameters

comparison StringComparison

The string comparison.

substrings string[]

The substrings; the message must contain all of them.

Returns

ILogRecordFilter

A filter accepting records whose message contains every substring.

Exceptions

ArgumentNullException

substrings is null.

ContainingAny(StringComparison, params string[])

Records whose formatted message contains any one of substrings.

public static ILogRecordFilter ContainingAny(StringComparison comparison, params string[] substrings)

Parameters

comparison StringComparison

The string comparison.

substrings string[]

The substrings; the message must contain at least one.

Returns

ILogRecordFilter

A filter accepting records whose message contains at least one substring.

Exceptions

ArgumentNullException

substrings is null.

Matching(Regex)

Records whose formatted message matches pattern.

public static ILogRecordFilter Matching(Regex pattern)

Parameters

pattern Regex

The regular expression. Must be non-null.

Returns

ILogRecordFilter

A filter accepting records whose message matches the regex.

Exceptions

ArgumentNullException

pattern is null.

Not(ILogRecordFilter)

Logical negation: records that do not match filter.

public static ILogRecordFilter Not(ILogRecordFilter filter)

Parameters

filter ILogRecordFilter

The filter to negate. Must be non-null.

Returns

ILogRecordFilter

A filter accepting records the inner filter rejects.

Exceptions

ArgumentNullException

filter is null.

Where(Func<FakeLogRecord, bool>)

An arbitrary predicate over the full record.

public static ILogRecordFilter Where(Func<FakeLogRecord, bool> predicate)

Parameters

predicate Func<FakeLogRecord, bool>

The predicate. Must be non-null.

Returns

ILogRecordFilter

A filter accepting records satisfying the predicate.

Exceptions

ArgumentNullException

predicate is null.

WithCategory(string)

Records whose category equals category (ordinal).

public static ILogRecordFilter WithCategory(string category)

Parameters

category string

The full category name. Must be non-null.

Returns

ILogRecordFilter

A filter accepting records emitted by the specified category.

Exceptions

ArgumentNullException

category is null.

WithEventId(int)

Records whose Id equals eventId.

public static ILogRecordFilter WithEventId(int eventId)

Parameters

eventId int

The numeric event ID.

Returns

ILogRecordFilter

A filter accepting records with the matching event ID.

WithEventIdInRange(int, int)

Records whose Id is within the inclusive range min..max.

public static ILogRecordFilter WithEventIdInRange(int min, int max)

Parameters

min int

The minimum event ID (inclusive).

max int

The maximum event ID (inclusive). Must be greater than or equal to min.

Returns

ILogRecordFilter

A filter accepting records with event IDs in the range.

Exceptions

ArgumentOutOfRangeException

max is less than min.

WithEventName(string)

Records whose Name equals eventName (ordinal).

public static ILogRecordFilter WithEventName(string eventName)

Parameters

eventName string

The event name. Must be non-null.

Returns

ILogRecordFilter

A filter accepting records with the matching event name.

Exceptions

ArgumentNullException

eventName is null.

WithException()

Records whose Microsoft.Extensions.Logging.Testing.FakeLogRecord.Exception is non-null (any type).

public static ILogRecordFilter WithException()

Returns

ILogRecordFilter

A filter accepting records that carry any exception.

WithException(Func<Exception, bool>)

Records whose Microsoft.Extensions.Logging.Testing.FakeLogRecord.Exception satisfies predicate.

public static ILogRecordFilter WithException(Func<Exception, bool> predicate)

Parameters

predicate Func<Exception, bool>

The predicate. Receives the non-null exception or returns false when the record has no exception.

Returns

ILogRecordFilter

A filter accepting records whose exception satisfies the predicate.

Exceptions

ArgumentNullException

predicate is null.

WithExceptionMessage(string, StringComparison)

Records whose exception's message contains substring under the supplied comparison.

public static ILogRecordFilter WithExceptionMessage(string substring, StringComparison comparison)

Parameters

substring string

The substring to find in the exception's message. Must be non-null.

comparison StringComparison

The string comparison rules. Project convention: pass explicitly so culture / case behavior is never silently inherited from the runtime locale.

Returns

ILogRecordFilter

A filter accepting records whose exception message contains the substring.

Exceptions

ArgumentNullException

substring is null.

WithException<TException>()

Records whose Microsoft.Extensions.Logging.Testing.FakeLogRecord.Exception is assignable to TException.

public static ILogRecordFilter WithException<TException>() where TException : Exception

Returns

ILogRecordFilter

A filter accepting records whose exception is the specified type or a subclass.

Type Parameters

TException

The exception type.

WithInnerExceptionMessage(string, StringComparison)

Records whose InnerException's Message contains substring under the supplied comparison. Walks only one level.

public static ILogRecordFilter WithInnerExceptionMessage(string substring, StringComparison comparison)

Parameters

substring string

The substring to find in the inner exception's message. Must be non-null.

comparison StringComparison

The string comparison rules. Project convention: pass explicitly (no default) : every public string-matching API in this package requires the caller to pick the comparison so culture / case behavior is never silently inherited from the runtime locale.

Returns

ILogRecordFilter

A filter accepting records whose first-level inner exception's message contains the substring.

Exceptions

ArgumentNullException

substring is null.

WithInnerException<TInner>()

Records whose Microsoft.Extensions.Logging.Testing.FakeLogRecord.Exception wraps an InnerException assignable to TInner. Walks only one level (Exception.InnerException); deeper nesting is not searched.

public static ILogRecordFilter WithInnerException<TInner>() where TInner : Exception

Returns

ILogRecordFilter

A filter accepting records whose exception's first-level inner is the specified type or a subclass.

Type Parameters

TInner

The inner-exception type to look for.

Remarks

Designed for the common gRPC / RPC pattern where a transport exception (e.g. RpcException) wraps the underlying domain exception once. Composes with WithException<TException>() via All(params ILogRecordFilter[]).

WithMessage(Func<string, bool>)

Records whose formatted message satisfies predicate.

public static ILogRecordFilter WithMessage(Func<string, bool> predicate)

Parameters

predicate Func<string, bool>

The message predicate. Must be non-null.

Returns

ILogRecordFilter

A filter accepting records whose message satisfies the predicate.

Exceptions

ArgumentNullException

predicate is null.

WithMessageTemplate(string)

Records whose pre-substitution message template equals template.

public static ILogRecordFilter WithMessageTemplate(string template)

Parameters

template string

The exact template (the value MEL stores under {OriginalFormat}). Must be non-null.

Returns

ILogRecordFilter

A filter accepting records with the given template.

Exceptions

ArgumentNullException

template is null.

WithProperty(string, Func<string?, bool>)

Records whose structured-state value at key satisfies predicate.

public static ILogRecordFilter WithProperty(string key, Func<string?, bool> predicate)

Parameters

key string

The structured-state key. Must be non-null.

predicate Func<string, bool>

A predicate over the formatted value (string-typed; FakeLogRecord stores values as strings).

Returns

ILogRecordFilter

A filter accepting records whose structured-state value satisfies the predicate.

Exceptions

ArgumentNullException

A required argument is null.

WithProperty(string, string?)

Records containing a structured-state entry with the specified key and value.

public static ILogRecordFilter WithProperty(string key, string? value)

Parameters

key string

The structured-state key. Must be non-null.

value string

The expected formatted-string value (ordinal); may be null.

Returns

ILogRecordFilter

A filter accepting records whose structured-state entry matches.

Exceptions

ArgumentNullException

key is null.

WithProperty<T>(string, Func<T, bool>)

Records whose structured-state value at key parses to a T satisfying predicate.

public static ILogRecordFilter WithProperty<T>(string key, Func<T, bool> predicate) where T : IParsable<T>

Parameters

key string

The structured-state key. Must be non-null.

predicate Func<T, bool>

A predicate over the parsed typed value. Must be non-null.

Returns

ILogRecordFilter

A filter accepting records whose parsed structured-state value satisfies the predicate.

Type Parameters

T

The parsable value type. Must implement IParsable<TSelf>.

Remarks

The stored string is parsed back to T via TryParse(string, IFormatProvider, out TSelf) using InvariantCulture; a value that is absent or does not parse never matches.

Exceptions

ArgumentNullException

A required argument is null.

WithProperty<T>(string, T)

Records whose structured-state value at key parses to a T equal to value (compared via Default).

public static ILogRecordFilter WithProperty<T>(string key, T value) where T : IParsable<T>

Parameters

key string

The structured-state key. Must be non-null.

value T

The expected typed value.

Returns

ILogRecordFilter

A filter accepting records whose structured-state value parses to value.

Type Parameters

T

The parsable value type. Must implement IParsable<TSelf>.

Remarks

FakeLogRecord stores structured-state values as their formatted strings, so the stored string is parsed back to T via TryParse(string, IFormatProvider, out TSelf) using InvariantCulture. A value that is absent or does not parse never matches. The IParsable<TSelf> constraint keeps the round-trip AOT-safe (no reflection).

Exceptions

ArgumentNullException

key is null.

WithScopeProperties(IReadOnlyDictionary<string, object?>)

Records whose active scopes collectively contain every key/value pair in required. Each pair must match in some scope, but different pairs may match in different scopes (subset match across all active scopes).

public static ILogRecordFilter WithScopeProperties(IReadOnlyDictionary<string, object?> required)

Parameters

required IReadOnlyDictionary<string, object>

The required scope-property key/value pairs. Must be non-null.

Returns

ILogRecordFilter

A filter accepting records whose active scopes contain every required pair.

Remarks

The empty-dictionary case matches every record (vacuous truth) since every element of an empty set is satisfied. Comparison is via Equals(object, object) for values; keys are compared ordinal.

The dictionary is snapshotted on construction; mutating the input dictionary after the filter is created does not affect the filter's behaviour.

Exceptions

ArgumentNullException

required is null.

WithScopeProperty(string, Func<object?, bool>)

Records whose active scopes contain a property whose value satisfies predicate.

public static ILogRecordFilter WithScopeProperty(string key, Func<object?, bool> predicate)

Parameters

key string

The scope-property key. Must be non-null.

predicate Func<object, bool>

A predicate over the scope-property value.

Returns

ILogRecordFilter

A filter accepting records whose scope-property value satisfies the predicate.

Exceptions

ArgumentNullException

A required argument is null.

WithScopeProperty(string, object?)

Records whose active scopes contain a property with the specified key and value.

public static ILogRecordFilter WithScopeProperty(string key, object? value)

Parameters

key string

The scope-property key. Must be non-null.

value object

The expected scope-property value; compared via Equals(object, object).

Returns

ILogRecordFilter

A filter accepting records with a matching scope property.

Exceptions

ArgumentNullException

key is null.

WithScopeProperty<T>(string, Func<T, bool>)

Records whose active scopes contain a property at key whose value is a T satisfying predicate.

public static ILogRecordFilter WithScopeProperty<T>(string key, Func<T, bool> predicate)

Parameters

key string

The scope-property key. Must be non-null.

predicate Func<T, bool>

A predicate over the typed scope value. Must be non-null.

Returns

ILogRecordFilter

A filter accepting records whose typed scope-property value satisfies the predicate.

Type Parameters

T

The scope-property value type.

Remarks

A scope value whose runtime type is not T never reaches the predicate.

Exceptions

ArgumentNullException

A required argument is null.

WithScopeProperty<T>(string, T)

Records whose active scopes contain a property at key whose value is a T equal to value (compared via Default).

public static ILogRecordFilter WithScopeProperty<T>(string key, T value)

Parameters

key string

The scope-property key. Must be non-null.

value T

The expected typed value.

Returns

ILogRecordFilter

A filter accepting records with a matching typed scope property.

Type Parameters

T

The scope-property value type.

Remarks

Scope values keep their runtime type (unlike structured-state values, which are stored as strings), so the comparison is fully typed: a scope value of a different runtime type than T never matches. Use this in place of the WithScopeProperty(string, object?) object overload when the scope value is a known type (for example Guid or int) to avoid boxing-comparison boilerplate at the call site.

Exceptions

ArgumentNullException

key is null.

WithScope<TScope>()

Records emitted while a scope of type TScope was active.

public static ILogRecordFilter WithScope<TScope>()

Returns

ILogRecordFilter

A filter accepting records with an active scope of the specified type.

Type Parameters

TScope

The scope state type to match.

WithoutException()

Records whose Microsoft.Extensions.Logging.Testing.FakeLogRecord.Exception is null.

public static ILogRecordFilter WithoutException()

Returns

ILogRecordFilter

A filter accepting records that carry no exception.

Remarks

The complement of WithException(). Useful when a code path logs at a warning/error level but deliberately omits the exception object (for example a transport or wire library that records a null Exception when full-exception capture is disabled): asserting the absence of an exception is as meaningful as asserting its type.