Loupe - Log - Monitor - Resolve
Loupe / Developer's Guide / For .NET Framework / Third Party Integration / Using NLog with Loupe / Third Party Integration - Using NLog 1.0 with Loupe
In This Topic
    Third Party Integration - Using NLog 1.0 with Loupe
    In This Topic

    Adapting your .NET Application's NLog logging to include Loupe

    To convert your .NET application's existing use of the NLog logging framework to include Loupe you need:

    Adding the Gibraltar.Agent.NLog Assembly to your Solution

    Using the Distributed Assembly

    If you reference the NLog.dll distributed with Loupe or the same version retrieved directly from the NLog Project site it then you may add this distribution's Gibraltar.Agent.NLog.dll binary to your references rather than include the GibraltarTarget class in your project.  This is the simplest way to use the Loupe NLog Target because we've already created a strong named assembly linked to the distribution of the Loupe Agent included in this release and NLog 1.0 Refresh.

    The Gibraltar.Agent.NLog target was compiled against the specific build of NLog distributed with this release and won't work with another version.  If you have another version of NLog 1, just recompile the provided source code to target your version.

    Building your Own Assembly

    If you reference the distributed NLog.dll distributed with this release then you may add this distribution's Gibraltar.Agent.NLog.dll assembly to your references rather than include the GibraltarTarget class in your project. If you instead wish to rebuild Gibraltar.Agent.NLog from source code:

    1. Add the GibraltarTarget.cs class to your own application from the SDK\NLog\1.0 folder.
    2. Check that the Reference to the NLog library points to where you have it on your system or build process. If needed, either add the correct reference and delete the broken one, or else edit the project file directly and correct the path.
    3. Confirm that the Reference to the Gibraltar.Agent library is valid, or correct it. If you installed Loupe in the default location it should be in one of these locations:
      • C:\Program Files\Gibraltar Software\Loupe\SDK\Redist\Gibraltar.Agent.dll
      • C:\Program Files (x86)\Gibraltar Software\Loupe\SDK\Redist\Gibraltar.Agent.dll (if your computer is running a 64-bit operating system)
    4. Build this project and either add this project to your application as a dependency or copy the assembly it builds to wherever you keep external library dependencies.
    5. Also include the Gibraltar.Agent.dll and Gibraltar.Package.exe in your distribution and installation in the directory for your application executable.

    Adjust your configuration to use the GibraltarTarget

    Loupe is intended as a top-level catch-all to collect all of your logging in one managed place so you can filter as needed dynamically during analysis. To do this, modify the extensions, targets, and rules sections of your NLog configuration as follows:

    If you find minlevel="Trace" too voluminous for normal collection, the minlevel may be set at "Debug" instead. Also, see the example App.config file in the Gibraltar.Agent.NLog project, and consult the NLog configuration documentation as needed.

    Example App.config for Integrating the GibraltarTarget with NLog
    Copy Code
    <?xml version="1.0" encoding="utf-8" ?>
    <configuration>
      <configSections>
        <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog"/>
      </configSections>
      <!-- In an NLog.config file only this "nlog" section is needed as the root.  App.config also needs the rest. -->
      <nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <extensions>
          <add assembly="Gibraltar.Agent.NLog" /> <!--Contains GibraltarTarget class marked as "Gibraltar" target type-->
        </extensions>
        <targets>
          <target name="Gibraltar" xsi:type="Gibraltar" /> <!--Define a named target using the "Gibraltar" target type-->
        </targets>
        <rules>
          <logger name="*" minlevel="Trace" writeTo="Gibraltar" /> <!--Send all logging to the "Gibraltar" named target-->
        </rules>
      </nlog>
    </configuration>
    

    In the above example no Loupe Agent configuration information was included.  You can add in any necessary Loupe Agent configuration manually or via NuGet.

    Usage Tips

    Make sure to log something to Loupe early in your application (e.g. before Application.Run) to load the Loupe Agent and initialize its automatic monitoring features. For example:

    Example NLog Application Startup Message
    Copy Code
    mainLogger.LogInfo("Entering application.");
    

    You can also take either of the approaches listed in Developer's Guide for WinForms - Ensuring the Loupe Agent gets Loaded.

    Ensuring your Application Exits

    Because NLog doesn't have any way of signaling to its logging targets that the log system is shutting down you should follow the instructions in Developer's Guide - .NET Framework - Ensuring Your Application Exits to ensure that your application exits.  As an example, the following line placed just before the routine exit of your application will ensure it exits quickly:

    Example Application Shutdown
    Copy Code
    Gibraltar.Agent.Log.EndSession("Application Exiting Normally");