How to: Create Custom Performance Counters

When you create a new counter, you first create a category, and then specify one or more counters to be included in it. You can do this in one of the following ways:

• You can use Server Explorer to create one or more counters at design time.

• You can use the CounterCreationData class to create one or more counters programmatically, and then add them to a collection of type CounterCreationDataCollection and pass the collection as a parameter of a special form of the Create method.

• You can use the Create method on the PerformanceCounterCategory class to create a single counter in a new category. For more information, see How to: Create Performance Counter Categories.

There are two special issues that you should consider when you create counters and categories. First, you cannot create custom categories and counters on remote computers. Second, your interaction with custom counters and categories is restricted to read-only mode unless you explicitly specify otherwise. In read-only mode, you cannot increment or decrement them or set the raw value or other values within them. You can use the ReadOnly property to set a custom counter to writable mode.

It is important to note the difference between creating a counter and creating an instance of the PerformanceCounter component. When you create a counter, you are creating a new category and its associated counters in the Windows operating system, rather than a component in your project or application. When you create an instance of the PerformanceCounter component, you create a component inside your Visual Studio project that references an external counter.

Note

There are security restrictions that affect your ability to use performance counters. For more information, see Introduction to Monitoring Performance Thresholds.

Security Note:
When you create a performance counter, realize that the resource may already exist. Another process, perhaps a malicious one, may have already created the resource and have access to it. When you put data in the performance counter, the data is available to the other process.

Note

The PerformanceCounter class is not fully supported on Microsoft Windows NT version 4.0. You can read from the system counters, but you cannot create, write to, or delete custom counters.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

To create a new category and custom performance counter at design time

1. Open Server Explorer and expand the node for the server you want to view.

   Note

   If the server you want is not listed, you have to add it. For more information, see How to: Access and Initialize Server Explorer/Database Explorer.

2. Right-click the Performance Counters node and select Create New Category.

   The Performance Counter Builder dialog box appears.

   Note

   To access performance counters, you have to be a member of the security group that has access to performance counters (for example, the Performance Monitor Users group). Additionally, you might receive prompts on Windows Vista when you try to perform an action that requires elevated privileges, even when you are running under administrative permissions. For more information, see Windows Vista and Visual Studio.

3. Enter a name and description for the category you want to create.

   Note

   If you specify the name of an existing category, an error will be raised. To overwrite an existing counter category, you must first delete the category by using the Delete method, and then add a new category.

4. In the Counter List Builder frame, do the following:

   1. Click the New button.

   2. In the Counter frame, specify a name for the counter you want to create in the category.

   3. Choose a type from the Type drop-down list.

   4. Enter a description for the counter.

5. Repeat step 4 for each counter you want to create in this category.

   Tip

   Before you exit the dialog box, you can select any one of the counters in the Counters list and edit their values, or delete the counters.

   Note

   By default, counters and categories you create in the dialog box are read-write enabled, but your interaction with them through an instance of the PerformanceCounter component will be restricted to read-only unless you specify otherwise.

To create a new category and set of performance counters programmatically

1. Create a collection of type CounterCreationDataCollection.

2. Create the counters you want to create as objects of type CounterCreationData and set their necessary properties.

3. Add the CounterCreationData objects to the collection by calling the collection's Add method.

4. Call the Create method on the PerformanceCounterCategory class and pass the collection to it.

   The following example shows how to create a series of counters and pass them to the category when you create it:

   ' Create a collection of type CounterCreationDataCollection. 
   Dim CounterDatas As New CounterCreationDataCollection()
   ' Create the counters and set their properties. 
   Dim cdCounter1 As New CounterCreationData()
   Dim cdCounter2 As New CounterCreationData()
   cdCounter1.CounterName = "MyCounter1"
   cdCounter1.CounterHelp = "help string"
   cdCounter1.CounterType = PerformanceCounterType.NumberOfItems64
   cdCounter2.CounterName = "MyCounter2"
   cdCounter2.CounterHelp = "help string 2"
   cdCounter2.CounterType = PerformanceCounterType.NumberOfItems64
   ' Add both counters to the collection.
   CounterDatas.Add(cdCounter1)
   CounterDatas.Add(cdCounter2)
   ' Create the category and pass the collection to it.
   PerformanceCounterCategory.Create("Multi Counter Category", _
       "Category help", PerformanceCounterCategoryType.SingleInstance, _
       CounterDatas)
   

   // Create a collection of type CounterCreationDataCollection.
           System.Diagnostics.CounterCreationDataCollection CounterDatas =
              new System.Diagnostics.CounterCreationDataCollection();
           // Create the counters and set their properties.
           System.Diagnostics.CounterCreationData cdCounter1 =
              new System.Diagnostics.CounterCreationData();
           System.Diagnostics.CounterCreationData cdCounter2 =
              new System.Diagnostics.CounterCreationData();
           cdCounter1.CounterName = "Counter1";
           cdCounter1.CounterHelp = "help string1";
           cdCounter1.CounterType = System.Diagnostics.PerformanceCounterType.NumberOfItems64;
           cdCounter2.CounterName = "Counter2";
           cdCounter2.CounterHelp = "help string 2";
           cdCounter2.CounterType = System.Diagnostics.PerformanceCounterType.NumberOfItems64;
           // Add both counters to the collection.
           CounterDatas.Add(cdCounter1);
           CounterDatas.Add(cdCounter2);
           // Create the category and pass the collection to it.
           System.Diagnostics.PerformanceCounterCategory.Create(
               "Multi Counter Category", "Category help",
               PerformanceCounterCategoryType.SingleInstance, CounterDatas);
   

See Also

Tasks

How to: Create Performance Counter Categories

Concepts

Category and Counter Management

Reference

How to: Access and Initialize Server Explorer/Database Explorer