This walkthrough demonstrates how to change the default log filtering for the My.Application.Log object, to control what information is passed from the Log object to the listeners and what information is written by the listeners. You can change the logging behavior even after building the application, because the configuration information is stored in the application's configuration file.
Getting Started
Each message that My.Application.Log writes has an associated severity level, which filtering mechanisms use to control the log output. This sample application uses My.Application.Log methods to write several log messages with different severity levels.
To build the sample application
Open a new Visual Basic Windows Application project.
Add a button named Button1 to Form1.
In the Click event handler for Button1, add the following code:
By default, the application flushes the log-file output when the application closes.
In the example above, the second call to the WriteEntry method and the call to the WriteException method produces log output, while the first and last calls to the WriteEntry method do not. This is because the severity levels of WriteEntry and WriteException are "Information" and "Error", both of which are allowed by the My.Application.Log object's default log filtering. However, events with "Start" and "Stop" severity levels are prevented from producing log output.
Filtering for All My.Application.Log Listeners
The My.Application.Log object uses a SourceSwitch named DefaultSwitch to control which messages it passes from the WriteEntry and WriteException methods to the log listeners. You can configure DefaultSwitch in the application's configuration file by setting its value to one of the SourceLevels enumeration values. By default, its value is "Information".
This table shows the severity level required for Log to write a message to the listeners, given a particular DefaultSwitch setting.
DefaultSwitch Value
Message severity required for output
Critical
Critical
Error
Critical or Error
Warning
Critical, Error, or Warning
Information
Critical, Error, Warning, or Information
Verbose
Critical, Error, Warning, Information, or Verbose
ActivityTracing
Start, Stop, Suspend, Resume, or Transfer
All
All messages are allowed.
Off
All messages are blocked.
Note
The WriteEntry and WriteException methods each have an overload that does not specify a severity level. The implicit severity level for the WriteEntry overload is "Information", and the implicit severity level for the WriteException overload is "Error".
This table explains the log output shown in the previous example: with the default DefaultSwitch setting of "Information", only the second call to the WriteEntry method and the call to the WriteException method produce log output.
To log only activity tracing events
Right-click app.config in the Solution Explorer and select Open.
-or-
If there is no app.config file:
On the Project menu, choose Add New Item.
From the Add New Item dialog box, choose Application Configuration File.
Click Add.
Locate the <switches> section, which is in the <system.diagnostics> section, which is in the top-level <configuration> section.
Find the element that adds DefaultSwitch to the collection of switches. It should look similar to this element:
<add name="DefaultSwitch" value="Information" />
Change the value of the value attribute to "ActivityTracing".
The content of the app.config file should be similar to the following XML:
Individual Filtering For My.Application.Log Listeners
The previous example shows how to change the filtering for all My.Application.Log output. This example demonstrates how to filter an individual log listener. By default, an application has two listeners that write to the application's debug output and the log file.
The configuration file controls the behavior of the log listeners by allowing each one to have a filter, which is similar to a switch for My.Application.Log. A log listener will output a message only if the message's severity is allowed by both the log's DefaultSwitch and the log listener's filter.
This example demonstrates how to configure filtering for a new debug listener and add it to the Log object. The default debug listener should be removed from the Log object, so it is clear that the debug messages come from the new debug listener.
To log only activity-tracing events
Right-click app.config in the Solution Explorer and choose Open.
-or-
If there is no app.config file:
On the Project menu, choose Add New Item.
From the Add New Item dialog box, choose Application Configuration File.
Click Add.
Right-click app.config in Solution Explorer. Choose Open.
Locate the <listeners> section, in the <source> section with the name attribute "DefaultSource", which is under the <sources> section. The <sources> section is under the <system.diagnostics> section, in the top-level <configuration> section.
Add this element to the <listeners> section:
<!-- Remove the default debug listener. -->
<remove name="Default"/>
<!-- Add a filterable debug listener. -->
<add name="NewDefault"/>
Locate the <sharedListeners> section, in the <system.diagnostics> section, in the top-level <configuration> section.
Add this element to that <sharedListeners> section: