Diagnostics & Logging

Internally, ZPT-Sharp makes use of the .NET framework's built-in diagnostics functionality. This allows it to expose diagnostic, debug and error information about the rendering process, without specifying what should done with that information.

By default, no action is performed with the Trace and Debug information; the messages are exposed to the framework and then immediately discarded. If you wish to record or capture this information then this is controlled via the application configuration file.

The .NET framework's Trace functionality is very powerful and flexible; we will not be examining it in depth here. Briefly, instances of TraceListener are attached to TraceSource objects, via the application configuration file. These listeners do not need neccesarily to be compiled with references to the main project, not does the main project need to reference them. At run-time, the .NET framework, acting on information from the configuration file, loads the relevant trace listener types and subscribes them to the trace sources in order to receive the messages.

Integrating with Log4net

What follows is an example of how to integrate with the log4net library in order to capture Trace and Debug information. Log4net is a third party logging library, maintained by the Apache project. If you wish to know more about it, including how to use its powerful configuration syntax, then you may read more at the log4net manual page.

ZPT-Sharp ships with two optional assemblies designed for logging diagnostics information; CSF.Zpt.Log4Net.dll and log4net.dll. The latter is the core log4net code and the former contains a customised TraceListener which redirects received messages to log4net. These two assemblies are not required for normal operation.

If you wish to capture log information using log4net then you should ensure that they are placed in the same directory as the ZPT-Sharp assemblies, and that your application configuration attaches the trace listener to the appropriate trace source(s).

Here is an example of the changes to make in your application configuration file in order to log messages to a file, using the log4net listener.

<!-- Declare the log4 net config section -->
<configSections>
  <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
</configSections>

<!-- This section configures log4net itself -->
<log4net>
  <root>
    <!--
        Set the default level (for anything not configured to
        warnings and above).
    -->
    <level value="WARN" />
    <appender-ref ref="FileAppender" />
  </root>
  <appender name="FileAppender" type="log4net.Appender.FileAppender">
    <!-- Set the path to the log file -->
    <file value="MyApplication.log" />
    <appendToFile value="false" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="[%-5level] [%logger] %message%n" />
    </layout>
  </appender>
  <!--
      Log messages of level DEBUG and up originating from ZPT-Sharp
      If you wish to use log4net in your own application, you would
      add further loggers here to determine the log-level for your
      own app.
  -->
  <logger name="CSF.Zpt">
    <level value="DEBUG" />
  </logger>
</log4net>

<!--
    This section attaches the ZPT-Sharp log4net trace listener to
    the appropriate TraceSource.
-->
<system.diagnostics>    
  <sources>
    <!-- Add the listener to other sources too if you wish -->
    <source name="CSF.Zpt" switchName="defaultSwitch" switchType="System.Diagnostics.SourceSwitch">
      <listeners>
        <add name="log4netListener" />
        <remove name="Default" />
      </listeners>
    </source>
  </sources>
  <switches>
    <add name="defaultSwitch" value="Verbose"/>
  </switches>
  <sharedListeners>
    <add name="log4netListener"
          type="CSF.Zpt.SelfConfiguringLog4netTraceListener, CSF.Zpt.Log4net">
      <filter type="System.Diagnostics.EventTypeFilter" initializeData="Verbose"/>
    </add>
  </sharedListeners>
</system.diagnostics>

This is only a limited example which will get logging through log4net working. Please read the relevant documentation (MSDN and log4net) if you would like to customise your logging solution.

Consuming ZPT-Sharp as an API

If you are building an application which consumes ZPT-Sharp as an API then you may wish to make use of Trace and Debug logging yourself. Additionally you might be integrating with other APIs which also make use of this functionality. The TraceSource names used by ZPT-Sharp are:

• CSF.Zpt - used by the core API for rendering operations.
• CSF.Zpt.Cli - used by the ZptBuilder front-end application.
• CSF.Zpt.Mvc - used by the MVC view engine.

Note about 'debug' builds

If you have built the solution by hand and used the Debug configuration, then additional information will be made available via trace listeners. This provides information useful to developers working on ZPT-Sharp itself, but which is not very useful otherwise.

These messages are recorded at the Verbose level (from a TraceEventType standpoint), or a DEBUG level in log4net terminology. You may wish to filter them out unless you are trying to debug ZPT-Sharp's rendering. You would do this using either a source switch or log4net logger level of INFO or above, otherwise you could see a very noisy log file.