ExcelDna.Diagnostics.Serilog

Integrate Excel-DNA Diagnostic Logging with your Serilog logging pipeling within your Excel-DNA add-in

Description

Integrate Excel-DNA Diagnostic Logging with your Serilog logging pipeling within your Excel-DNA add-in.

Programming language: C#

License: Apache License 2.0

Tags: Logging     Log     Error     Exception     Serilog     Diagnostics     Netstandard     Exceldna    

Latest version: v1.1.0

README

README.md

ExcelDna.Diagnostics.Serilog

Integrate Excel-DNA Diagnostic Logging with your Serilog logging pipeling within your Excel-DNA add-in.

[Excel-DNA Diagnostics Serilog with Seq screenshot](assets/serilog-logs-seq.png)

Give a Star! :star:

If you like or are using this project please give it a star. Thanks!

Background

Excel-DNA writes diagnostic log messages which can be very useful for troubleshooting issues with an add-in that is not working or behaving as expected. By default, messages are written to the LogDisplay window, which can only be seen by the end-user of the add-in.

[Excel-DNA Diagnostics LogDisplay screenshot](assets/default-logdisplay-logs.png)

However, it's possible to configure Excel-DNA to write to other Trace listeners which can then forward these diagnostic messages to any logging pipeline such as Serilog, for example, in order to consume / analyse these logs outside of the user's machine.

ExcelDna.Diagnostics.Serilog implements a TraceListener that converts Trace log events to Serilog log events and integrates with a Serilog logging pipeline, effectivelly forwarding any diagnostic messages written by Excel-DNA to a Serilog logger.

Getting started :rocket:

Install the ExcelDna.Diagnostics.Serilog package from NuGet:

Install-Package ExcelDna.Diagnostics.Serilog

If you don't have Serilog in your project yet, you'll need to install one or more Serilog Sinks to have Excel-DNA diagnostic messages written to the destination you want. For example, if you'd like to write the messages to a file, you could use the Serilog.Sinks.File sink.

Install-Package Serilog.Sinks.File

Sinks can be found in the list of Provided Sinks in the Serilog documentation, and also by searching within the serilog tag on NuGet.org.

Configure Excel-DNA diagnostic logging and the Serilog Trace Listener in your App.config file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.diagnostics>
    <sources>
      <source name="ExcelDna.Integration" switchValue="All">
        <listeners>
          <!-- (optional) Remove the `DefaultTraceListener`, which writes to the attached debugger -->
          <remove name="Default" />

          <!-- Remove any existing listener named `LogDisplay` (just in case) -->
          <remove name="LogDisplay" />

          <!-- Turn off the default `LogDisplayTraceListener` (we can use Serilog for that) -->
          <add name="LogDisplay"
               type="ExcelDna.Logging.LogDisplayTraceListener, ExcelDna.Integration">
            <filter type="System.Diagnostics.EventTypeFilter" initializeData="Off" />
          </add>

          <!-- Remove any existing listener named `ExcelDnaSerilog` (just in case) -->
          <remove name="ExcelDnaSerilog" />

          <!-- Add the listener that will forward Excel-DNA diagnostic messages to Serilog -->
          <add name="ExcelDnaSerilog"
               type="ExcelDna.Diagnostics.Serilog.SerilogTraceListener, ExcelDna.Diagnostics.Serilog" />
        </listeners>
      </source>
    </sources>
  </system.diagnostics>
</configuration>

Configure your Serilog logging pipeline, create your root logger, and call ExcelDnaTraceSource.WriteToSerilog() to start forwarding any diagnostic messages written by Excel-DNA to your Serilog logger.

public class AddIn : IExcelAddIn
{
    public void AutoOpen()
    {
        Log.Logger = new LoggerConfiguration()
            .MinimumLevel.Verbose()
            .WriteTo.File($"{ExcelDnaUtil.XllPath}.log")
            .WriteTo.Seq("https://central-logging-system.company.net")
            .CreateLogger();

        // Forward any messages written by Excel-DNA to Serilog
        ExcelDnaTraceSource.WriteToSerilog();
    }

    // ...
}

Example of an Excel-DNA add-in using ExcelDna.Diagnostics.Serilog

In the [sample](sample/) folder, you can find an example of an Excel-DNA add-in that captures any diagnostic messages written by Excel-DNA and forwards them to a Serilog logging pipeline configured to write log events to a file on disk and also to Excel-DNA's built-in LogDisplay.

[Excel-DNA Serilog logs in file Notepad screenshot](assets/serilog-logs-file-notepad.png)

[Excel-DNA Serilog logs in LogDisplay window screenshot](assets/serilog-logs-exceldna-logdisplay.png)

Mapping of Trace events to Serilog

Trace events are mapped to Serilog log events in the following way:

Trace TraceEventType	Serilog LogEventLevel
TraceEventType.Critical	LogEventLevel.Fatal
TraceEventType.Error	LogEventLevel.Error
TraceEventType.Warning	LogEventLevel.Warning
TraceEventType.Information	LogEventLevel.Information
TraceEventType.Start	LogEventLevel.Debug
TraceEventType.Stop	LogEventLevel.Debug
TraceEventType.Suspend	LogEventLevel.Debug
TraceEventType.Resume	LogEventLevel.Debug
TraceEventType.Transfer	LogEventLevel.Debug
TraceEventType.Verbose	LogEventLevel.Verbose

Log Event Properties

Diagnostic log messages forwarded to Serilog have the SourceContext property set to ExcelDna.Integration, allowing developers to use filters, sub-loggers, and minimum level overrides.

Trace event fields (when available) are added as custom properties to Serilog log events with the following names:

• ActivityId - A structure that identifies the related activity
• Category - A category name used to organize the output
• TraceEventId - A numeric identifier for the event
• FailDetails - A detailed error message to emit
• RelatedActivityId - A structure that identifies the related activity
• TraceSource - A name used to identify the output, typically the name of the application that generated the trace event
• TraceData - The trace data to emit
• TraceEventType - One of the System.Diagnostics.TraceEventType values specifying the type of event that has caused the trace

Excel-DNA configuration for packing with ExcelDnaPack

In order for the Excel-DNA Diagnostics Serilog to work from an add-in that is packaged using the ExcelDnaPack utility, you need to include references to Serilog.dll and ExcelDna.Diagnostics.Serilog.dll in the .dna file of the add-in along with references to the assemblies of any other sinks you may have added:

<DnaLibrary Name="My Add-In" RuntimeVersion="v4.0">
  <ExternalLibrary Path="MyAddIn.dll" ExplicitExports="false" LoadFromBytes="true" Pack="true" />

  <Reference Path="Serilog.dll" Pack="true" />
  <Reference Path="Serilog.Sinks.SomeSink.dll" Pack="true" />
  <Reference Path="ExcelDna.Diagnostics.Serilog.dll" Pack="true" />
  <!-- etc. -->

Release History

Click on the Releases tab on GitHub.

---

Copyright © 2019-2020 C. Augusto Proiete & Contributors - Provided under the [Apache License, Version 2.0](LICENSE).