Visual Basic 2010 Logging - My.Application.Log Object Instrumenting Applications

home links
visual basic 2010 broncode voorbeelden

31.16. Logging - My.Application.Log Object

Dit artikel is gepubliceerd op zondag 31 juli 2011 op vbvoorbeelden, bezoek de website voor een recente versie van dit artikel of andere artikels.

31.16.1. Logging Service

Een eenvoudige manier om boodschappen te loggen is via het My.Application.Log object. Deze geeft ons rechtstreeks toegang naar een Visual Basic logging service en beschikt over methods als WriteEntry en WriteException om boodschappen te sturen naar de listeners van de applications log.
De listeners kunnen opnieuw geconfigureerd worden in de Application Configuration File ( app.config ).

boven boven

31.16.2. Application Configuration File

Als je in Visual Studio een nieuw project start van type Windows Application, Class Library, Console Application, Windows Control Library of Windows Service en een Application Configuration File ( app.config ) toevoegt aan het project, dan ziet deze er zo uit :

Application Configuration File

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.diagnostics>
        <sources>
            <!-- This section defines the logging configuration
                 for My.Application.Log -->
            <source name="DefaultSource" switchName="DefaultSwitch">
                <listeners>
                    <add name="FileLog"/>
                    <!-- Uncomment the below section to write to the
                         Application Event Log -->
                    <!--<add name="EventLog"/>-->
                </listeners>
            </source>
        </sources>
        <switches>
            <add name="DefaultSwitch" value="Information" />
        </switches>
        <sharedListeners>
            <add name="FileLog"
                 type="Microsoft.VisualBasic.Logging.FileLogTraceListener,
                       Microsoft.VisualBasic, Version=8.0.0.0,
                       Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a,
                       processorArchitecture=MSIL"
                 initializeData="FileLogWriter"/>
            <!-- Uncomment the below section and replace APPLICATION_NAME
                 with the name of your application to write to the
                 Application Event Log -->
            <!--<add name="EventLog"
                     type="System.Diagnostics.EventLogTraceListener"
                     initializeData="APPLICATION_NAME"/> -->
        </sharedListeners>
    </system.diagnostics>
</configuration>

Meteen is er dus een default configuratie voor listeners van de booschappen die worden verzonden met WriteEntry en WriteException van My.Application.Log.

Alle boodschappen van TraceEventType.Information of erger ( Warning, Error en Critical ) die My.Application.Log ontvangt zullen naar de listeners worden doorgezonden. Dit is ingesteld in de switch met de naam "DefaultSwitch".

Er is ook meteen een listener ingesteld van het type FileLogTraceListener met de naam "FileLog" die de boodschappen zal schrijven naar een logbestand die by default dezelfde naam heeft als de assembly ( met extensie .log ).

Uiteraard kan deze configuratie naar eigen believen worden aangepast.

Indien de assembly geen Application Configuration File heeft wordt enkel de defaultlistener ( DefaultTraceListener ) gebruikt, die ervoor zal zorgen dat de boodschappen in het Output toolvenster terecht komen.

boven boven

31.16.3. FileLogTraceListener.Location Property

Als men geen specifieke locatie voor het logbestand instelt dan wordt gekeken naar de FileLogTraceListener.Location property ( van type LogFileLocation ) om te zien waar deze moet terecht komen.
By default is deze property ingesteld op LocalUserApplicationDirectory, wat neerkomt op het path voor de applicatie data van de gebruiker ( BasePath\CompanyName\ProductName\ProductVersion ). Het basispath is doorgaans iets als C:\Documents and Settings\username\Application Data\ ( Windows XP ) of C:\Users\username\AppData\Roaming\ ( Windows Vista en Windows 7 ).
CompanyName, ProductName en ProductVersion worden overgenomen uit de assembly-informatie, zie hiervoor de projecteigenschappen, tabblad Application, knop Assembly Information.

Andere mogelijke Microsoft.VisualBasic.Logging.LogFileLocation waardes zijn :

- CommonApplicationDirectory om gebruik te maken van het path voor applicatie data dat wordt gedeeld door alle gebruikers ( BasePath\CompanyName\ProductName\ProductVersion ), het basispath is hier doorgaans iets als C:\Documents and Settings\All Users\Application Data\ ( Windows XP ) of C:\ProgramData\ ( Windows Vista en Windows 7 ).

- ExecutableDirectory om gebruik te maken van hetzelfde path als het uitvoerbaar bestand dat de applicatie heeft gestart.

- TempDirectory om het path van de temporary folder van het systeem te gebruiken. Op Windows Vista en Windows 7 iets als C:\Users\userName\AppData\Local\Temp\.

- Custom om zelf aan de hand van de CustomLocation property te bepalen in welke folder het logbestand wordt geplaatst.

We zouden op volgende manier de Location property at runtime kunnen aanpassen :

Visual Basic 2010 Broncode

Class ConfigureFileLogLocationAtRunTime
    Public Shared Sub Main()
        Dim myTraceSource As New TraceSource("DefaultSource")
        Dim myFileLog As Microsoft.VisualBasic.Logging.FileLogTraceListener = _
                                              myTraceSource.Listeners("FileLog")
        '
        ' default :
        myFileLog.Location = _
                           Logging.LogFileLocation.LocalUserApplicationDirectory
        Console.WriteLine("LocalUserApplicationDirectory : " & _
                          myFileLog.FullLogFileName)
        '
        ' or :
        myFileLog.Location = Logging.LogFileLocation.CommonApplicationDirectory
        Console.WriteLine("CommonApplicationDirectory : " & _
                          myFileLog.FullLogFileName)
        '
        ' or :
        myFileLog.Location = Logging.LogFileLocation.ExecutableDirectory
        Console.WriteLine("ExecutableDirectory : " & myFileLog.FullLogFileName)
        '
        ' or :
        myFileLog.Location = Logging.LogFileLocation.TempDirectory
        Console.WriteLine("TempDirectory : " & myFileLog.FullLogFileName)
        '
        ' or :
        myFileLog.Location = Logging.LogFileLocation.Custom
        myFileLog.CustomLocation = "c:\someFolder\"
        Console.WriteLine("CustomLocation : " & myFileLog.FullLogFileName)
        '
        Console.ReadLine()
    End Sub
End Class

Download Visual Basic 2010 Broncode Download Visual C# Sourcecode

Bovenstaand voorbeeld zou ons bijvoorbeeld ( op Windows Vista en Windows 7 ) volgend resultaat kunnen geven ( assembly met naam TestApp en gebruiker met naam john ) :

Console Application Output

LocalUserApplicationDirectory : C:\Users\john\AppData\Roaming\TestApp\TestApp\
1.0.0.0\TestApp.log
CommonApplicationDirectory : C:\ProgramData\TestApp\TestApp\1.0.0.0\TestApp.lo
g
ExecutableDirectory : C:\TestApp\bin\Debug\TestApp.log
TempDirectory : C:\Users\john\AppData\Local\Temp\TestApp.log
CustomLocation : c:\someFolder\TestApp.log

Makkelijker is het om deze configuratie aan te brengen at configuration time. Bij een wijziging aan deze configuratie hoeft het programma niet opnieuw gecompileerd te worden.

Elke property van FileLogTraceListener kan via een attribuut van de <add> node worden ingesteld. Als attribuutnaam gebruik je hiervoor dezelfde naam als de property maar dan volledig in kleine letters. Om de property Location in te stellen werk je dus met attribuut location :

Een voorbeeld :

Application Configuration File

<add name="FileLog"
     type="Microsoft.VisualBasic.Logging.FileLogTraceListener,
           Microsoft.VisualBasic, Version=8.0.0.0,
           Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a,
           processorArchitecture=MSIL"
     location="ExecutableDirectory"/>

Visual Basic 2010 Broncode

Class ConfigureFileLogLocationAtConfigurationTime
    Public Shared Sub Main()
        My.Application.Log.WriteEntry("Message 1")
        My.Application.Log.WriteEntry("Message 2", TraceEventType.Warning, 3)
        My.Application.Log.WriteException(New OverflowException)
        My.Application.Log.WriteException(New InvalidCastException, _
                                          TraceEventType.Critical, _
                                          "Extra Message", 5)
    End Sub
End Class

Download Visual Basic 2010 Broncode Download Visual C# Sourcecode

In dezelfde directory als de executable ( waarschijnlijk de \bin\Debug\ subfolder van je projectfolder ) vind je een logbestand met daarin volgende boodschappen :

Tekst Bestand

DefaultSource	Information	0	Message 1
DefaultSource	Warning	3	Message 2
DefaultSource	Error	2	Arithmetic operation resulted in an overflow.
DefaultSource	Critical	5	Specified cast is not valid. Extra Message

In het Output toolvenster, waar naartoe de defaultlistener heeft geschreven, vinden we :

DefaultSource Information: 0 : Message 1
DefaultSource Warning: 3 : Message 2
DefaultSource Error: 2 : Arithmetic operation resulted in an overflow.
DefaultSource Critical: 5 : Specified cast is not valid. Extra Message

Zoals je aan bovenstaand voorbeeld ziet is het ook mogelijk per boodschap de ID, TraceEventType en eventueel een extra boodschap ( bij exceptions ) te bepalen.
By default zal WriteEntry een TraceEventType.Information boodschap met ID waarde 0 brengen en WriteException een TraceEventType.Error boodschap met ID waarde 2.

boven boven

31.16.4. Vergelijking met TraceSource

Men kan hetzelfde resultaat bereiken met een TraceSource object, hiervoor is echter vereist dat de TRACE constante op True is ingesteld :

Visual Basic 2010 Broncode

#Const TRACE = True
Class ExampleWithTraceSource
    Public Shared Sub Main()
        Dim myTraceSource As New TraceSource("DefaultSource")
        myTraceSource.TraceEvent(TraceEventType.Information, 0, "Message 1")
        myTraceSource.TraceEvent(TraceEventType.Warning, 3, "Message 2")
        myTraceSource.TraceEvent(TraceEventType.Error, 2, _
                                 (New OverflowException).Message)
        myTraceSource.TraceEvent(TraceEventType.Critical, 5, _
                           (New InvalidCastException).Message & "Extra Message")
        myTraceSource.Flush()
    End Sub
End Class

Download Visual Basic 2010 Broncode Download Visual C# Sourcecode

In het logbestand krijgen we volgende boodschappen :

Tekst Bestand

DefaultSource	Information	0	Message 1
DefaultSource	Warning	3	Message 2
DefaultSource	Error	2	Arithmetic operation resulted in an overflow.
DefaultSource	Critical	5	Specified cast is not valid. Extra Message

In het Output toolvenster krijgen we volgende boodschappen :

boven boven

31.16.5. My.Application.Log Enkel Voor Logging

De TRACE constante moet op True zijn ingesteld, omdat methods als TraceEvent van de TraceSource klasse in hun definitie een <Conditional("TRACE")> attribuut hebben.
Dit is niet het geval voor de methods WriteEntry en WriteException van My.Application.Log.

Dit wijst erop dat My.Application.Log specifiek voor het het registreren van log-informatie is ontworpen.  De Microsoft documentatie suggereert dat je dit ook voor het registreren van trace-informatie kunt gebruiken, wat natuurlijk klopt, alleen kan je de registratie hier niet uitzetten ( door de TRACE constante op False te zetten ), zoals je doorgaans wel wenst bij tracing.
Tracing is immers een vorm van debugging, waar je enkel in geïntresseerd ben in de ontwikkelfase.  In debug builds bijvoorbeeld worden de DEBUG en TRACE constanten doorgaans op True ingesteld, maar in een final build worden deze normaal op False ingesteld zodoende dat deze niet worden opgenomen door de compiler.
Omdat ze bij het gebruik van My.Application.Log altijd worden opgenomen, ook in release builds, ga je dit enkel gebruiken voor het registreren van log-informatie, anders zouden je release builds ook debug- of trace- informatie uitspuwen.  Wat uiteraard niet gewenst is, gezien debug- en trace-informatie per definitie slechts voor het ontwikkelteam nut heeft.

boven boven

31.16.6. Overige FileLogTraceListener Properties

Naast Location en CustomLocation zijn er nog tal van andere nuttige properties als BaseFilename, Append, AutoFlush, LogFileCreationSchedule, MaxFileSize en DiskSpaceExhaustedBehavior aanwezig.
Deze staan je toe zaken als de bestandsnaam, het toevoeggedrag, het flushgedrag, het maximum volume voor het logbestand en het al dan niet opwerpen van een exceptie bij het overschrijven van dat maximum volume in te stellen. Indien je kiest geen exceptie te laten optreden zal een nieuw logbestand wordt gemaakt met dezelfde BaseFileName maar met een nummer uitgebreid.

Voor alle bovenvermelde properties die je at runtime kan instellen, bestaan er ook corresponderende attributen die je at configurationtime kan gebruiken in de Application Configuration File.

boven boven

31.16.7. Beschikbaarheid My.Application.Log en My.Log

My.Application.Log is bruikbaar in Windows Applications, Class Libraries, Console Applications, Windows Control Libraries en Windows Services.

Voor Web Sites en Web Control Libraries gebruik je My.Log.

Beiden zijn te vinden in de assembly ( runtime library ) Microsoft.VisualBasic.dll, gedefinieerd in de namespace Microsoft.VisualBasic.Logging, en zijn dus specifiek voor Visual Basic.

Dit artikel is gepubliceerd op zondag 31 juli 2011 op vbvoorbeelden, bezoek de website voor een recente versie van dit artikel of andere artikels.

visual basic 2010 broncode voorbeelden

31.16. Logging - My.Application.Log Object

XML Transformatie

Instrumenting Applications

Referentie en Conceptuele Documentatie

TraceSource - Application Configuration File - app.config

Logging Application Events

31.16.1. Logging Service

31.16.2. Application Configuration File

31.16.3. FileLogTraceListener.Location Property

31.16.4. Vergelijking met TraceSource

31.16.5. My.Application.Log Enkel Voor Logging

31.16.6. Overige FileLogTraceListener Properties

31.16.7. Beschikbaarheid My.Application.Log en My.Log

31.16.1. Logging Service

31.16.2. Application Configuration File

31.16.3. FileLogTraceListener.Location Property

31.16.4. Vergelijking met TraceSource

31.16.5. My.Application.Log Enkel Voor Logging

31.16.6. Overige FileLogTraceListener Properties

31.16.7. Beschikbaarheid My.Application.Log en My.Log

XML Transformatie

Instrumenting Applications

Referentie en Conceptuele Documentatie

TraceSource - Application Configuration File - app.config

Logging Application Events