This is the online documentation for PostSharp 5.0.
Download PDF or CHM. Go to v4.3 or v5.0

Adding Detailed Logging to your Solution

When you're working with your codebase, it's common to need to add logging either as a non-functional requirement or simply to assist during the development process. In either situation, you will want to include information about the parameters passed to the method when it was called as well as the parameter values once the method call has completed. This can be a tedious and brittle process. As you work and refactor methods, the order and types of parameters may change, parameters may be added and some maybe removed. Along with performing these refactorings, you have to remember to update the logging messages to keep them in sync. This is something that is easy to forget, and once forgotten, the output of the logging is much less useful.

Logging is one of the examples of a boilerplate code. Performing logging imperatively not only leads to the problems with refactoring mentioned above. It also makes your code harder to understand.

PostSharp offers a solution to all of these problems. PostSharp Logging allows you to configure where logging should be performed and takes over the task of keeping your log entries in sync as you add, remove and refactor your codebase. Using the PostSharp Logging does not require to change your codebase allowing you to keep the production code clearly understandable with no boilerplate code.

Let's take a look at how you can add a trace logging for the start and completion of method calls.

This topic contains the following sections:

Step 1. Adding logging to your projects

To add logging to a specific project:

  1. Add a reference to the PostSharp.Patterns.Diagnostics package to your project.

  2. Create a source code file where you will add all project-wise aspects. We suggest to name this file GlobalAspects.cs.

    Add the following content to this file:

    C#
    using PostSharp.Patterns.Diagnostics;
    using PostSharp.Extensibility;
    
    [assembly: Log(AttributePriority = 1, AttributeTargetMemberAttributes = MulticastAttributes.Protected | MulticastAttributes.Internal | MulticastAttributes.Public)]
    [assembly: Log(AttributePriority = 2, AttributeExclude = true, AttributeTargetMembers = "get_*" )]

    This code adds logging to all methods except private methods and except property getters. You can edit this code to target methods relevant to your scenarios. See Adding Aspects to Code for details.

PostSharp will now add logging before and after the execution of all methods targeted by the logging aspect.

Note Note

If there are several projects in your solution, repeat this procedure for each project. Note that you can share the GlobalAspects.cs file among several projects.

The next step is to configure logging at run-time. You should at least determine using which logging framework the records should be written. We call this concept the logging back-end.

Step 2. Choose your logging back-end
Step 3. Configure PostSharp logging at run-time

To configure logging:

  1. Identify the startup method of your solution. In a console application and an ASP.NET Core application, the startup method is usually named Program.Main. In a XAML application, this is the Startup event handler. In an ASP.NET application, this is the Application_Start method in the Global.asax source file.

  2. To the startup project, add a reference to the package containing the implementation of your logging back-end, as listed in the table above.

  3. Import the PostSharp.Patterns.Diagnostics namespace in the startup file.

    C#
    using PostSharp.Patterns.Diagnostics;
  4. Add the following code on the top of the startup method:

    C#
    LoggingServices.DefaultBackend = new Patterns.Diagnostics.Backends.Console.ConsoleLoggingBackend();

    In the code snippet above, you can replace ConsoleLoggingBackend by any of the logging back-ends.

  5. It is essential that you configure logging before any logged type (i.e. any type containing a logged method or field) is initialized, otherwise TypeInitializationException will be thrown at build time. Therefore, you should add the following custom attribute on the top of the startup class:

    C#
    [Log(AttributeExclude = true)]
    class Program
    {
    // ...
    }

    Important note Important

    You should exclude the logging aspect from any class that is executed before you set up and configure the back-end. If this is too cumbersome, you can create a module initializer for your startup project using the ModuleInitializerAttribute aspect.

Step 4. Configure your logging framework.

Remember that PostSharp emits records to the logging framework of your choice. Some of these frameworks may need additional configuration. Please refer to the documentation of the logging framework for details.

Result

Now that you have added logging to your project method, you will get a super-detailed log of your program execution, including parameter values and return values. You are able to add, remove, or rename a method or its parameters with the confidence that your log entries will be kept in sync with each of those changes. Adding logging to your codebase and maintaining it becomes a very easy task.

See Also