.NET 2.0+

Creating Performance Counters Programmatically

Performance counters allow numerical information about the current state of the operating system or an application to be recorded and monitored using standard tools. This article explains how to create custom performance counters using C# code.

Performance Counters

In previous articles I have explained the use of performance counters to allow monitoring of the state of the operating system, hardware, services, drivers and software applications. These topics were described in the articles, "Reading Performance Counters" and "Setting Performance Counters". The latter of those articles showed how the values of existing counters can be modified and how new counters could be created using the tools provided by Visual Studio.

When deploying software using a setup package or other installation routine, you cannot rely on the manual creation of performance counters. Instead, you should create any new counters programmatically during installation. They will then be available for use from within your software. Similarly, when your program is uninstalled, you should remove the counters to correctly clean up the user's computer.

In this article we will create several performance counter categories, each containing one or more counters. The classes used in the process are found in the System.Diagnostics namespace, so to follow the examples you should create a new console application and add the following using directive to the source code.

using System.Diagnostics;

NB: To create performance counters you must have the appropriate permissions. To follow the examples, you should execute the code as an administrative user.

Checking if a Performance Counter Category Exists

Every performance counter exists within a performance counter category. The category and its counters are created at the same time; it is not possible to add counters to an existing category using the methods described in this article. Before you attempt to create a new category, you should check to see if the name is already in use. If you fail to do so and attempt to create a duplicate category, an exception will be thrown.

To determine if a category exists, you can call the static Exists method of the PerformanceCounterCategory class. If the name is already in use, the method returns true. If the return value is false, it is safe to continue with creating the new category.

bool exists = PerformanceCounterCategory.Exists("Sales");

Creating a Single, "Number of Items" Performance Counter

One of the most commonly used performance counter data types is "NumberOfItems32". This allows a single 32-bit integer value to be recorded as required. When you only wish to use this type of counter, and only one value needs to be monitored within a category, you can create the counter and its containing category in a single line of code using the Create method of the PerformanceCounterCategory class.

The overloaded version of the method that we will demonstrate first accepts five arguments. The first two arguments are strings that define a name and some descriptive text for the category. The third parameter is used to specify whether the new counter category will contain a single instance or a multi-instance counter. The final two string arguments are used to provide a name and some helpful text for the counter.

In the sample code below, a category named "Sales" that contains a single instance counter named "Total Sales" is created in the first statement. The last two lines connect to the counter and apply a value. Try executing this code and then loading the Performance Monitor utility and viewing the new counter.

PerformanceCounterCategory.Create("Sales", "Performance counters for worldwide sales",
    PerformanceCounterCategoryType.SingleInstance, "Total Sales",
    "The total number of sales");

PerformanceCounter pc = new PerformanceCounter("Sales", "Total Sales", false);
pc.RawValue = 50;

NB: You should normally not create a counter and immediately apply a value. The counters and categories should be created during the installation process and values should be set when the program is running. This is to ensure that the operating system has time to create new counters before they are used.