Choosing and using text formatters
.png "patterns & practices Developer Center")
Some of the event sinks available for use with the Semantic Logging Application Block support the use of event text formatters that you can use to format the messages written by these event sinks. Events typically include a string value for the Message property, which is generated by the method in the event source and is a summary of the event. However, formatters act on the individual items of data in the event payload, and so can produce a much more useful and verbose message in the logs. In addition, the format of this message can be changed without requiring any modification to the log method in the event source.
All of the formatters are included in the main Semantic Logging Application Block package obtainable from NuGet. You can create instances of the formatter classes and configure them by passing parameters to the constructors, and/or by setting some properties.
The following sections describe the configuration options for each formatter:
- EventTextFormatter. This formatter allows you to control the headers, footers, verbosity, and date/time format of the output from an event sink.
- JsonEventTextFormatter. This formatter generates its output in JSON format, and allows you to specify the indenting and the date/time format of the output from an event sink.
- XmlEventTextFormatter. This formatter generates its output in XML format, and allows you to specify the indenting and the date/time format of the output from an event sink.
The block does not include a CSV formatter, but you can easily export log messages in CSV format from Azure Table storage or from a SQL Server database. You can also create your own custom event formatters. For more details, see Creating a custom event formatter.
EventTextFormatter
The following table describes the configurable constructor parameters and properties of the EventTextFormatter class. If you are using the application block out-of-process, you set these parameters using the configuration file for the Out-of-Process Host. See Configuration schema for the out-of-process model for details.
Parameter/Property |
Description |
|---|---|
header |
A string to appear before the log message. This is optional. |
footer |
A string to appear after the log message. This is optional. |
verbosityThreshold |
An event level as defined in the EventLevel enumeration: one of Verbose (5), Informational (4), Warning (3), Error (2), Critical (1), or LogAlways (0). All log messages with an event level less than or equal to this value are displayed in detail. Other log messages are displayed in summary. The default value is Error. If the value is LogAlways all messages are displayed in detail. |
dateTimeFormat |
This optional parameter controls the format of the timestamp written to the log. By default, the block uses “O” as the format string. For more information, see Standard Date and Time Format Strings on MSDN. |
The following code shows how to use the EventTextFormatter class to add a header and footer to the log messages written to a file.
var formatter = new EventTextFormatter("++++++++++++", "============");
listener.LogToFlatFile(@"C:\Temp\SLAB_logs.txt", formatter);
The following sample shows how you specify that all Error, Critical, and LogAlways messages should be displayed in detail, while Informational, Verbose, and Warning messages are displayed in summary. It uses the VerbosityThreshold property of the EventTextFormatter to set the event level.
var formatter = new EventTextFormatter() { VerbosityThreshold = EventLevel.Error };
listener.LogToFlatFile(@"C:\Temp\SLAB_logs.txt", formatter);
JsonEventTextFormatter
The following table describes the configurable constructor parameters and properties of the JsonEventTextFormatter class. If you are using the application block out-of-process, you set these parameters using the configuration file for the Out-of-Process Host. See Configuration schema for the out-of-process model for details.
Parameter/Property |
Description |
|---|---|
Formatting |
An event level as defined in the EventTextFormatting enumeration: either None or Indented. The default value is None. This controls the layout of the JSON string in the output. It is exposed as a read-only property named Formatting. |
dateTimeFormat |
This optional property controls the format of the timestamp written to the log. By default, the block uses “O” as the format string. For more information, see Standard Date and Time Format Strings on MSDN. |
IncludeEntrySeparator |
Set this property to true to include a comma separator between event entries in the sink destination. This property cannot be set as a parameter to the class constructor. |
The following code sample shows how to use the JsonEventTextFormatter class to format the log messages written to a file as JSON and use an indented layout for the JSON messages.
var formatter = new JsonEventTextFormatter(EventTextFormatting.Indented);
listener.LogToFlatFile(@"C:\Temp\SLAB_logs.txt", formatter);
XmlEventTextFormatter
This formatter generates XML that is compliant with the Event schema described in Event Schema on MSDN. The following table describes the configurable constructor parameters and properties of the XmlEventTextFormatter class. If you are using the application block out-of-process, you set these parameters using the configuration file for the Out-of-Process Host. See Configuration schema for the out-of-process model for details.
Parameter/Property |
Description |
|---|---|
formatting |
An event level as defined in the EventTextFormatting enumeration: either None or Indented. The default value is None. This controls the layout of the XML in the output. It is exposed as a read-only property named Formatting. |
dateTimeFormat |
This optional property controls the format of the timestamp written to the log. By default, the block uses “O” as the format string. For more information, see Standard Date and Time Format Strings on MSDN. |
The following code sample shows how to use the XmlEventTextFormatter class to format the log messages written to a file as XML, using an indented layout for the XML messages and the short date/time format for dates.
var formatter = new XmlEventTextFormatter(EventTextFormatting.Indented, "d");
listener.LogToFlatFile(@"C:\Temp\SLAB_logs.txt", formatter);