This documentation is archived and is not being maintained.

Creating 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 Creating 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 machines. 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 .NET 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.

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 Accessing and Initializing Server Explorer.
    Note   The Servers node of Server Explorer is not available in the Standard Edition of Visual Basic and Visual C# .NET. For more information, see Visual Basic Standard Edition Features or Visual C# Standard Edition Features.
  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 New Counter frame, do the following:
    1. Specify a name for the counter you want to create within the category.
    2. Choose a type from the Type drop-down list.
    3. Enter a description for the counter.
  5. Click Add to List.
  6. Repeat steps 4 and 5 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 via 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:

    ' Visual Basic
    ' 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.
    ' Create the category and pass the collection to it.
    PerformanceCounterCategory.Create( _
       "Multi Counter Category", "Category help", CounterDatas)
    // C#
    // 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.
    // Create the category and pass the collection to it.
       "Multi Counter Category", "Category help", CounterDatas);

See Also

Accessing and Initializing Server Explorer | Creating Performance Counter Categories | Category and Counter Management