How to: Add and Remove Performance Counter Instances

You can add and remove instances dynamically as you work with counters and categories. For example, you might add an instance for each user of a Web-based retail application so that you could track information about their actions, and then remove the instance when the user's session expires.

You add instances by setting a raw value for a counter. If no instance exists for the counter, an instance is created the first time that you set the RawValue property, and all subsequent actions on the raw value are assumed to affect that instance if no other is specified. You can create additional instances by specifying a new instance name and then setting a value after it.

Note

The process of setting the instance's value, rather than specifying the name of a new instance, creates the instance.

Unlike counters, which cannot be added to an existing category except as part of category creation, instances can be added to and removed from user-defined categories at any time. You can use the InstanceName property to switch between one instance and another.

You can use the RemoveInstance method to remove an instance of a custom performance counter from memory. For example, suppose you have a Web-based retail application that uses a category called OrderInProgress, and within that you maintain instances for each user's current shopping cart. When a user first adds an item to their cart, your application creates a new instance for that user. When the user completes the order, your application deletes the instance. During the order, you update the instance with counters such as NumberofItemsinCart, TimeSinceCreation, and NumberofItemsAddedPerSecond.

You cannot remove instances from the performance counters that are a default part of Windows. If your PerformanceCounter component does not refer to a valid instance, this method will throw an exception.

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 add a performance counter instance

1. Create your categories and counters normally. For more information, see How to: Create Performance Counter Categories.

2. Set the InstanceName property to a unique name for the instance, and then set the instance's RawValue property.

   The following code shows how to create several instances of an existing performance counter category:

   ' Assumes the category and counter have already been created. 
   Dim myCounter As New System.Diagnostics.PerformanceCounter( _
      "cat", "counter", "instance1", False)
   ' Set the raw value to automatically create instance1.
   myCounter.RawValue = 100
   ' State that you will now be working with a different instance.
   myCounter.InstanceName = "instance2" 
   ' Setting the value actually creates instance2.
   myCounter.RawValue = 200
   

   // Assumes category and counter have been created.
           System.Diagnostics.PerformanceCounter myCounter =
              new System.Diagnostics.PerformanceCounter(
              "cat", "counter", "instance1", false);
           // Set the raw value to automatically create instance1.
           myCounter.RawValue = 100;
           // State that you will now be working with a different instance.
           myCounter.InstanceName = "instance2";
           // Setting the value actually creates instance2.
           myCounter.RawValue = 200;
   

To remove a performance counter instance

1. Create an instance of the PerformanceCounter component that is connected to the counter from which you want to remove an instance. For more information, see How to: Create PerformanceCounter Component Instances.

2. Set the InstanceName property to the instance you want to delete.

3. Call the RemoveInstance method on your component.

   The following example shows how to remove an instance called Reference from a counter:

   ' Assumes that you have configured PerformanceCounter1 to 
   ' interact with the appropriate counter.
   PerformanceCounter1.InstanceName = "Reference"
   PerformanceCounter1.RemoveInstance()
   

   // Assumes that you have configured PerformanceCounter1 to 
           // interact with the appropriate counter.
           PerformanceCounter1.InstanceName = "Reference";
           PerformanceCounter1.RemoveInstance();
   

See Also

Tasks

How to: Create PerformanceCounter Component Instances

Concepts

Category and Counter Management