Skip to content

augustoproiete/exceldna-diagnostics-serilog

Folders and files

NameName
Last commit message
Last commit date
Oct 22, 2022
Jan 12, 2025
Jul 29, 2020
Mar 31, 2023
Mar 31, 2023
Mar 31, 2023
Aug 9, 2020
Mar 18, 2021
Sep 19, 2021
May 16, 2020
May 14, 2020
Mar 18, 2021
Mar 31, 2023
Mar 31, 2023
Apr 7, 2020
Jan 12, 2025
Mar 18, 2021
Mar 18, 2021
Mar 18, 2021
Mar 18, 2021
Nov 10, 2019
Nov 10, 2019
Sep 19, 2021
Apr 7, 2021

Repository files navigation

README.md
ExcelDna.Diagnostics.Serilog

ExcelDna.Diagnostics.Serilog

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

NuGet Version Stack Overflow Stack Overflow

Excel-DNA Diagnostics Serilog with Seq screenshot

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.

Excel-DNA Diagnostics LogDisplay screenshot

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.

Excel-DNA Serilog logs in file Notepad screenshot

Excel-DNA Serilog logs in LogDisplay window screenshot

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.