Share via


How to: Configure 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.

    NoteNote

    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 computer 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.

    NoteNote

    You can write counters only on the local computer. 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 How to: Create PerformanceCounter Component Instances.

  2. Indicate the counter with which your component should interact by setting the following properties.

    Property Setting

    MachineName

    Any server to which you have access.

    CategoryName

    Any category that exists on the server.

    CounterName

    Any 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.

    NoteNote

    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.

    ' 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", _
    PerformanceCounterCategoryType.SingleInstance, "milk", "desc")
    Dim myCounter2 As New PerformanceCounter("orders", "milk", False)
    
    // 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
    System.Diagnostics.PerformanceCounterCategory.Create(
       "orders", "desc", PerformanceCounterCategoryType.SingleInstance,
       "milk", "desc");
    System.Diagnostics.PerformanceCounter myCounter2 =
       new System.Diagnostics.PerformanceCounter("orders", "milk", false);
    
    // Connect to an existing Windows counter and category
    System.Diagnostics.PerformanceCounter abortedTransactions =
       new System.Diagnostics.PerformanceCounter();
    abortedTransactions.set_CategoryName(
       "distributed transaction coordinator");
    abortedTransactions.set_CounterName("aborted transactions");
    abortedTransactions.set_MachineName(".");
    // Connect to a custom counter and category in writeable mode
    System.Diagnostics.PerformanceCounterCategory.Create(
       "orders", "desc", "milk", "desc");
    System.Diagnostics.PerformanceCounter myCounter2 = 
       new System.Diagnostics.PerformanceCounter("orders", "milk", false);
    
    NoteNote

    In this code, "." represents the local computer.

See Also

Tasks

How to: Create PerformanceCounter Component Instances
How to: Create Custom Performance Counters

Concepts

Category and Counter Management