PerformanceCounterCategory.Create Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Registers a custom performance counter category and one or more counters with the system.
Overloads
| Create(String, String, String, String) |
Obsolete.
Obsolete.
Obsolete.
Registers a custom performance counter category containing a single counter of type |
| Create(String, String, PerformanceCounterCategoryType, String, String) |
Registers the custom performance counter category containing a single counter of type NumberOfItems32 on the local computer. |
| Create(String, String, CounterCreationDataCollection) |
Obsolete.
Obsolete.
Obsolete.
Registers the custom performance counter category containing the specified counters on the local computer. |
| Create(String, String, PerformanceCounterCategoryType, CounterCreationDataCollection) |
Registers the custom performance counter category containing the specified counters on the local computer. |
Create(String, String, String, String)
Caution
This overload of PerformanceCounterCategory.Create has been deprecated. Use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, string counterName, string counterHelp) instead.
Caution
This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, string counterName, string counterHelp) instead. http://go.microsoft.com/fwlink/?linkid=14202
Caution
This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, string counterName, string counterHelp) instead. https://go.microsoft.com/fwlink/?linkid=14202
Registers a custom performance counter category containing a single counter of type NumberOfItems32 on the local computer.
public:
static System::Diagnostics::PerformanceCounterCategory ^ Create(System::String ^ categoryName, System::String ^ categoryHelp, System::String ^ counterName, System::String ^ counterHelp);[System.Obsolete("This overload of PerformanceCounterCategory.Create has been deprecated. Use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, string counterName, string counterHelp) instead.")]
public static System.Diagnostics.PerformanceCounterCategory Create(string categoryName, string categoryHelp, string counterName, string counterHelp);public static System.Diagnostics.PerformanceCounterCategory Create(string categoryName, string categoryHelp, string counterName, string counterHelp);[System.Obsolete("This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, string counterName, string counterHelp) instead. http://go.microsoft.com/fwlink/?linkid=14202")]
public static System.Diagnostics.PerformanceCounterCategory Create(string categoryName, string categoryHelp, string counterName, string counterHelp);[System.Obsolete("This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, string counterName, string counterHelp) instead. https://go.microsoft.com/fwlink/?linkid=14202")]
public static System.Diagnostics.PerformanceCounterCategory Create(string categoryName, string categoryHelp, string counterName, string counterHelp);[<System.Obsolete("This overload of PerformanceCounterCategory.Create has been deprecated. Use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, string counterName, string counterHelp) instead.")>]
static member Create : string * string * string * string -> System.Diagnostics.PerformanceCounterCategorystatic member Create : string * string * string * string -> System.Diagnostics.PerformanceCounterCategory[<System.Obsolete("This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, string counterName, string counterHelp) instead. http://go.microsoft.com/fwlink/?linkid=14202")>]
static member Create : string * string * string * string -> System.Diagnostics.PerformanceCounterCategory[<System.Obsolete("This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, string counterName, string counterHelp) instead. https://go.microsoft.com/fwlink/?linkid=14202")>]
static member Create : string * string * string * string -> System.Diagnostics.PerformanceCounterCategoryPublic Shared Function Create (categoryName As String, categoryHelp As String, counterName As String, counterHelp As String) As PerformanceCounterCategoryParameters
- categoryName
- String
The name of the custom performance counter category to create and register with the system.
- categoryHelp
- String
A description of the custom category.
- counterName
- String
The name of a new counter, of type NumberOfItems32, to create as part of the new category.
- counterHelp
- String
A description of the counter that is associated with the new custom category.
Returns
A PerformanceCounterCategory that is associated with the new system category, or performance object.
- Attributes
Exceptions
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.
The category already exists on the local computer.
A call to an underlying system API failed.
Code that is executing without administrative privileges attempted to read a performance counter.
Remarks
Note
To read performance counters from a non-interactive logon session 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.
See also
Applies to
Create(String, String, PerformanceCounterCategoryType, String, String)
Registers the custom performance counter category containing a single counter of type NumberOfItems32 on the local computer.
public:
static System::Diagnostics::PerformanceCounterCategory ^ Create(System::String ^ categoryName, System::String ^ categoryHelp, System::Diagnostics::PerformanceCounterCategoryType categoryType, System::String ^ counterName, System::String ^ counterHelp);public static System.Diagnostics.PerformanceCounterCategory Create(string categoryName, string categoryHelp, System.Diagnostics.PerformanceCounterCategoryType categoryType, string counterName, string counterHelp);static member Create : string * string * System.Diagnostics.PerformanceCounterCategoryType * string * string -> System.Diagnostics.PerformanceCounterCategoryPublic Shared Function Create (categoryName As String, categoryHelp As String, categoryType As PerformanceCounterCategoryType, counterName As String, counterHelp As String) As PerformanceCounterCategoryParameters
- categoryName
- String
The name of the custom performance counter category to create and register with the system.
- categoryHelp
- String
A description of the custom category.
- categoryType
- PerformanceCounterCategoryType
One of the PerformanceCounterCategoryType values specifying whether the category is MultiInstance, SingleInstance, or Unknown.
- counterName
- String
The name of a new counter to create as part of the new category.
- counterHelp
- String
A description of the counter that is associated with the new custom category.
Returns
A PerformanceCounterCategory that is associated with the new system category, or performance object.
Exceptions
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.
The category already exists on the local computer.
A call to an underlying system API failed.
Code that is executing without administrative privileges attempted to read a performance counter.
Examples
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");
Console.WriteLine("Creating Inventory custom counter")
If Not PerformanceCounterCategory.Exists("Inventory") Then
PerformanceCounterCategory.Create("Inventory", "Truck inventory", PerformanceCounterCategoryType.SingleInstance, "Trucks", "Number of trucks on hand")
End If
Remarks
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. The PerformanceCounterCategoryType enumeration is used to indicate whether a performance counter can have multiple instances.
Performance counter categories installed with .NET 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.
Note
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.
Note
To read performance counters from a non-interactive logon session 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.
See also
Applies to
Create(String, String, CounterCreationDataCollection)
Caution
This overload of PerformanceCounterCategory.Create has been deprecated. Use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, CounterCreationDataCollection counterData) instead.
Caution
This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, CounterCreationDataCollection counterData) instead. http://go.microsoft.com/fwlink/?linkid=14202
Caution
This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, CounterCreationDataCollection counterData) instead. https://go.microsoft.com/fwlink/?linkid=14202
Registers the custom performance counter category containing the specified counters on the local computer.
public:
static System::Diagnostics::PerformanceCounterCategory ^ Create(System::String ^ categoryName, System::String ^ categoryHelp, System::Diagnostics::CounterCreationDataCollection ^ counterData);[System.Obsolete("This overload of PerformanceCounterCategory.Create has been deprecated. Use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, CounterCreationDataCollection counterData) instead.")]
public static System.Diagnostics.PerformanceCounterCategory Create(string categoryName, string categoryHelp, System.Diagnostics.CounterCreationDataCollection counterData);public static System.Diagnostics.PerformanceCounterCategory Create(string categoryName, string categoryHelp, System.Diagnostics.CounterCreationDataCollection counterData);[System.Obsolete("This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, CounterCreationDataCollection counterData) instead. http://go.microsoft.com/fwlink/?linkid=14202")]
public static System.Diagnostics.PerformanceCounterCategory Create(string categoryName, string categoryHelp, System.Diagnostics.CounterCreationDataCollection counterData);[System.Obsolete("This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, CounterCreationDataCollection counterData) instead. https://go.microsoft.com/fwlink/?linkid=14202")]
public static System.Diagnostics.PerformanceCounterCategory Create(string categoryName, string categoryHelp, System.Diagnostics.CounterCreationDataCollection counterData);[<System.Obsolete("This overload of PerformanceCounterCategory.Create has been deprecated. Use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, CounterCreationDataCollection counterData) instead.")>]
static member Create : string * string * System.Diagnostics.CounterCreationDataCollection -> System.Diagnostics.PerformanceCounterCategorystatic member Create : string * string * System.Diagnostics.CounterCreationDataCollection -> System.Diagnostics.PerformanceCounterCategory[<System.Obsolete("This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, CounterCreationDataCollection counterData) instead. http://go.microsoft.com/fwlink/?linkid=14202")>]
static member Create : string * string * System.Diagnostics.CounterCreationDataCollection -> System.Diagnostics.PerformanceCounterCategory[<System.Obsolete("This method has been deprecated. Please use System.Diagnostics.PerformanceCounterCategory.Create(string categoryName, string categoryHelp, PerformanceCounterCategoryType categoryType, CounterCreationDataCollection counterData) instead. https://go.microsoft.com/fwlink/?linkid=14202")>]
static member Create : string * string * System.Diagnostics.CounterCreationDataCollection -> System.Diagnostics.PerformanceCounterCategoryPublic Shared Function Create (categoryName As String, categoryHelp As String, counterData As CounterCreationDataCollection) As PerformanceCounterCategoryParameters
- categoryName
- String
The name of the custom performance counter category to create and register with the system.
- categoryHelp
- String
A description of the custom category.
- counterData
- CounterCreationDataCollection
A CounterCreationDataCollection that specifies the counters to create as part of the new category.
Returns
A PerformanceCounterCategory that is associated with the new custom category, or performance object.
- Attributes
Exceptions
A counter name that is specified within the counterData collection is null or an empty string ("").
-or-
A counter that is specified within the counterData collection already exists.
The categoryName parameter is null.
The category already exists on the local computer.
-or-
The layout of the counterData collection is incorrect for base counters. A counter of type AverageCount64, AverageTimer32, CounterMultiTimer, CounterMultiTimerInverse, CounterMultiTimer100Ns, CounterMultiTimer100NsInverse, RawFraction, SampleFraction or SampleCounter has to be immediately followed by one of the base counter types (AverageBase, MultiBase, RawBase, or SampleBase).
A call to an underlying system API failed.
Code that is executing without administrative privileges attempted to read a performance counter.
Remarks
Note
To read performance counters from a non-interactive logon session 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.
See also
Applies to
Create(String, String, PerformanceCounterCategoryType, CounterCreationDataCollection)
Registers the custom performance counter category containing the specified counters on the local computer.
public:
static System::Diagnostics::PerformanceCounterCategory ^ Create(System::String ^ categoryName, System::String ^ categoryHelp, System::Diagnostics::PerformanceCounterCategoryType categoryType, System::Diagnostics::CounterCreationDataCollection ^ counterData);public static System.Diagnostics.PerformanceCounterCategory Create(string categoryName, string categoryHelp, System.Diagnostics.PerformanceCounterCategoryType categoryType, System.Diagnostics.CounterCreationDataCollection counterData);static member Create : string * string * System.Diagnostics.PerformanceCounterCategoryType * System.Diagnostics.CounterCreationDataCollection -> System.Diagnostics.PerformanceCounterCategoryPublic Shared Function Create (categoryName As String, categoryHelp As String, categoryType As PerformanceCounterCategoryType, counterData As CounterCreationDataCollection) As PerformanceCounterCategoryParameters
- categoryName
- String
The name of the custom performance counter category to create and register with the system.
- categoryHelp
- String
A description of the custom category.
- categoryType
- PerformanceCounterCategoryType
One of the PerformanceCounterCategoryType values.
- counterData
- CounterCreationDataCollection
A CounterCreationDataCollection that specifies the counters to create as part of the new category.
Returns
A PerformanceCounterCategory that is associated with the new custom category, or performance object.
Exceptions
A counter name that is specified within the counterData collection is null or an empty string ("").
-or-
A counter that is specified within the counterData collection already exists.
categoryType value is outside of the range of the following values: MultiInstance, SingleInstance, or Unknown.
The category already exists on the local computer.
-or-
The layout of the counterData collection is incorrect for base counters. A counter of type AverageCount64, AverageTimer32, CounterMultiTimer, CounterMultiTimerInverse, CounterMultiTimer100Ns, CounterMultiTimer100NsInverse, RawFraction, SampleFraction, or SampleCounter must be immediately followed by one of the base counter types (AverageBase, MultiBase, RawBase, or SampleBase).
A call to an underlying system API failed.
Code that is executing without administrative privileges attempted to read a performance counter.
Examples
The following code example shows the use of the Create method. The example shows how to create a custom, multi-instance performance counter category for the number of orders per second.
CounterCreationData data1 = new CounterCreationData("Trucks",
"Number of orders", PerformanceCounterType.NumberOfItems32);
CounterCreationData data2 = new CounterCreationData("Rate of sales",
"Orders/second", PerformanceCounterType.RateOfCountsPerSecond32);
CounterCreationDataCollection ccds = new CounterCreationDataCollection();
ccds.Add(data1);
ccds.Add(data2);
Console.WriteLine("Creating Orders custom counter.");
if (!PerformanceCounterCategory.Exists("Orders"))
PerformanceCounterCategory.Create("Orders",
"Processed orders",
PerformanceCounterCategoryType.MultiInstance,
ccds);
Dim data1 As New CounterCreationData("Trucks", "Number of orders", PerformanceCounterType.NumberOfItems32)
Dim data2 As New CounterCreationData("Rate of sales", "Orders/second", PerformanceCounterType.RateOfCountsPerSecond32)
Dim ccds As New CounterCreationDataCollection()
ccds.Add(data1)
ccds.Add(data2)
Console.WriteLine("Creating Orders custom counter.")
If Not PerformanceCounterCategory.Exists("Orders") Then
PerformanceCounterCategory.Create("Orders", "Processed orders", PerformanceCounterCategoryType.MultiInstance, ccds)
End If
Remarks
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. The PerformanceCounterCategoryType enumeration is used to indicate whether a performance counter can have multiple instances.
Performance counter categories installed with .NET 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.
Note
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.
Note
To read performance counters from a non-interactive logon session 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.
