Enable Logging

Enable Logging

The Workspaces SDK uses NLog as its underlying logging provider. Additional Information about NLog found at NLog Tutorial

Configuring Logging

To enable logging in the SDK you need to add to the configuration for your application. First define a section for NLog in the configSection of your configuration.

Copy

<configSections>
  <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog"/>
</configSections>

Next, add the targets and rules inside the section defined for NLog. Targets specify where to write log messages, Rules define when to write log messages.

In the example below two targets have been defined: one will send log messages to a file named "workspacessdk.log", the other will write to the console. The two rules specified will cause Trace and higher messages to be written to the log file while only Info and higher messages will be written to the console.

Copy

<nlog
     autoReload="true"
     xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target
         name="logfile"
         xsi:type="File"
         fileName="${basedir}/workspacessdk.log"
         layout="${level} | ${message}"
         keepFileOpen="true" />
    <target
         name="console"
         xsi:type="Console" />
  </targets>

  <rules>
    <logger name="*" minlevel="Trace" writeTo="logfile"/>
    <logger name="*" minlevel="Info" writeTo="console" />
  </rules>
</nlog>

Workspaces logging extensions

The Workspaces SDK provides two extensions to NLog.

CustomDbgOutputTarget: Logs messages using the native OutputDebugString method.
ResettableFileTarget: Provides a File target which will reset or truncate the log file whenever a specified pattern is seen in a log message.

To enable the Workspaces SDK extensions you must add an extensions section to the NLog configuration section.

Copy

<nlog
     autoReload="true"
     xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <extensions>
    <add assembly="WorkspacesSdk" />
  </extensions>
</nlog>

The CustomDbgOutputTarget extension extends the NLog TargetWithLayout which allows the layout attribute to be specified to define the format of the log messages.

Copy

<nlog
     autoReload="true"
     xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <extensions>
    <add assembly="WorkspacesSdk" />
  </extensions>

  <targets>
    <target
         name="ods"
         xsi:type="CustomDbgOutput"
         layout="${level} | ${message}"/>
  </targets>

  <rules>
    <logger name="*" minlevel="Trace" writeTo="ods"/>
  </rules>
</nlog>

The ResettableFileTarget extension extends the NLog FileTarget. Any attributes allowed on FileTarget maybe used with ResettableFileTarget.

ResettableFileTarget supports an additional attribute, DeleteToken, which controls when the log file is reset/truncated. The default value for DeleteToken is ~DELETE~LOG~FILE~. Whenever the value specified by the DeleteToken attribute is seen in a log message the current logfile is truncated and any future log messages will be written from the beginning of the log file.

Copy

<nlog
     autoReload="true"
     xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <extensions>
    <add assembly="WorkspacesSdk" />
  </extensions>

  <targets>
    <target
         name="resetlogfile"
         xsi:type="ResettableFile"
         deleteToken="SomeDeleteToken"
         fileName="${basedir}/workspacessdk.log"
         layout="${message}"
         keepFileOpen="true" />
  </targets>

  <rules>
    <logger name="*" minlevel="Trace" writeTo="resetlogfile"/>
  </rules>
</nlog>

Other Resources

NLog Tutorial