.NET 1.1+

Reading Performance Counters

by Richard Carr, published at http://www.blackwasp.co.uk/ReadPerformanceCounters.aspx

Microsoft Windows provides a large number of categorised performance counters that can be used to monitor the utilisation of hardware, services, software applications and drivers. Usually viewed with Performance Monitor, they can also be read using C#.

Performance Counters

Microsoft Windows provides a set of counters that can be used to determine how well the operating system, hardware, services and drivers are performing. In addition, applications can register their own performance counters so that key statistical information can be published. This information is often monitored using tools such as the Windows Performance Monitor and is used to identify performance problems and bottlenecks.

Performance counters are categorised according to the hardware or software that they report upon. For example, the "Processor" category includes counters that indicate the percentage of available processor time that is being utilised and the percentage being spent on user tasks. Some counters include multiple instance values. For example, separate instances of the processor time counters are available for each processor.

To read values from performance counters you must have the appropriate permissions. To follow the examples, you should run the program as an administrative user or as a member of the "Performance Monitor Users" group.

Reading Performance Counters

The .NET framework includes several classes that permit you to read performance counter values. In this article we will use the PerformanceCounter class from the System.Diagnostics namespace. This class can be used both to read performance counters and to publish information for custom counters. We will concentrate on the former, creating a simple Windows Forms application that periodically displays the values from two counters.

Creating the Test Application

To begin, create a new Windows Forms application. Add two labels to the form that is created automatically for you, naming the controls "MemoryLabel" and "ProcessorLabel". These labels will be used to display the number of bytes of memory available and the percentage of total processor time that is being used. Set the AutoSize property for each label to True to ensure that they will be large enough to show the performance counter data.

The labels will be updated once per second using a Timer control. Add a Timer control to the form, naming it "PerformanceTimer". Set the Enabled property of the control to true and the Interval to 1,000 milliseconds. Finally, double-click the timer control to add the Tick event and associated method.

As the PerformanceCounter class is found in the System.Diagnostics namespace, add the following using directive to the form's code:

using System.Diagnostics;

Reading a Single Instance Counter

With the basic form created, we can now add the code to display the performance counter information. To begin, we need a PerformanceCounter instance, which we will use to attach to the counter that provides the number of bytes of free memory. The performance counter that we will use is named, "Available Bytes" and is found in the "Memory" category. This is a single instance counter so we will not be required to specify the name of an instance.

You could create the object using the default constructor, then setting the CategoryName and CounterName properties. However, it is simpler to specify these values in an overloaded version of the constructor. The overload that we require accepts two string parameters. The first specifies the name of the category and the second is the name of the performance counter.

To create the object, add the following declaration within the class's code block. NB: This is a class-level variable and should not appear within a method.

private PerformanceCounter _memoryCounter
    = new PerformanceCounter("Memory", "Available Bytes");

To read the value of the performance counter, you can call its NextValue method. This returns a float, which we can convert to a string and display using the Text property of one of the labels. Add the following line of code to the timer's Tick event and run the program to see the available memory value updating once per second.

MemoryLabel.Text = _memoryCounter.NextValue().ToString("0");

NB: The PerformanceCounter class implements IDisposable. Although not shown in this simple example, you should always call either the Close or Dispose method of a PerformanceCounter object that is no longer required.

Reading a Multi-Instance Counter

When reading a performance counter that has multiple instances, you must specify the instance to read using the InstanceName property. You can also use another variation upon the PerformanceCounter constructor. This version accepts the instance name as a third argument. The second performance counter that we will interrogate is the "% Processor Time" counter that resides within the "Processor" category. This counter has instances for each processor as well as an instance named "_Total" that returns the combined processor utilisation.

To attach to the new performance counter add the following class-scope declaration:

private PerformanceCounter _processorCounter
    = new PerformanceCounter("Processor", "% Processor Time", "_Total");

You can now add the following line of code to the Tick event to display the counter value in the other Label control:

ProcessorLabel.Text = _processorCounter.NextValue().ToString("0.0");

When you run the program, you may notice that the processor utilisation value is initially set to zero. This is because the performance counter is a two-read counter. Such counters return incremental values that represent the average or total for the period between calls to the NextValue method.