43 lines
3.7 KiB
Plaintext
43 lines
3.7 KiB
Plaintext
== Why is this an issue?
|
|
|
|
The https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace.writelineif[`Trace.WriteLineIf` Method] from the https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace[`System.Diagnostic.Trace`] facility writes a trace if the condition passed as the first parameter is `true`.
|
|
|
|
https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.traceswitch[`TraceSwitch`] allows trace control via `bool` properties for each relevant https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.tracelevel[`TraceLevel`], such as https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.traceswitch.traceerror[`TraceSwitch.TraceError`].
|
|
|
|
Using `Trace.WriteLineIf` with such properties should be avoided since it can lead to misinterpretation and produce confusion.
|
|
|
|
In particular, `Trace.WriteLineIf` may appear as equivalent to the level-specific tracing methods provided by `Trace`, such as https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace.traceerror[`Trace.Error`], but it is not.
|
|
|
|
The difference is that `Trace.WriteLineIf(switch.TraceError, ...)` conditionally writes the trace, based on the switch, whereas `Trace.TraceError` always writes the trace, no matter whether `switch.TraceError` is `true` or `false`.
|
|
|
|
Moreover, unlike `Trace.TraceError`, `Trace.WriteLineIf(switch.TraceError, ...)` would behave like `Trace.WriteLine(...)` when `switch.TraceError` is `true`, writing unfiltered to the underlying trace listeners and not categorizing the log entry by level, as described more in detail in S6670.
|
|
|
|
== How to fix it
|
|
|
|
The fix depends on the intent behind the use of https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.traceswitch[`TraceSwitch`] levels with https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace.writelineif[`Trace.WriteLineIf`].
|
|
|
|
If it is *trace categorization*, level-specific tracing methods, such as https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace.traceerror[`Trace.TraceError`] or https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace.tracewarning[`Trace.TraceWarning]`, should be used instead.
|
|
|
|
If it is *trace filtering*, https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.tracesource[`TraceSource`] should be used instead.
|
|
|
|
If it is *log filtering*, `Trace` should be replaced by logging APIs, such as the https://learn.microsoft.com/en-us/dotnet/core/diagnostics/logging-tracing#net-logging-apis[`ILogger` API].
|
|
|
|
Modern logging APIs are also more suitable than `Trace` when https://learn.microsoft.com/en-us/dotnet/core/extensions/high-performance-logging[high-performance logging] is required.
|
|
|
|
== Resources
|
|
|
|
=== Documentation
|
|
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace.writelineif[`Trace.WriteLineIf` Method]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.traceswitch[`TraceSwitch`]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.tracesource[`TraceSource`]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace.writeline[`Trace.WriteLine` Method]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/core/extensions/high-performance-logging[High-performance logging in .NET]
|
|
|
|
=== Articles & blog posts
|
|
|
|
* StackOverflow - https://stackoverflow.com/a/5118040[Difference between Trace.WriteLineIf and Trace.Error]
|
|
* StackOverflow - https://stackoverflow.com/a/3691841[Difference between TraceSwitch and SourceSwitch]
|
|
* InfoSupport Blogs - https://blogs.infosupport.com/please-be-careful-when-using-trace-writelineif/[Please be careful when using Trace.WriteLineIf()]
|
|
|
|
include::rspecator.adoc[] |