README.md

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!

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.

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.

---

Copyright © 2019-2023 C. Augusto Proiete & Contributors - Provided under the Apache License, Version 2.0.