ExcelDna.Diagnostics.Serilog

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

Give a Star! ⭐

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

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.

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

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 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.

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.

zeta1999 / exceldna-diagnostics-serilog Goto Github PK