Loupe - Log - Monitor - Resolve
Loupe / Developer's Guide / For .NET Framework / Logging / Developer's Guide - Logging - Directly to Loupe
In This Topic
    Developer's Guide - Logging - Directly to Loupe
    In This Topic

    Prerequisites

    To log information directly using the Loupe API you need to add a reference to the Loupe Agent (Gibraltar.Agent.dll).  This is the only file required.  By adding the reference most setup and deployment tools will automatically distribute this file with your application.

    Converting from Trace

    If you've already started using Trace logging that's built into the .NET framework the simplest place to start is to use the API methods that are designed to mirror the .NET System.Trace commands.

    Simple Logging Direct to Loupe
    Copy Code
    private void LogDirectSample()
    {
        //The following are designed to be drop-in substitutes for the System.Trace logging capability.
        Log.TraceVerbose("This is a sample verbose message.  Verbose are the lowest level of priority");
        Log.TraceInformation("This is a sample information message.  Information are the first level up from Verbose.");
        Log.TraceWarning("This is a sample information message.  Information are the first level up from Verbose.");
        Log.TraceError("This is a sample error message.  Error messages are the most severe typical message.");
        Log.TraceVerbose("You can also insert strings into messages, just like {0} supports",
            typeof(System.Diagnostics.Trace).FullName);
        //Because Loupe supports an extra severity it is also accessible through a similar command
        Log.TraceCritical("Critical are the most severe messages, and should be reserved "
            + " for crash events or other scenarios where execution can't continue");
    
        //Unlike System.Trace, you can add in an exception as part of a message without having to dump it to
        //a string in the body of the message.  This provides additional capabilities in the viewer and generally
        //cleaner messages.
        try
        {
            //things that might be a problem.
        }
        catch (Exception ex)
        {
            Log.TraceInformation(ex, "We received an exception while working.  "
                + "We can continue, so this isn't an error.");
        }
    }
    

    Better Logging

    If you aren't trying to quickly convert from Trace to using the Loupe Log API directly the best interface is a set of direct methods broken out by severity:

    Better Logging Direct to Loupe
    Copy Code
    public void BetterLogSample()
    {
        Log.Critical("Period.Delimited.Category", "This is a critical problem",
            "We are writing a test message with multiple insertion strings: {0} {1} {2}",
            "string", 124, DateTime.Now);
        Log.Warning("Period.Delimited.Category", "This might be a problem problem",
            "You don't have to provide insertion strings if you don't want to");
        //Any of the different severities can include details of an exception.  Don't bother
        //dumping it in the message area; it'll all be showing in the Loupe Desktop under the Exception.
        Exception ex = new InvalidOperationException("This is an example invalid operation exception");
        Log.Error(ex, "Your Application.Exceptions", "We had an odd exception but managed to recover",
            "Here's a description of what we were doing.  We don't need to provide exception data.");
        //If you think the application might crash immediately after you call to record the message
        //you might want to make just this message synchronous.
        Log.Critical(LogWriteMode.WaitForCommit, "Your.Category", "We had a problem and may crash",
            "Just like our first method above we can now provide extended detail with insertion strings");
        Log.Verbose("Your.Category", "This is our lowest severity message",
            "Verbose is like a debug or success message - below all other severities.");
    }
    

    Using your own Central Log Class

    If you already have a central logging class you can gateway calls into Loupe by using the Write methods.

    Advanced Logging Direct to Loupe
    Copy Code
    private void LogDirectAdvancedSample()
    {
        //using the Write method you can perform additional tasks that aren't accessible through the
        //Trace-compatible API.
        Log.Write(LogMessageSeverity.Information,
            "This is the simplest form of write, and is identical to Log.TraceInformation");
        //One special case is for important messages that you need committed to disk before continuing
        //such as when logging during an unhandled exception.  There is a performance penalty, so this option
        //is not set by default.
        Log.Write(LogMessageSeverity.Critical, LogWriteMode.WaitForCommit,
            "This statement will not return until the log message is committed to disk");
        //and the variation with passing exceptions and additional parameters to insert are also supported.
        //see the documentation for Log.Write for other overloads.
    }
    

    For the most advanced functionality (used primarily when bridging data from a foreign log system into Loupe, such as Log4Net and Trace) you can use the WriteMessage methods.  These require the most work but delegate the most capability to your code. 

    Configuring the Agent

    You can configure the agent directly in your code by subscribing to its Initializing event.  For complete information, see Developer's Guide - Agent Configuration through Code.

    See Also

    Developer's Guide