Developer's Reference - Microsoft.Extensions.Logging Introduction

In This Topic

Loupe provides an excellent log provider for capturing messages written to Microsoft.Extensions.Logging (MEL). MEL is used extensively within .NET Core & .NET 5's internal libraries and many third-party libraries. It supports basic logging in an API very similar to Loupe's native API but also supports Semantic Logging, making it easy to record contextual information along with log messages.

Using Loupe with Microsoft.Extensions.Logging

To use the Loupe Logging Provider:

Add the Loupe.Extensions.Logging NuGet Package to your project. This adds the provider itself and other required Loupe packages.
Register the Loupe provider in your logging configuration

For projects that use Generic Host (like ASP.NET Core), register the Loupe provider by adding a call to AddLoupeLogging like this:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .AddLoupe() //Add the Loupe Agent
        .AddLoupeLogging() //create a default log config & add Loupe to it.
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

If you need to provide more detail to set up your logging, you can also add Loupe in your log builder, like this:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .AddLoupe() //Add the Loupe Agent
        .ConfigureLogging(builder =>
        {
            //this line adds Loupe to the configuration builder
            builder.AddLoupe();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

In a non-host app (like a console application) make the call while creating your LoggerFactory, like this:

//Create a logging factory, typically once per application.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddFilter("Microsoft", LogLevel.Warning)
        .AddFilter("System", LogLevel.Warning)
        .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
        .AddLoupe(); //this line adds Loupe
});
//Having set up the factory, use it to create the logger for your class
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("This message will be sent to Loupe (and any other logging provider you configure above)");

Basic Logging with Microsoft.Extensions.Logging

MEL includes a logging API similar to the built-in Loupe API. The main difference is the prefixing of each severity with "Log" (e.g. Log.LogCritical vs. Log.Critical) and the support for logging scopes & Structured Logging which are very beneficial.

The basic logging API, in decreasing severity, are:

logger.LogCritical("This message will show up as a Critical message in the log.");
logger.LogError("This message will show up as a Error message in the log.");
logger.LogWarning("This message will show up as a Warning message in the log.");
logger.LogInformation("This message will show up as an Information message in the log.");
logger.LogDebug("This message will show up as a Debug message in the log.");
logger.LogTrace("This message will show up as a Trace message in the log.");

Like Loupe, an Exception object can be recorded as part of any log message severity. Loupe will serialize the exception for extended analysis and display, even if it isn't inserted into the message itself like this:

logger.LogError(ex, "This message is an Error with an exception attached as data.");

Usually, you'll want to include some information from the exception in your message, like this:

logger.LogError(ex, $"Unable to do what you wanted due to {Exception}\r\n" +
                    $"{ExceptionMessage}", ex.GetType(), ex.Message);

The example above also demonstrates Semantic Logging - where a name/value pair is added to the context information for the log message for Exception and ExceptionMessage with the values based on the order they are listed.