NeedlrLoggerMessageAttribute

NexusLabs.Needlr.Logging

NeedlrLoggerMessageAttribute Class

Marks a partial method whose body Needlr will source-generate into a high-performance, cancellation-aware logging method.

public sealed class NeedlrLoggerMessageAttribute : System.Attribute

Inheritance System.Object 🡒 System.Attribute 🡒 NeedlrLoggerMessageAttribute

Example

using Microsoft.Extensions.Logging;
using NexusLabs.Needlr.Logging;

public partial class OrderService
{
    private readonly ILogger<OrderService> _logger;

    public OrderService(ILogger<OrderService> logger) => _logger = logger;

    // When 'error' is an OperationCanceledException, this logs nothing by default.
    [NeedlrLoggerMessage(EventId = 42, Level = LogLevel.Warning, Message = "Order {OrderId} failed")]
    public partial void LogOrderFailed(int orderId, Exception error);
}

Remarks

This attribute mirrors the surface of Microsoft.Extensions.Logging.LoggerMessageAttribute (EventId, EventName, Level, Message, SkipEnabledCheck) so migrating an existing [LoggerMessage] method is a near drop-in swap. The generated body reuses the public Microsoft.Extensions.Logging.LoggerMessage.Define(Microsoft.Extensions.Logging.LogLevel,Microsoft.Extensions.Logging.EventId,System.String) primitive — the same fast path the built-in generator targets — so there is no performance penalty for the common case.

The difference from the built-in attribute is the cancellation guard: when the method has a parameter assignable to System.Exception and that argument is a cancellation (an System.OperationCanceledException by default), the generated body consults NeedlrCancellationLogging and, by default, skips the log entirely. Cancellation is normal control flow in production code, so logging it as a warning or error is usually noise. The behavior can be globally overridden at startup (force-log or demote to a lower level) via NeedlrCancellationLogging.

The decorated method must be partial, return void, be non-generic, and live in a partial type. For an instance method, the containing type must expose an Microsoft.Extensions.Logging.ILogger field or property; for a static method, an Microsoft.Extensions.Logging.ILogger parameter supplies the logger.

This is a source-generation only feature. It requires the NexusLabs.Needlr.Logging package and the generator that ships with it.

Constructors

NeedlrLoggerMessageAttribute() Constructor

Initializes a new instance of the NeedlrLoggerMessageAttribute class. All values are supplied via the named properties.

public NeedlrLoggerMessageAttribute();

NeedlrLoggerMessageAttribute(int, LogLevel, string) Constructor

Initializes a new instance of the NeedlrLoggerMessageAttribute class with an event id, log level, and message template.

public NeedlrLoggerMessageAttribute(int eventId, Microsoft.Extensions.Logging.LogLevel level, string message);

Parameters

eventId System.Int32

The numeric event id assigned to the log entry.

level Microsoft.Extensions.Logging.LogLevel

The level at which the message is logged.

message System.String

The structured message template (e.g. "Order {OrderId} failed").

NeedlrLoggerMessageAttribute(LogLevel, string) Constructor

Initializes a new instance of the NeedlrLoggerMessageAttribute class with a log level and message template.

public NeedlrLoggerMessageAttribute(Microsoft.Extensions.Logging.LogLevel level, string message);

Parameters

level Microsoft.Extensions.Logging.LogLevel

The level at which the message is logged.

message System.String

The structured message template (e.g. "Order {OrderId} failed").

NeedlrLoggerMessageAttribute(string) Constructor

Initializes a new instance of the NeedlrLoggerMessageAttribute class with a message template. The Level defaults to Microsoft.Extensions.Logging.LogLevel.Information.

public NeedlrLoggerMessageAttribute(string message);

Parameters

message System.String

The structured message template (e.g. "Order {OrderId} failed").

Properties

NeedlrLoggerMessageAttribute.EventId Property

Gets or sets the numeric event id assigned to the generated log entry. Defaults to 0.

public int EventId { get; set; }

Property Value

System.Int32

NeedlrLoggerMessageAttribute.EventName Property

Gets or sets the event name assigned to the generated log entry. When null, the decorated method's name is used.

public string? EventName { get; set; }

Property Value

System.String

NeedlrLoggerMessageAttribute.Level Property

Gets or sets the level at which the message is logged. Defaults to Microsoft.Extensions.Logging.LogLevel.Information when not supplied via a constructor.

public Microsoft.Extensions.Logging.LogLevel Level { get; set; }

Property Value

Microsoft.Extensions.Logging.LogLevel

NeedlrLoggerMessageAttribute.Message Property

Gets or sets the structured message template. Placeholders (e.g. {OrderId}) bind to the method's non-exception parameters in declaration order, exactly as with the built-in attribute.

public string Message { get; set; }

Property Value

System.String

NeedlrLoggerMessageAttribute.SkipEnabledCheck Property

Gets or sets a value indicating whether the generated body omits the Microsoft.Extensions.Logging.ILogger.IsEnabled(Microsoft.Extensions.Logging.LogLevel) guard. Set to true only when the caller has already checked that the level is enabled. Defaults to false.

public bool SkipEnabledCheck { get; set; }

Property Value

System.Boolean