.NET Instrumentation Workshop
Home About Workshops Articles Writing Talks Books Contact

.NET Instrumentation Workshop

This is a self paced workshop designed to teach you what instrumentation is, why you will want to use it and how to instrument your .NET code.

This Workshop Will Teach You

  • Conditional Code
  • Tracing
  • Asserts
  • .NET Trace Sources and Trace Listeners
  • Performance Counters
  • The Event Log


There are two main uses for instrumentation: one is strictly for debug mode, the other is for both debug and release mode. During the testing and debug phase of your application development you will want to trace values to give you an idea about what code is called and what values are being generated. This information is of no use whatsoever to anyone outside of your development team and hence such information should only be generated in debug mode. The other use of instrumentation is to log information while your application runs. Such logging should be restrictive and typically will log critical information. It is vital to realise the difference between the two.

This workshop will lead you through all the kinds of instrumentation and help you decide the best way to instrument your code.

The example code for this workshop can be found here.


This workshop was originally written for .NET version 2.0 on Windows XP. Since then Microsoft have released 'version 3.0' of the .NET framework. However (with a few minor changes), this is merely version 2.0 distributed with the WinFX library. This means that in most cases .NET 2.0 and .NET 3.0 are interchangeable. When I say version 3.0 you can assume that I also mean version 2.0. Many of the features are also available with 1.0 and 1.1 but the features may be restricted compared to 2.0. If I do not mention a version then you should assume that the text refers to all versions of .NET which means 3.0, 2.0, 1.1 and 1.0.

The demonstrations will use the command line tools provided by the .NET SDK and the code will be written in C#. The example code can easily be converted to other .NET languages and can easily be converted to VS.NET projects.

The examples in this workshop will use the following tools:

Tool Path Description
csc <CORFolder>\csc.exe The C# compiler
fuslogvw <SDKFolder>\bin\fuslogvw.exe The Fusion log viewer
gacutil <SDKFolder>\bin\gacutil.exe The GAC utility
ildasm <SDKFolder>\bin\ildasm.exe The IL disassembly tool
nmake <SDKFolder>\bin\nmake.exe Program maintenance utility
sn <SDKFolder>\bin\sn.exe The strong name generator

Here, <CORFolder> is the location of the .NET framework assemblies (%systemroot%\Microsoft.NET\Framework\vx.x.xxx), <SDKFolder> is the location of the .NET SDK (usually it is in the Visual Studio folder). To do the examples in the workshop you should ensure that your command line path is set to give access to the folders in the table. The simplest way to do this is to run the vsvars32.bat file in the Common7\Tools folder in the Visual Studio .NET folder.


There is no charge for this tutorial, if this workshop was published as a book then you would pay $50 for it, if I were to give you this workshop as a training session then you would have to pay several thousand dollars, instead, you get it entirely for free. If you want to show your appreciation for the effort I have put into this workshop then please consider making a donation through Paypal. 

I give training courses and conference talks, and I write white papers and books on a variety of .NET topics; I also architect systems and perform code reviews. Please contact me if you want me to provide my services for you.


1. Instrumentation
1.1 Basic Tenets Of Instrumentation
1.2 Instrumentation In .NET
1.3 Why Instrument Code?

2. Conditional Code
2.1 Conditional Compilation
2.2 Conditional Code
2.3 Switches
2.4 .NET Switches
2.5 Switch Attributes
2.6 Monitoring

3. Tracing Code
3.1 Architecture
3.2 Trace Messages
3.3 Localization Of Messages

4. Trace Listeners
4.1 Framework Trace Listeners
4.2 DefaultTraceListener
4.3 TextWriterTraceListener
4.4 EventLogTraceListener
4.5 .NET 2.0 Trace Listeners
4.6 Redirecting Console Streams
4.7 VB.NET Logging

5. Asserts
5.1 Windows Error Dialogs
5.2 Fail
5.3 Assert
5.4 What Should You Asset?

6. .NET 2.0 Trace Sources
6.1 TraceSource
6.2 Trace Options
6.3 Tracing Methods
6.4 Configuration
6.5 Attributes
6.6 Filters
6.7 Work In Progress

7. Performance Counters
7.1 Performance Monitor Example
7.2 Performance Monitor Registration
7.3 Reading .NET Performance Counters
7.4 Providing .NET Performance Counters
7.5 Performance Counter Installers

8. Event Log
8.1 The Event Log Architecture
8.2 What Is The Event Log For?
8.3 The Event Log Viewer
8.4 Reading The Event Log
8.5 Event Messages
8.6 How Microsoft Wants You To Write To The Event Log
8.7 The Right Way To Write To The Event Log
8.8 More About Reporting Events
8.9 Event Log Installers
8.10 What Should You Log?

I hope that you enjoy this tutorial and value the knowledge that you will gain from it. This tutorial is free and will always remain free.

This page is (c) 2006 Richard Grimes, all rights reserved