951c7da4b7
* Modify rule S3416: add C# and VB.NET * Add logging frameworks to the list of allowed frameworks * Reverse adding logging frameworks * Fix issues from adoc validation * Review 1 * Fix tabbing * Review 2 * Add list of supported frameworks * Missed renames * Add 'logging' tag * Remove VB.NET * Fix a minor typo --------- Co-authored-by: Gregory Paidis <gregory.paidis@sonarsource.com> Co-authored-by: Gregory Paidis <115458417+gregory-paidis-sonarsource@users.noreply.github.com>
57 lines
2.6 KiB
Plaintext
57 lines
2.6 KiB
Plaintext
== Why is this an issue?
|
|
|
|
It is a well-established convention to name each logger after its enclosing type. This rule raises an issue when the convention is not respected.
|
|
|
|
include::{language}/why-code-example.adoc[]
|
|
|
|
Not following such a convention can result in confusion and logging misconfiguration.
|
|
|
|
For example, the person configuring the log may attempt to change the logging behavior for the `MyNamespace.EnclosingType` type, by overriding defaults for the logger named after that type.
|
|
|
|
[source,json]
|
|
----
|
|
{
|
|
"Logging": {
|
|
"LogLevel": {
|
|
"Default": "Error",
|
|
"MyNamespace.EnclosingType": "Debug"
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
However, if the convention is not in place, the override would not affect logs from `MyNamespace.EnclosingType`, since they are made via a logger with a different name.
|
|
|
|
Moreover, using the same logger name for multiple types prevents the granular configuration of each type's logger, since there is no way to distinguish them in configuration.
|
|
|
|
The rule targets the following logging frameworks:
|
|
* https://learn.microsoft.com/en-us/dotnet/core/extensions/logging[Microsoft Extensions Logging]
|
|
* https://logging.apache.org/log4net/[Apache log4net]
|
|
* https://nlog-project.org/[NLog]
|
|
|
|
=== Exceptions
|
|
|
|
The rule doesn't raise issues when custom handling of logging names is in place, and the logger name is not derived from a `Type`.
|
|
|
|
include::{language}/why-exception-example.adoc[]
|
|
|
|
include::{language}/how.adoc[]
|
|
|
|
== Resources
|
|
|
|
=== Documentation
|
|
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/core/diagnostics/logging-tracing[.NET logging and tracing]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line#log-category[Logging in C# and .NET - Log category]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line#configure-logging[Logging in C# and .NET - Configure logging]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.ilogger-1[ILogger<TCategoryName> Interface]
|
|
* Apache Logging - https://logging.apache.org/log4net/[Apache log4net]
|
|
* NLog - https://nlog-project.org/[Flexible & free open-source logging for .NET]
|
|
|
|
=== Articles & blog posts
|
|
|
|
* Raygun Blog - https://raygun.com/blog/c-sharp-logging-best-practices/[C# logging: Best practices in 2023 with examples and tools]
|
|
* Apache Logging - https://logging.apache.org/log4net/release/manual/configuration.html[Apache log4net Manual - Configuration]
|
|
* GitHub NLog repository - https://github.com/nlog/nlog/wiki/Tutorial#best-practices-for-using-nlog[Best practices for using NLog]
|
|
|
|
include::rspecator-dotnet.adoc[] |