This web site uses cookies. By using the site you accept the cookie policy.This message is for compliance with the UK ICO law.

System Information
.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.

Creating a Multi-Instance Counter Category

Counter categories can be single instance or multi-instance. Single instance categories can contain multiple counters but each can only have one value. When you create a multi-instance category, you can create several sets of the counters in the group, giving each set an instance name. The values for each instance can then be monitored individually using Performance Monitor.

In the sample code below, a new category is created to hold counters related to the area sales of a business. The category contains a single counter named, "Total Sales". As the counter is multi-instance, we can add more than one instance of each counter by providing a unique name. In this case the "Total Sales" counter is given two instances to represent the sales for Europe and the USA. Each instance is initialised with a different value.

    "Area Sales", "Sales Performance", PerformanceCounterCategoryType.MultiInstance,
    "Total Sales", "The total number of sales");

PerformanceCounter eu = new PerformanceCounter(
    "Area Sales", "Total Sales", "Europe", false);
eu.RawValue = 50;
PerformanceCounter us = new PerformanceCounter(
    "Area Sales", "Total Sales", "USA", false);
us.RawValue = 80;
27 October 2010