This documentation is archived and is not being maintained.

Configuring PerformanceCounter Component Instances

There are a variety of properties you must set on the PerformanceCounter components you create. These determine the counter with which the component interacts. The properties you must set include:

  • CategoryName, which determines the performance object with which the component will interact. All performance counters in Windows are grouped by categories, such as Memory, Processes, and Processor.
  • CounterName, which identifies the counter within the specified category with which the component will interact.
  • InstanceName, which identifies the instance of the category with which the component will interact. Note that many categories do not contain instances, so this property might be left blank, indicating a single instance counter.
    Note   If the Category has been set to a category that was not defined by the user, you must choose from existing counters and instances. You can only create new counters and instances in custom categories. For example, you cannot create a new counter in the Memory category, but if you create a new category called Orders, you can define as many counters and instances as you need within that category.
  • MachineName, which identifies the server on which the performance counter with which you want your component to interact resides. You can set this property to "." to indicate the local machine or leave it blank to default to this value.
  • ReadOnly, which determines whether any custom counter you create can be written to. By default, any PerformanceCounter component instances you configure to work with existing Windows counters function in read-only mode and will not allow you to change values in these counters. When you configure your component instance to work with a custom counter, however, you have a choice to accept the default of working in read-only mode, or resetting the property value to false to allow values to be written.
    Note   You can write counters only on the local machine. If you intend to read counter values, you can choose any computer to which you have access.

To configure an instance of the PerformanceCounter component

  1. Create an instance of the PerformanceCounter component. For more information, see Creating PerformanceCounter Component Instances.
  2. Indicate the counter with which your component should interact by setting the following properties.
    MachineNameAny server to which you have access.
    CategoryNameAny category that exists on the server.
    CounterNameAny counter within the selected category.
  3. If the counter with which you are interacting has several instances, set the appropriate one as the value of the InstanceName property.
  4. If you are working with a custom counter and want write access, set the ReadOnly property to false.
    Note   You can specify these properties either in the Properties window, in code, or by using special forms of the constructor for the PerformanceCounter component instance.

    The following example shows how you would set these values programmatically to connect to an existing Windows performance counter called "aborted transactions" on the local server.

    ' Visual Basic
    ' Connect to an existing Windows counter and category
    Dim abortedTransactions As New PerformanceCounter()
    abortedTransactions.CategoryName = _
       "distributed transaction coordinator"
    abortedTransactions.CounterName = "aborted transactions"
    abortedTransactions.MachineName = "."
    ' Connect to a custom counter and category in writable mode
    PerformanceCounterCategory.Create("orders", "desc", "milk", "desc")
    Dim myCounter2 As New PerformanceCounter("orders", "milk", False)
    // C#
    // Connect to an existing Windows counter and category
    System.Diagnostics.PerformanceCounter abortedTransactions =
       new System.Diagnostics.PerformanceCounter();
    abortedTransactions.CategoryName = 
       "distributed transaction coordinator";
    abortedTransactions.CounterName = "aborted transactions";
    abortedTransactions.MachineName = ".";
    // Connect to a custom counter and category in writable mode
       "orders", "desc", "milk", "desc");
    System.Diagnostics.PerformanceCounter myCounter2 = 
       new System.Diagnostics.PerformanceCounter("orders", "milk", false);
    Note   In this code, "." represents the local machine.

See Also

Creating PerformanceCounter Component Instances | Creating Custom Performance Counters | Category and Counter Management