Class DbCommandLoggerExtensions

Namespace

Wolfgang.Extensions.Logging.Data

Assembly

Wolfgang.Extensions.Logging.Data.dll

Extension methods on ILogger for logging a SQL command's text alongside its parameters, with opt-in redaction of sensitive parameter values.

public static class DbCommandLoggerExtensions

Inheritance

object

DbCommandLoggerExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Two parameter-supplying styles are provided:

• An explicit IReadOnlyDictionary<TKey, TValue> of parameter name to value — the lowest-overhead path.
• A Dapper-style anonymous object (e.g. new { id = 1, name = "abc" }) — its public readable properties are reflected into a dictionary and then logged via the dictionary path. Per-type property accessors are cached so the reflection cost is paid once per parameter type, not once per call.

Parameter-name matching for excludedParameterNames is case-insensitive and prefix-tolerant: @name, :name, ?name, and name are all treated as the same parameter, so a connection's ADO.NET prefix convention does not have to be known by the caller. The value of an excluded parameter is replaced with *** in the logged output; the parameter name itself is preserved so the shape of the command is still visible.

Methods

LogCommandText(ILogger, string, IReadOnlyDictionary<string, object?>)

Logs the commandText and its parameters at LogLevel.Information.

public static void LogCommandText(this ILogger logger, string commandText, IReadOnlyDictionary<string, object?> parameters)

Parameters

logger ILogger

The logger to write to.

commandText string

The SQL command text.

parameters IReadOnlyDictionary<string, object>

The command parameters, keyed by name.

Examples

var p = new Dictionary<string, object?> { ["id"] = 1, ["password"] = "hunter2" };
logger.LogCommandText("SELECT * FROM Users WHERE Id = @id", p, new[] { "password" });

Exceptions

ArgumentNullException

Thrown when logger, commandText, or parameters is null.

LogCommandText(ILogger, string, IReadOnlyDictionary<string, object?>, LogLevel)

Logs the commandText and its parameters at the specified level.

public static void LogCommandText(this ILogger logger, string commandText, IReadOnlyDictionary<string, object?> parameters, LogLevel level)

Parameters

logger ILogger

The logger to write to.

commandText string

The SQL command text.

parameters IReadOnlyDictionary<string, object>

The command parameters, keyed by name.

level LogLevel

The log level to write the entry at.

Exceptions

ArgumentNullException

Thrown when logger, commandText, or parameters is null.

LogCommandText(ILogger, string, IReadOnlyDictionary<string, object?>, IEnumerable<string>)

Logs the commandText and its parameters at LogLevel.Information, redacting the values of any parameters named in excludedParameterNames.

public static void LogCommandText(this ILogger logger, string commandText, IReadOnlyDictionary<string, object?> parameters, IEnumerable<string> excludedParameterNames)

Parameters

logger ILogger

The logger to write to.

commandText string

The SQL command text.

parameters IReadOnlyDictionary<string, object>

The command parameters, keyed by name.

excludedParameterNames IEnumerable<string>

Parameter names whose values should be redacted. Matching is case-insensitive and prefix-tolerant (@name, :name, ?name, name are equivalent).

Exceptions

ArgumentNullException

Thrown when logger, commandText, parameters, or excludedParameterNames is null.

LogCommandText(ILogger, string, IReadOnlyDictionary<string, object?>, IEnumerable<string>, LogLevel)

Logs the commandText and its parameters at the specified level, redacting the values of any parameters named in excludedParameterNames.

public static void LogCommandText(this ILogger logger, string commandText, IReadOnlyDictionary<string, object?> parameters, IEnumerable<string> excludedParameterNames, LogLevel level)

Parameters

logger ILogger

The logger to write to.

commandText string

The SQL command text.

parameters IReadOnlyDictionary<string, object>

The command parameters, keyed by name.

excludedParameterNames IEnumerable<string>

Parameter names whose values should be redacted. Matching is case-insensitive and prefix-tolerant (@name, :name, ?name, name are equivalent).

level LogLevel

The log level to write the entry at.

Exceptions

ArgumentNullException

Thrown when logger, commandText, parameters, or excludedParameterNames is null.

LogCommandText(ILogger, string, object)

Logs the commandText and the public readable properties of the anonymous (or any) parameters object at LogLevel.Information.

[RequiresUnreferencedCode("The anonymous-object parameter overload reflects over the runtime type's public properties, which the trimmer cannot statically preserve. In trimmed / Native AOT applications, pass an IReadOnlyDictionary<string, object?> instead.")]
public static void LogCommandText(this ILogger logger, string commandText, object parameters)

Parameters

logger ILogger

The logger to write to.

commandText string

The SQL command text.

parameters object

An object whose public readable properties become the command parameters — e.g. new { id = 1, name = "abc" }.

Examples

logger.LogCommandText(
    "SELECT * FROM Users WHERE Id = @id",
    new { id = 1, password = "hunter2" },
    new[] { "password" });

Exceptions

ArgumentNullException

Thrown when logger, commandText, or parameters is null.

LogCommandText(ILogger, string, object, LogLevel)

Logs the commandText and the public readable properties of the parameters object at the specified level.

[RequiresUnreferencedCode("The anonymous-object parameter overload reflects over the runtime type's public properties, which the trimmer cannot statically preserve. In trimmed / Native AOT applications, pass an IReadOnlyDictionary<string, object?> instead.")]
public static void LogCommandText(this ILogger logger, string commandText, object parameters, LogLevel level)

Parameters

logger ILogger

The logger to write to.

commandText string

The SQL command text.

parameters object

An object whose public readable properties become the command parameters.

level LogLevel

The log level to write the entry at.

Exceptions

ArgumentNullException

Thrown when logger, commandText, or parameters is null.

LogCommandText(ILogger, string, object, IEnumerable<string>)

Logs the commandText and the public readable properties of the parameters object at LogLevel.Information, redacting the values of any properties named in excludedParameterNames.

[RequiresUnreferencedCode("The anonymous-object parameter overload reflects over the runtime type's public properties, which the trimmer cannot statically preserve. In trimmed / Native AOT applications, pass an IReadOnlyDictionary<string, object?> instead.")]
public static void LogCommandText(this ILogger logger, string commandText, object parameters, IEnumerable<string> excludedParameterNames)

Parameters

logger ILogger

The logger to write to.

commandText string

The SQL command text.

parameters object

An object whose public readable properties become the command parameters.

excludedParameterNames IEnumerable<string>

Parameter names whose values should be redacted. Matching is case-insensitive and prefix-tolerant (@name, :name, ?name, name are equivalent).

Exceptions

ArgumentNullException

Thrown when logger, commandText, parameters, or excludedParameterNames is null.

LogCommandText(ILogger, string, object, IEnumerable<string>, LogLevel)

Logs the commandText and the public readable properties of the parameters object at the specified level, redacting the values of any properties named in excludedParameterNames.

[RequiresUnreferencedCode("The anonymous-object parameter overload reflects over the runtime type's public properties, which the trimmer cannot statically preserve. In trimmed / Native AOT applications, pass an IReadOnlyDictionary<string, object?> instead.")]
public static void LogCommandText(this ILogger logger, string commandText, object parameters, IEnumerable<string> excludedParameterNames, LogLevel level)

Parameters

logger ILogger

The logger to write to.

commandText string

The SQL command text.

parameters object

An object whose public readable properties become the command parameters.

excludedParameterNames IEnumerable<string>

Parameter names whose values should be redacted. Matching is case-insensitive and prefix-tolerant (@name, :name, ?name, name are equivalent).

level LogLevel

The log level to write the entry at.

Exceptions

ArgumentNullException

Thrown when logger, commandText, parameters, or excludedParameterNames is null.

LogDbCommand(ILogger, DbCommand)

Logs a live DbCommand — its CommandText and the name/value pairs of its Parameters — at LogLevel.Information.

public static void LogDbCommand(this ILogger logger, DbCommand command)

Parameters

logger ILogger

The logger to write to.

command DbCommand

The command to log.

Examples

using var command = connection.CreateCommand();
command.CommandText = "SELECT * FROM Users WHERE Id = @id";
logger.LogDbCommand(command);

Exceptions

ArgumentNullException

Thrown when logger or command is null.

LogDbCommand(ILogger, DbCommand, LogLevel)

Logs a live DbCommand at the specified level.

public static void LogDbCommand(this ILogger logger, DbCommand command, LogLevel level)

Parameters

logger ILogger

The logger to write to.

command DbCommand

The command to log.

level LogLevel

The log level to write the entry at.

Exceptions

ArgumentNullException

Thrown when logger or command is null.

LogDbCommand(ILogger, DbCommand, IEnumerable<string>)

Logs a live DbCommand at LogLevel.Information, redacting the values of any parameters named in excludedParameterNames.

public static void LogDbCommand(this ILogger logger, DbCommand command, IEnumerable<string> excludedParameterNames)

Parameters

logger ILogger

The logger to write to.

command DbCommand

The command to log.

excludedParameterNames IEnumerable<string>

Parameter names whose values should be redacted. Matching is case-insensitive and prefix-tolerant (@name, :name, ?name, name are equivalent).

Exceptions

ArgumentNullException

Thrown when logger, command, or excludedParameterNames is null.

LogDbCommand(ILogger, DbCommand, IEnumerable<string>, LogLevel)

Logs a live DbCommand at the specified level, redacting the values of any parameters named in excludedParameterNames.

public static void LogDbCommand(this ILogger logger, DbCommand command, IEnumerable<string> excludedParameterNames, LogLevel level)

Parameters

logger ILogger

The logger to write to.

command DbCommand

The command to log.

excludedParameterNames IEnumerable<string>

Parameter names whose values should be redacted. Matching is case-insensitive and prefix-tolerant (@name, :name, ?name, name are equivalent).

level LogLevel

The log level to write the entry at.

Exceptions

ArgumentNullException

Thrown when logger, command, or excludedParameterNames is null.