/Anotar

Simplifies logging through a static class and some IL manipulation.

Primary LanguageC#MIT LicenseMIT

Icon

This is an add-in for Fody

Simplifies logging through a static class and some IL manipulation

Introduction to Fody

Supported Logging Libraries

Nuget

Explicit Logging

This example is targeting the NLog.

Your Code

public class MyClass
{
    void MyMethod()
    {
        Log.Debug("TheMessage");
    }
}

What gets compiled

In NLog

public class MyClass
{
    static Logger logger = LogManager.GetLogger("MyClass");

    void MyMethod()
    {
        logger.Debug("Method: 'Void MyMethod()'. Line: ~12. TheMessage");
    }
}

In Log4Net

public class MyClass
{
    static ILog logger = LogManager.GetLogger("MyClass");

    void MyMethod()
    {
        logger.Debug("Method: 'Void MyMethod()'. Line: ~12. TheMessage");
    }
}

In MetroLog

public class MyClass
{
    static ILogger logger = LogManagerFactory.DefaultLogManager.GetLogger("MyClass");

    void MyMethod()
    {
        logger.Debug("Method: 'Void :MyMethod()'. Line: ~24. TheMessage");
    }
}

In Serilog

public class MyClass
{
    static ILogger logger = Log.ForContext<MyClass>();

    void MyMethod()
    {
        logger
            .ForContext("MethodName", "Void Debug()")
            .ForContext("LineNumber", "8")
            .Debug("TheMessage");
    }
}

In Catel

public class MyClass
{
    static ILog logger = LogManager.GetLogger(typeof(MyClass));

    void MyMethod()
    {
        logger.WriteWithData("Method: 'Void MyMethod()'. Line: ~12. TheMessage", null, LogEvent.Debug);
    }
}

In Custom

public class MyClass
{
    static Logger logger = LoggerFactory.GetLogger<MyClass>();

    void MyMethod()
    {
        logger.Debug("Method: 'Void MyMethod()'. Line: ~12. TheMessage");
    }
}

Other Log Overloads in Explicit Logging

There are also appropriate methods for Warn, Info, Error etc as applicable to each of the logging frameworks.

Each of these methods has the expected 'message', 'params' and 'exception' overloads.

Exception Logging

Your code

[LogToErrorOnException]
void MyMethod(string param1, int param2)
{
    //Do Stuff
}

What gets compiled

In NLog

void MyMethod(string param1, int param2)
{
    try
    {
        //Do Stuff
    }
    catch (Exception exception)
    {
        if (logger.IsErrorEnabled)
        {
            var message = string.Format("Exception occurred in SimpleClass.MyMethod. param1 '{0}', param2 '{1}'", param1, param2);
            logger.ErrorException(message, exception);
        }
        throw;
    }
}

Custom Logging

The custom logging variant exist for several reasons

  1. Projects targeting an obscure logging libraries i.e. not NLog, MetroLog, SeriLog or Log4Net. Or wraps a logging library with a custom API.
  2. Projects that have their own logging custom logging libraries
  3. Projects that support multiple different logging libraries

It works by allowing you to have custom logger construction and a custom logger instance.

Expected factory and instance formats

Factory

The Logger Factory is responsible for building an instance of a logger.

  • Named LoggerFactory.
  • Namespace doesnt matter.
  • Have a static method GetLogger.

For example

public class LoggerFactory
{
    public static Logger GetLogger<T>()
    {
        return new Logger();
    }
}

Instance

The Logger instance is responsible for building an instance of a logger.

  • Name doesnt matter. It will be derived from the return type of LoggerFactory.GetLogger.
  • Must not be generic.
  • Namespace doesnt matter.
  • Can be either an interface, a concrete class or an abstract class.
  • Must contain the members listed below.

For example

public class Logger
{
    public void Debug(string format, params object[] args){}
    public void Debug(Exception exception, string format, params object[] args){}
    public bool IsDebugEnabled { get }
    public void Information(string format, params object[] args){}
    public void Information(Exception exception, string format, params object[] args){}
    public bool IsInformationEnabled { get  }
    public void Warning(string format, params object[] args){}
    public void Warning(Exception exception, string format, params object[] args){}
    public bool IsWarningEnabled { get }
    public void Error(string format, params object[] args){}
    public void Error(Exception exception, string format, params object[] args){}
    public bool IsErrorEnabled { get  }
    public void Fatal(string format, params object[] args){}
    public void Fatal(Exception exception, string format, params object[] args){}
    public bool IsFatalEnabled { get  }
}

Discovery

Current Assembly

If LoggerFactory and Logger exist in the current assembly they will be picked up automatically.

Other Assembly

If LoggerFactory and Logger exist in a different assembly You will need to use a [LoggerFactoryAttribute] to tell Anotar where to look.

[assembly: LoggerFactoryAttribute(typeof(MyUtilsLibrary.LoggerFactory))]

Nothing to deploy

After compilation the reference to the Anotar assemblies will be removed so you don't need to deploy the assembly.

But why? What purpose does this serve?

1. Dont make me think

When I am coding I often want to quickly add a line of logging code. If I dont already have the static logger field I have to jump back to the top of the file to add it. This breaks my train of thought. I know this is minor but it is still an annoyance. Static logging methods are much less disruptive to call.

2. I want some extra information

Often when I am logging I want to know the method and line number I am logging from. I don't want to manually add this. So using IL I just prefix the message with the method name and line number. Note that the line number is prefixed with '~'. The reason for this is that a single line of code can equate to multiple IL instructions. So I walk back up the instructions until I find one that has a line number and use that. Hence it is an approximation.

I don't want extra information

If you don't want the extra information, method name and line number, then add this to AssemblyInfo.cs:

[assembly: LogMinimalMessage]

Why not use CallerInfoAttributes

The CallerInfoAttributes consist of CallerLineNumberAttribute, CallerFilePathAttribute and CallerMemberNameAttribute. The allow you to pass information about the caller method to the callee method.

So some of this could be achieved using these attributes however there are a couple of points that complicate things.

1. Only .net 4.5 and up

So this makes it a little difficult to use with other runtimes.

2. Cant be used when passing arrays as params

Logging APIs all make use of params to pass arguments to a string.Format. Since you cant use params with CallerInfoAttributes most logging APIs choose not to use these attributes.

You can vote for Compatibility between params with CallerInfoAttributes

Icon

Icon courtesy of The Noun Project