Export (0) Print
Expand All

PerformanceCounterCategory.Create Method (String, String, PerformanceCounterCategoryType, String, String)

Registers the custom performance counter category containing a single counter of type NumberOfItems32 on the local computer.

Namespace:  System.Diagnostics
Assembly:  System (in System.dll)

public static PerformanceCounterCategory Create(
	string categoryName,
	string categoryHelp,
	PerformanceCounterCategoryType categoryType,
	string counterName,
	string counterHelp
)

Parameters

categoryName
Type: System.String

The name of the custom performance counter category to create and register with the system.

categoryHelp
Type: System.String

A description of the custom category.

categoryType
Type: System.Diagnostics.PerformanceCounterCategoryType

One of the PerformanceCounterCategoryType values specifying whether the category is MultiInstance, SingleInstance, or Unknown.

counterName
Type: System.String

The name of a new counter to create as part of the new category.

counterHelp
Type: System.String

A description of the counter that is associated with the new custom category.

Return Value

Type: System.Diagnostics.PerformanceCounterCategory
A PerformanceCounterCategory that is associated with the new system category, or performance object.

ExceptionCondition
ArgumentException

counterName is null or is an empty string ("").

-or-

The counter that is specified by counterName already exists.

-or-

counterName has invalid syntax. It might contain backslash characters ("\") or have length greater than 80 characters.

InvalidOperationException

The category already exists on the local computer.

ArgumentNullException

categoryName is null.

-or-

counterHelp is null.

Win32Exception

A call to an underlying system API failed.

UnauthorizedAccessException

Code that is executing without administrative privileges attempted to read a performance counter.

The categoryType parameter specifies whether the performance counter category is single-instance or multi-instance. By default, a category is single-instance when it is created and becomes multi-instance when another instance is added. Categories are created when an application is set up, and instances are added at run time. In the .NET Framework versions 1.0 and 1.1, it is not necessary to know if a performance counter category is multi-instance or single-instance. In the .NET Framework 2.0, the PerformanceCounterCategoryType enumeration is used to indicate whether a performance counter can have multiple instances.

Performance counter categories installed with the .NET Framework 2.0 use separate shared memory, with each performance counter category having its own memory. You can specify the size of separate shared memory by creating a DWORD named FileMappingSize in the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\<category name>\Performance. The FileMappingSize value is set to the shared memory size of the category. The default size is 131072 decimal. If the FileMappingSize value is not present, the fileMappingSize attribute value for the performanceCounters element specified in the Machine.config file is used, causing additional overhead for configuration file processing. You can realize a performance improvement for application startup by setting the file mapping size in the registry.

NoteNote

It is strongly recommended that new performance counter categories be created during the installation of the application, not during the execution of the application. This allows time for the operating system to refresh its list of registered performance counter categories. If the list has not been refreshed, the attempt to use the category will fail.

NoteNote

To read performance counters in Windows Vista and later, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges.

To avoid having to elevate your privileges to access performance counters in Windows Vista and later, add yourself to the Performance Monitor Users group.

In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator.

The following code example shows the use of the Create method. The example shows how to create a custom, single instance performance counter category.

Console.WriteLine("Creating Inventory custom counter");
if (!PerformanceCounterCategory.Exists("Inventory"))
    PerformanceCounterCategory.Create("Inventory",
        "Truck inventory",
        PerformanceCounterCategoryType.SingleInstance,
        "Trucks", "Number of trucks on hand");

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft