Formatting Log Records

PostSharp offers several ways to customize the appearance and the content of log records. This article maps different customization scenarios to a procedure, then explains each procedure in detail.

Scenarios

Scenario	Procedure
Include execution time. Emit a warning when execution time exceeds a given threshold. Include source file and line information. Include information about which task or method is being awaited by the `await` operator.	Editing a build-time configuration (LoggingProfile) in postsharp.config.
Include parameter name, type, or value. Include return value. Include `this` parameter. Set the LogLevel.	Editing a build-time configuration (LoggingOptions) in postsharp.config.
Set the maximum length of a record. Set formatting options such as the delimiter character or the number of indentation spaces Include the type name, namespace, or name. Include exception details. Specify which exceptions should be logged.	Editing run-time options (TextLoggingBackendOptions or a derived class).
Change how parameter values of a specific type are rendered.	Implementing a custom formatter.
Change any other behavior.	Overriding a backend.

Editing a build-time configuration

Some configuration settings affect the way how PostSharp generates instructions. These settings can have an important effect on run-time execution speed or assembly size. These settings are defined in the postsharp.config file. This file can be private to a project or shared among several projects. See Configuring Projects Using postsharp.config for details about the postsharp.config file.

Because settings in postsharp.config affect code generation, you will have to rebuild your project after you modify this file.

In large applications, you may need to configure logging differently for different areas or layers in your application. For example, exceptions in the service that cleans up old data in the database can be logged with a "Warning" level, while exceptions in the customer-facing web service must be logged with the "Error" level.

PostSharp enables you to organize your logging options using Logging Profiles. You apply a given logging profile by providing its name as an argument for the constructor of the LogAttribute constructor.

Logging aspects are assigned to a default profile, as shown in the following table:

Aspect	Default logging profile
LogAttribute	`default`
LogExceptionAttribute	`exceptions`

To edit the default logging profile:

Open the file postsharp.config in your project. If it does not exist, create an XML file with the following content:
```
<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.postsharp.org/1.0/configuration">
</Project>
```
Note

If you create postsharp.config in a directory, the file will be used for any project located under that directory. This allows you to share the logging profile among several projects. See Configuring Projects Using postsharp.config for details.

Edit postsharp.config as in the following example:

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.postsharp.org/1.0/configuration">
  <Logging xmlns="clr-namespace:PostSharp.Patterns.Diagnostics;assembly:PostSharp.Patterns.Diagnostics">
    <Profiles>
      <LoggingProfile Name="default" IncludeSourceLineInfo="True">
        <DefaultOptions>
          <LoggingOptions IncludeParameterType="True"/>
        </DefaultOptions>
      </LoggingProfile>
    </Profiles>
  </Logging>
</Project>

See the documentation of the LoggingProfile and LoggingOptions classes for details.

To create and use a new logging profile:

Configure a logging profile in postsharp.config, but choose a different name than default, exceptions or audit.

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.postsharp.org/1.0/configuration">
  <Logging xmlns="clr-namespace:PostSharp.Patterns.Diagnostics;assembly:PostSharp.Patterns.Diagnostics">
    <Profiles>
      <LoggingProfile Name="detailed" IncludeSourceLineInfo="True" IncludeExecutionTime="True" IncludeAwaitedTask="True">
        <DefaultOptions>
          <LoggingOptions IncludeParameterType="True" IncludeThisValue="True"/>
        </DefaultOptions>
      </LoggingProfile>
    </Profiles>
  </Logging>
</Project>

Specify the profile name when you add the LogAttribute aspect to a method, type, or project.
```
[assembly: Log("detailed", AttributeTargetTypes = "My.Namespace.*", AttributePriority = 1, AttributeTargetMemberAttributes = MulticastAttributes.Public)]
```
Note

Alternatively, you can create a new aspect class and derive it from LogAttributeBase.

Editing run-time options

The run-time options are available on the Options property of the backend class. Each backend can expose a specific set of options.

Contrarily to the build-time options, the run-time options are not organized into profiles. They affect all profiles that use the backend you configure.

To edit run-time options, go to the startup method where PostSharp Logging is initialized, and set the backend options:

var backend = new Patterns.Diagnostics.Backends.Console.ConsoleLoggingBackend();
backend.Options.Delimiter = " \u00A6 ";
backend.Options.UseColors = false;
LoggingServices.DefaultBackend = backend ;

Implementing a custom formatter

When you include parameter values in log records, PostSharp will invoke the ToString method of the object by default. To learn when and how to override the default formatter, see Implementing a Custom Formatter.

Overriding a backend

If none of the previous options are sufficient, you can create your own backend. Instead of creating your own implementation from scratch, you can derive any existing implementation and override relevant methods.

See Building Your Own Logging Backend (Adapter) for details.