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 placed 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, 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 within a new category. For more information, see How to: Create Performance Counter Categories.

There are two special issues to be aware of when creating 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, be aware 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
The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. 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 need 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.

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 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 within 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 of the counters in the Counters list and edit their values, or delete the counters.

   Note
   Counters and categories you create in the dialog box are read-write enabled by default, 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);
   

   // 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.set_CounterName("Counter1");
   cdCounter1.set_CounterHelp("help string1");
   cdCounter1.set_CounterType(System.Diagnostics.PerformanceCounterType.NumberOfItems64);
   cdCounter2.set_CounterName("Counter2");
   cdCounter2.set_CounterHelp("help string 2");
   cdCounter2.set_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

Reference

How to: Access and Initialize Server Explorer/Database Explorer

Concepts

Category and Counter Management