From 71b741f9e0e3343a8ae5c0498e956f4ef8573ffd Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 27 Dec 2024 18:02:35 -0800 Subject: [PATCH] fix paramrefs --- xml/System.Device.Location/GeoCoordinate.xml | 264 ++-- xml/System.Diagnostics/ActivityContext.xml | 2 +- xml/System.Diagnostics/ActivityLink.xml | 2 +- xml/System.Diagnostics/EventLog.xml | 18 +- .../PerformanceCounterCategory.xml | 1064 ++++++++--------- xml/System.Diagnostics/ProcessStartInfo.xml | 4 +- xml/System.Diagnostics/TagList.xml | 2 +- .../TraceListenerCollection.xml | 194 +-- .../XmlWriterTraceListener.xml | 348 +++--- .../PrincipalContext.xml | 230 ++-- .../ActiveDirectorySchedule.xml | 194 +-- .../ActiveDirectorySchema.xml | 14 +- ...ctiveDirectorySchemaPropertyCollection.xml | 2 +- .../ActiveDirectorySiteLink.xml | 46 +- .../Domain.xml | 6 +- .../Forest.xml | 142 +-- .../ForestTrustDomainInformation.xml | 2 +- .../ReadOnlyStringCollection.xml | 2 +- .../DirectoryAttribute.xml | 38 +- .../DirectoryRequest.xml | 4 +- .../DsmlRequestDocument.xml | 24 +- .../LdapConnection.xml | 26 +- .../LdapDirectoryIdentifier.xml | 8 +- .../SearchResultEntryCollection.xml | 8 +- .../SearchResultReferenceCollection.xml | 8 +- .../DirectoryServicesPermission.xml | 2 +- .../PropertyCollection.xml | 440 +++---- 27 files changed, 1533 insertions(+), 1561 deletions(-) diff --git a/xml/System.Device.Location/GeoCoordinate.xml b/xml/System.Device.Location/GeoCoordinate.xml index 1bec6ecbf93..f8a27388450 100644 --- a/xml/System.Device.Location/GeoCoordinate.xml +++ b/xml/System.Device.Location/GeoCoordinate.xml @@ -46,13 +46,13 @@ Initializes a new instance of that has no data fields set. - . The new instance of is equivalent to . - - This constructor should be used for serialization. - + . The new instance of is equivalent to . + + This constructor should be used for serialization. + ]]> @@ -84,11 +84,11 @@ The longitude of the location. May range from -180.0 to 180.0. Initializes a new instance of the class from latitude and longitude data. - Latitude or longitude is out of range. @@ -123,11 +123,11 @@ The altitude in meters. May be negative, 0, positive, or , if unknown. Initializes a new instance of the class from latitude, longitude, and altitude data. - @@ -166,7 +166,7 @@ Initializes a new instance of the class from latitude, longitude, altitude, horizontal accuracy, vertical accuracy, speed, and course. To be added. - , , , or is out of range. + , , , , or is out of range. @@ -198,11 +198,11 @@ Gets the altitude of the , in meters. The altitude, in meters. - @@ -232,19 +232,19 @@ Gets or sets the heading in degrees, relative to true north. The heading in degrees, relative to true north. - and properties of the current location's . - + and properties of the current location's . + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinate/Course/courseandspeed.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.courseandspeed/vb/courseandspeed.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.courseandspeed/vb/courseandspeed.vb" id="Snippet2"::: + ]]> @@ -287,11 +287,11 @@ if the objects are equal; otherwise, . - objects have the same and properties. The , , and properties are not used to determine equivalency. - + objects have the same and properties. The , , and properties are not used to determine equivalency. + ]]> @@ -320,11 +320,11 @@ , if the objects are equal; otherwise, . - objects have the same and properties. The , , and properties are not used to determine equivalency. - + objects have the same and properties. The , , and properties are not used to determine equivalency. + ]]> @@ -352,13 +352,13 @@ Returns the distance between the latitude and longitude coordinates that are specified by this and another specified . The distance between the two coordinates, in meters. - @@ -383,11 +383,11 @@ Serves as a hash function for the . A hash code for the current . - objects that are equivalent have the same hash code. Equivalent objects have the same and properties. The , , and properties are not used to determine equivalency. - + objects that are equivalent have the same hash code. Equivalent objects have the same and properties. The , , and properties are not used to determine equivalency. + ]]> @@ -417,11 +417,11 @@ Gets or sets the accuracy of the latitude and longitude that is given by the , in meters. The accuracy of the latitude and longitude, in meters. - @@ -448,19 +448,19 @@ if the does not contain latitude or longitude data; otherwise, . - that does not contain latitude or longitude data is equal to . - - - -## Examples - The following code example verifies whether the that corresponds to a location is before printing out its latitude and longitude. - + that does not contain latitude or longitude data is equal to . + + + +## Examples + The following code example verifies whether the that corresponds to a location is before printing out its latitude and longitude. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinate/IsUnknown/getlocationdatasynchandleunknown.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasynchandleunknown/vb/GetLocationDataSyncHandleUnknown.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasynchandleunknown/vb/GetLocationDataSyncHandleUnknown.vb" id="Snippet1"::: + ]]> @@ -490,19 +490,19 @@ Gets or sets the latitude of the . Latitude of the location. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinate/Latitude/locationevent.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.locationevent1/vb/locationevent.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.locationevent1/vb/locationevent.vb" id="Snippet1"::: + ]]> @@ -534,19 +534,19 @@ Gets or sets the longitude of the . The longitude. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinate/Latitude/locationevent.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.locationevent1/vb/locationevent.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.locationevent1/vb/locationevent.vb" id="Snippet1"::: + ]]> @@ -579,11 +579,11 @@ , if the objects are determined to be equivalent; otherwise, . - objects have the same and properties. The , , and properties are not used to determine equivalency. - + objects have the same and properties. The , , and properties are not used to determine equivalency. + ]]> @@ -614,11 +614,11 @@ , if the objects are determined to be different; otherwise, . - objects have the same and properties. The , , and properties are not used to determine equivalency. - + objects have the same and properties. The , , and properties are not used to determine equivalency. + ]]> @@ -648,14 +648,14 @@ Gets or sets the speed in meters per second. The speed in meters per second. The speed must be greater than or equal to zero, or . - and properties of the current location's . - + and properties of the current location's . + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinate/Course/courseandspeed.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.courseandspeed/vb/courseandspeed.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.courseandspeed/vb/courseandspeed.vb" id="Snippet2"::: + ]]> @@ -682,11 +682,11 @@ Returns a string that contains the latitude and longitude. A string that contains the latitude and longitude, separated by a comma. - @@ -709,19 +709,19 @@ Represents a object that has unknown latitude and longitude fields. - property can be used to verify whether a contains no data. - - - -## Examples - The following code example verifies whether the that corresponds to a location is before printing out its latitude and longitude. - + property can be used to verify whether a contains no data. + + + +## Examples + The following code example verifies whether the that corresponds to a location is before printing out its latitude and longitude. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinate/IsUnknown/getlocationdatasynchandleunknown.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasynchandleunknown/vb/GetLocationDataSyncHandleUnknown.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasynchandleunknown/vb/GetLocationDataSyncHandleUnknown.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Diagnostics/ActivityContext.xml b/xml/System.Diagnostics/ActivityContext.xml index 7aa0fbc4f4d..6329e77da15 100644 --- a/xml/System.Diagnostics/ActivityContext.xml +++ b/xml/System.Diagnostics/ActivityContext.xml @@ -113,7 +113,7 @@ ActivityContext contains the property `IsRemote`, which is not part of W3C. `IsR The object to compare to this instance. Indicates whether the current object is equal to another object of the same type. - if the current object is equal to the parameter; otherwise, . + if the current object is equal to the parameter; otherwise, . To be added. diff --git a/xml/System.Diagnostics/ActivityLink.xml b/xml/System.Diagnostics/ActivityLink.xml index 4358d79ec04..cce746fc2a7 100644 --- a/xml/System.Diagnostics/ActivityLink.xml +++ b/xml/System.Diagnostics/ActivityLink.xml @@ -141,7 +141,7 @@ Activity links can be used to represent batched operations where an activity was The activity link to compare. Indicates whether the current activity link is equal to another activity link. - if the current activity link is equal to ; otherwise, . + if the current activity link is equal to ; otherwise, . to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. @@ -3377,9 +3377,7 @@ SVC_UPDATE.EXE > If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. - - +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. ## Examples The following example writes a warning entry to an event log, "MyNewLog", on the local computer. @@ -3464,6 +3462,7 @@ SVC_UPDATE.EXE , use a different overload of . You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. @@ -3473,11 +3472,9 @@ SVC_UPDATE.EXE If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. > -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. ## Examples The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. @@ -4370,6 +4367,7 @@ SVC_UPDATE.EXE . You must register the source with the corresponding resource file before you write events using resource identifiers. The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. @@ -4383,9 +4381,7 @@ SVC_UPDATE.EXE If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If you write an entry to a remote computer, the value of the `message` string might not be what you expect if the remote computer is not running the .NET Framework. Also, the `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - +> If you write an entry to a remote computer, the value of the `message` string might not be what you expect if the remote computer is not running .NET. Also, the `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. ## Examples The following example writes two audit entries to the event log `myNewLog`. The example creates a new event source and a new event log if they do not exist on the local computer. The event message text is specified using a resource identifier in a resource file. diff --git a/xml/System.Diagnostics/PerformanceCounterCategory.xml b/xml/System.Diagnostics/PerformanceCounterCategory.xml index 0ea286a0757..5fca2af8f23 100644 --- a/xml/System.Diagnostics/PerformanceCounterCategory.xml +++ b/xml/System.Diagnostics/PerformanceCounterCategory.xml @@ -29,44 +29,44 @@ Represents a performance object, which defines a category of performance counters. - [!IMPORTANT] -> Creating or deleting a performance counter requires synchronization of the underlying code by using a named mutex. If a highly privileged application locks the named mutex, attempts to create or delete a performance counter causes the application to stop responding until the lock is released. To help avoid this problem, never grant permission to untrusted code. In addition, permission potentially allows other permissions to be bypassed and should only be granted to highly trusted code. - - The instance's property is displayed in the Performance Object field of the Performance Viewer application's Add Counter dialog box. - - The class provides several methods for interacting with counters and categories on the computer. The methods enable you to define custom categories. The method provides a way to remove categories from the computer. The method enables you to view the list of categories, while retrieves all the counter and instance data associated with a single category. - - A performance counter publishes performance data about an application. Categories include physical components (such as processors, disks, and memory) and system objects (such as processes and threads). System counters that are related to the same performance object are grouped into a category that indicates their common focus. When you create an instance of the class, you first indicate the category with which the component will interact, and then you choose a counter from that category. - - For example, one Windows counter category is the Memory category. System counters within this category track memory data such as the number of bytes available and the number of bytes cached. If you wanted to work with the bytes cached in your application, you would create an instance of the component, connect it to the Memory category, and then pick the appropriate counter (in this case, Cached Bytes) from that category. - - Although your system makes many more counter categories available, the categories that you will probably interact with most frequently are the Cache, Memory, Objects, PhysicalDisk, Process, Processor, Server, System, and Thread categories. - +> Creating or deleting a performance counter requires synchronization of the underlying code by using a named mutex. If a highly privileged application locks the named mutex, attempts to create or delete a performance counter causes the application to stop responding until the lock is released. To help avoid this problem, never grant permission to untrusted code. In addition, permission potentially allows other permissions to be bypassed and should only be granted to highly trusted code. + + The instance's property is displayed in the Performance Object field of the Performance Viewer application's Add Counter dialog box. + + The class provides several methods for interacting with counters and categories on the computer. The methods enable you to define custom categories. The method provides a way to remove categories from the computer. The method enables you to view the list of categories, while retrieves all the counter and instance data associated with a single category. + + A performance counter publishes performance data about an application. Categories include physical components (such as processors, disks, and memory) and system objects (such as processes and threads). System counters that are related to the same performance object are grouped into a category that indicates their common focus. When you create an instance of the class, you first indicate the category with which the component will interact, and then you choose a counter from that category. + + For example, one Windows counter category is the Memory category. System counters within this category track memory data such as the number of bytes available and the number of bytes cached. If you wanted to work with the bytes cached in your application, you would create an instance of the component, connect it to the Memory category, and then pick the appropriate counter (in this case, Cached Bytes) from that category. + + Although your system makes many more counter categories available, the categories that you will probably interact with most frequently are the Cache, Memory, Objects, PhysicalDisk, Process, Processor, Server, System, and Thread categories. + > [!IMPORTANT] -> The method in the class will release the counter and, if the reuse option is selected for that category, the instance of the counter will be reused. This could cause a race condition if another process or even another part of the code is trying to write to the counter instance. - +> The method in the class will release the counter and, if the reuse option is selected for that category, the instance of the counter will be reused. This could cause a race condition if another process or even another part of the code is trying to write to the counter instance. + > [!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. - +> 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] -> 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\\*\*\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. For more information about the file mapping size, see [<performanceCounters>](/dotnet/framework/configure-apps/file-schema/trace-debug/performancecounters-element). - - - -## Examples - The following code example determines whether a and its exist on the local computer or on another computer. If these objects do not exist on the local computer, the example optionally creates them. It uses the method to determine whether the exists. If the does not exist and no counter name is specified, or if the computer is a remote machine, the example exits. - - If a name is provided, the example uses the method and displays the result to the user. If the does not exist, the user can delete and re-create the with the new . If the user does so, the category is deleted using the method. - - If requested, the example now creates the new and using the method. If an instance name is specified, the example uses the method and displays the result. - +> 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\\*\*\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. For more information about the file mapping size, see [<performanceCounters>](/dotnet/framework/configure-apps/file-schema/trace-debug/performancecounters-element). + + + +## Examples + The following code example determines whether a and its exist on the local computer or on another computer. If these objects do not exist on the local computer, the example optionally creates them. It uses the method to determine whether the exists. If the does not exist and no counter name is specified, or if the computer is a remote machine, the example exits. + + If a name is provided, the example uses the method and displays the result to the user. If the does not exist, the user can delete and re-create the with the new . If the user does so, the category is deleted using the method. + + If requested, the example now creates the new and using the method. If an instance name is specified, the example uses the method and displays the result. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/Overview/perfcountercatcreateexist.cs" id="Snippet27"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.Class/VB/perfcountercatcreateexist.vb" id="Snippet27"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.Class/VB/perfcountercatcreateexist.vb" id="Snippet27"::: + ]]> @@ -110,19 +110,19 @@ Initializes a new instance of the class, leaves the property empty, and sets the property to the local computer. - property must be set before associating this instance with a performance object on the server. Otherwise, an exception is thrown. - - - -## Examples - The following code example accepts a name and a computer name from the command line. It creates a using the constructor overload appropriate for the number of parameters provided, then displays its properties. - + property must be set before associating this instance with a performance object on the server. Otherwise, an exception is thrown. + + + +## Examples + The following code example accepts a name and a computer name from the command line. It creates a using the constructor overload appropriate for the number of parameters provided, then displays its properties. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfcountercatctor.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatctor.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatctor.vb" id="Snippet4"::: + ]]> @@ -167,14 +167,14 @@ The name of the performance counter category, or performance object, with which to associate this instance. Initializes a new instance of the class, sets the property to the specified value, and sets the property to the local computer. - name and a computer name from the command line. It creates a using the constructor overload that is appropriate for the number of parameters provided, then displays its properties. - + name and a computer name from the command line. It creates a using the constructor overload that is appropriate for the number of parameters provided, then displays its properties. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfcountercatctor.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatctor.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatctor.vb" id="Snippet4"::: + ]]> The is an empty string (""). @@ -217,20 +217,20 @@ The computer on which the performance counter category and its associated counters exist. Initializes a new instance of the class and sets the and properties to the specified values. - name and a computer name from the command line. It creates a using the constructor overload that is appropriate for the number of parameters provided, then displays its properties. - + name and a computer name from the command line. It creates a using the constructor overload that is appropriate for the number of parameters provided, then displays its properties. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfcountercatctor.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatctor.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatctor.vb" id="Snippet4"::: + ]]> - The is an empty string (""). - - -or- - + The is an empty string (""). + + -or- + The syntax is invalid. The is . @@ -269,14 +269,14 @@ Gets the category's help text. A description of the performance object that this category measures. - with the . It prompts the user for the and computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. - + with the . It prompts the user for the and computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfCounterCatProps.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatprops.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatprops.vb" id="Snippet8"::: + ]]> The property is . The category name must be set before getting the category help. @@ -324,14 +324,14 @@ Gets or sets the name of the performance object that defines this category. The name of the performance counter category, or performance object, with which to associate this instance. - with the . It prompts the user for the and computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. - + with the . It prompts the user for the and computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfCounterCatProps.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatprops.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatprops.vb" id="Snippet8"::: + ]]> The is an empty string (""). @@ -370,13 +370,13 @@ Gets the performance counter category type. One of the values. - property indicates whether the object can have multiple instances. The possible values are , , or . - - There are two types of performance counter categories: single-instance and 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 enumeration is used to indicate whether a performance counter can have multiple instances. - + property indicates whether the object can have multiple instances. The possible values are , , or . + + There are two types of performance counter categories: single-instance and 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 enumeration is used to indicate whether a performance counter can have multiple instances. + ]]> @@ -426,28 +426,26 @@ if the counter is registered to the category that is specified by the and properties; otherwise, . - property before calling this method. Otherwise, an exception is thrown. - - If you have not set the property, this method uses the local computer ("."). - + property before calling this method. Otherwise, an exception is thrown. + + If you have not set the property, this method uses the local computer ("."). + > [!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. - - - -## Examples - The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It creates a object using the appropriate . It then uses the method to determine whether the specified exists, and informs the user. - +> 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. + +## Examples + The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It creates a object using the appropriate . It then uses the method to determine whether the specified exists, and informs the user. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatobjexists.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatobjcountexists.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatobjcountexists.vb" id="Snippet4"::: + ]]> The is . @@ -504,31 +502,29 @@ , if the counter is registered to the specified category on the local computer; otherwise, . - [!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. - - - -## Examples - The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It uses the static overloads of the method to determine whether the specified name exists in the . The overload is selected based on whether a computer name is provided. - +> 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. + +## Examples + The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It uses the static overloads of the method to determine whether the specified name exists in the . The overload is selected based on whether a computer name is provided. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatcounterexists.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatstatcountexists.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatstatcountexists.vb" id="Snippet8"::: + ]]> - The is . - - -or- - + The is . + + -or- + The is . The is an empty string (""). The category name does not exist. @@ -579,36 +575,34 @@ , if the counter is registered to the specified category on the specified computer; otherwise, . - [!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. - - - -## Examples - The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It uses the static overloads of the method to determine whether the specified name exists in the . The overload is selected based on whether a computer name is provided. - +> 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. + +## Examples + The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It uses the static overloads of the method to determine whether the specified name exists in the . The overload is selected based on whether a computer name is provided. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatcounterexists.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatstatcountexists.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatstatcountexists.vb" id="Snippet8"::: + ]]> - The is . - - -or- - + The is . + + -or- + The is . - The is an empty string (""). - - -or- - + The is an empty string (""). + + -or- + The is invalid. The category name does not exist. A call to an underlying system API failed. @@ -684,42 +678,36 @@ Registers the custom performance counter category containing the specified counters on the local computer. A that is associated with the new custom category, or performance object. - [!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. - - - -## Examples - The following code example determines whether a object named "orders" exists. If not, it creates the object by using a object that contains two performance counters. - +> 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. + +## Examples + The following code example determines whether a object named "orders" exists. If not, it creates the object by using a object that contains two performance counters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerfCounter_ccd/CPP/ccd.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/Create/ccd.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerfCounter_ccd/VB/ccd.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerfCounter_ccd/VB/ccd.vb" id="Snippet1"::: + ]]> - A counter name that is specified within the collection is or an empty string (""). - - -or- - - A counter that is specified within the collection already exists. - - -or- - - The parameter has invalid syntax. It might contain backslash characters ("\\") or have length greater than 80 characters. + A counter name that is specified within the collection is or an empty string (""). + + -or- + + A counter that is specified within the collection already exists. The parameter is . - The category already exists on the local computer. - - -or- - + The category already exists on the local computer. + + -or- + The layout of the collection is incorrect for base counters. A counter of type , , , , , , , or has to be immediately followed by one of the base counter types (, , , or ). A call to an underlying system API failed. Code that is executing without administrative privileges attempted to read a performance counter. @@ -769,54 +757,48 @@ Registers the custom performance counter category containing the specified counters on the local computer. A that is associated with the new custom category, or performance object. - 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\\*\*\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. - + 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\\*\*\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. - +> 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. - - - -## Examples - The following code example shows the use of the method. The example shows how to create a custom, multi-instance performance counter category for the number of orders per second. - +> 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. + +## Examples + The following code example shows the use of the method. The example shows how to create a custom, multi-instance performance counter category for the number of orders per second. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/Create/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategoryType/VB/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategoryType/VB/program.vb" id="Snippet2"::: + ]]> - A counter name that is specified within the collection is or an empty string (""). - - -or- - - A counter that is specified within the collection already exists. - - -or- - - has invalid syntax. It might contain backslash characters ("\\") or have length greater than 80 characters. + A counter name that is specified within the collection is or an empty string (""). + + -or- + + A counter that is specified within the collection already exists. - is . - - -or- - + is . + + -or- + is . value is outside of the range of the following values: , , or . - The category already exists on the local computer. - - -or- - + The category already exists on the local computer. + + -or- + The layout of the collection is incorrect for base counters. A counter of type , , , , , , , , or must be immediately followed by one of the base counter types (, , , or ). A call to an underlying system API failed. Code that is executing without administrative privileges attempted to read a performance counter. @@ -881,43 +863,43 @@ Registers a custom performance counter category containing a single counter of type on the local computer. A that is associated with the new system category, or performance object. - [!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. - - - -## Examples - The following code example creates a and single with help text for each, using the method. - +> 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. + + + +## Examples + The following code example creates a and single with help text for each, using the method. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfcountercatcreate.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatcreate.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatcreate.vb" id="Snippet2"::: + ]]> - is or is an empty string (""). - - -or- - - The counter that is specified by already exists. - - -or- - + is or is an empty string (""). + + -or- + + The counter that is specified by already exists. + + -or- + has invalid syntax. It might contain backslash characters ("\\") or have length greater than 80 characters. The category already exists on the local computer. - is . - - -or- - + is . + + -or- + is . A call to an underlying system API failed. Code that is executing without administrative privileges attempted to read a performance counter. @@ -969,49 +951,49 @@ Registers the custom performance counter category containing a single counter of type on the local computer. A that is associated with the new system category, or performance object. - 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\\*\*\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. - + 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\\*\*\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. - +> 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. - - - -## Examples - The following code example shows the use of the method. The example shows how to create a custom, single instance performance counter category. - +> 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. + + + +## Examples + The following code example shows the use of the method. The example shows how to create a custom, single instance performance counter category. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/Create/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategoryType/VB/program.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategoryType/VB/program.vb" id="Snippet3"::: + ]]> - is or is an empty string (""). - - -or- - - The counter that is specified by already exists. - - -or- - + is or is an empty string (""). + + -or- + + The counter that is specified by already exists. + + -or- + has invalid syntax. It might contain backslash characters ("\\") or have length greater than 80 characters. The category already exists on the local computer. - is . - - -or- - + is . + + -or- + is . A call to an underlying system API failed. Code that is executing without administrative privileges attempted to read a performance counter. @@ -1055,26 +1037,26 @@ The name of the custom performance counter category to delete. Removes the category and its associated counters from the local computer. - [!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. - - - -## Examples - The following code example uses the method to delete a and the objects that it contains. - +> 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. + + + +## Examples + The following code example uses the method to delete a and the objects that it contains. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfCounterCatDelete.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatdelete.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatdelete.vb" id="Snippet6"::: + ]]> The parameter is . @@ -1136,27 +1118,27 @@ if the category is registered; otherwise, . - method can result in a noticeable performance penalty while all performance counters on the machine are checked for availability. If you are only writing to a performance counter, you can avoid the global search for performance counters by creating the performance counter when the application is installed and assuming the category exists when accessing the counter. There is no way to avoid the performance counter search when reading from performance counters. - + method can result in a noticeable performance penalty while all performance counters on the machine are checked for availability. If you are only writing to a performance counter, you can avoid the global search for performance counters by creating the performance counter when the application is installed and assuming the category exists when accessing the counter. There is no way to avoid the performance counter search when reading from performance counters. + > [!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. - - - -## Examples - The following code example determines whether a object named "orders" exists. If not, it creates the object by using a object that contains two performance counters. - +> 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. + + + +## Examples + The following code example determines whether a object named "orders" exists. If not, it creates the object by using a object that contains two performance counters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerfCounter_ccd/CPP/ccd.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/Create/ccd.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerfCounter_ccd/VB/ccd.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerfCounter_ccd/VB/ccd.vb" id="Snippet1"::: + ]]> The parameter is . @@ -1205,41 +1187,41 @@ if the category is registered; otherwise, . - method can result in a noticeable performance penalty while all performance counters on the machine are checked for availability. If you are only writing to a performance counter, you can avoid the global search for performance counters by creating the performance counter when the application is installed and assuming the category exists when accessing the counter. There is no way to avoid the performance counter search when reading from performance counters. - + method can result in a noticeable performance penalty while all performance counters on the machine are checked for availability. If you are only writing to a performance counter, you can avoid the global search for performance counters by creating the performance counter when the application is installed and assuming the category exists when accessing the counter. There is no way to avoid the performance counter search when reading from performance counters. + > [!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. - - - -## Examples - The following example determines whether a object named `Orders` exists. If it does not exist, the example creates the object by using a object that contains two performance counters. - +> 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. + + + +## Examples + The following example determines whether a object named `Orders` exists. If it does not exist, the example creates the object by using a object that contains two performance counters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerfCounter_ccd/CPP/ccd.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/Create/ccd.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerfCounter_ccd/VB/ccd.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerfCounter_ccd/VB/ccd.vb" id="Snippet1"::: + ]]> The parameter is . - The parameter is an empty string (""). - - -or- - + The parameter is an empty string (""). + + -or- + The parameter is invalid. A call to an underlying system API failed. The network path cannot be found. - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + Code that is executing without administrative privileges attempted to read a performance counter. @@ -1292,26 +1274,26 @@ Retrieves a list of the performance counter categories that are registered on the local computer. An array of objects indicating the categories that are registered on the local computer. - [!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. - - - -## Examples - The following code example uses the method to return an array of objects from the local computer or a specified computer. It converts the array into an array of category names, which it sorts and displays for the user. The overload is selected based on whether a computer name was specified. - +> 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. + + + +## Examples + The following code example uses the method to return an array of objects from the local computer or a specified computer. It converts the array into an array of category names, which it sorts and displays for the user. The overload is selected based on whether a computer name was specified. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/cpp/perfcountergetcat.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountergetcat.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/VB/perfcountercatgetcat.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/VB/perfcountercatgetcat.vb" id="Snippet2"::: + ]]> A call to an underlying system API failed. @@ -1354,27 +1336,27 @@ Retrieves a list of the performance counter categories that are registered on the specified computer. An array of objects indicating the categories that are registered on the specified computer. - [!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. - - - -## Examples - The following code example uses the method to return an array of objects from the local computer or a specified computer. It converts the array into an array of category names, which it sorts and displays for the user. The overload is selected based on whether a computer name was specified. - +> 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. + + + +## Examples + The following code example uses the method to return an array of objects from the local computer or a specified computer. It converts the array into an array of category names, which it sorts and displays for the user. The overload is selected based on whether a computer name was specified. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/cpp/perfcountergetcat.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountergetcat.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/VB/perfcountercatgetcat.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/VB/perfcountercatgetcat.vb" id="Snippet2"::: + ]]> The parameter is invalid. @@ -1424,29 +1406,29 @@ Retrieves a list of the counters in a performance counter category that contains exactly one instance. An array of objects indicating the counters that are associated with this single-instance performance counter category. - class overview. - + class overview. + > [!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. - - - -## Examples - The following code example gets a list of the objects in a . It first creates a with the appropriate constructor, based on whether a computer name was specified. It then uses the method to return an array of objects, selecting the overload based on whether an instance name was specified. - - This overload fails unless it is used with a single-instance category. - +> 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. + + + +## Examples + The following code example gets a list of the objects in a . It first creates a with the appropriate constructor, based on whether a computer name was specified. It then uses the method to return an array of objects, selecting the overload based on whether an instance name was specified. + + This overload fails unless it is used with a single-instance category. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/cpp/perfcountercatgetcount.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountercatgetcount.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/VB/perfcountercatgetcount.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/VB/perfcountercatgetcount.vb" id="Snippet4"::: + ]]> The category is not a single instance. @@ -1491,38 +1473,38 @@ Retrieves a list of the counters in a performance counter category that contains one or more instances. An array of objects indicating the counters that are associated with the specified object instance of this performance counter category. - class overview. - + class overview. + > [!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. - - - -## Examples - The following code example gets a list of the objects in a . It first creates a with the appropriate constructor, based on whether a computer name was specified. It then uses the method to return an array of objects, selecting the overload based on whether an instance name was specified. - - This overload fails unless it is used with a category that contains instances. - +> 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. + + + +## Examples + The following code example gets a list of the objects in a . It first creates a with the appropriate constructor, based on whether a computer name was specified. It then uses the method to return an array of objects, selecting the overload based on whether an instance name was specified. + + This overload fails unless it is used with a category that contains instances. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/cpp/perfcountercatgetcount.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountercatgetcount.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/VB/perfcountercatgetcount.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/VB/perfcountercatgetcount.vb" id="Snippet4"::: + ]]> The parameter is . - The property for this instance has not been set. - - -or- - + The property for this instance has not been set. + + -or- + The category does not contain the instance that is specified by the parameter. A call to an underlying system API failed. Code that is executing without administrative privileges attempted to read a performance counter. @@ -1561,32 +1543,32 @@ Retrieves the list of performance object instances that are associated with this category. An array of strings representing the performance object instance names that are associated with this category or, if the category contains only one performance object instance, a single-entry array that contains an empty string (""). - [!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. - - - -## Examples - The following code example gets a list of the objects in a . It first creates a object, using the appropriate constructor based on whether a computer name was specified. It then uses to return the instance names as an array of , which it sorts and displays. - +> 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. + + + +## Examples + The following code example gets a list of the objects in a . It first creates a object, using the appropriate constructor based on whether a computer name was specified. It then uses to return the instance names as an array of , which it sorts and displays. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/cpp/perfcountercatgetinst.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountercatgetinst.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/VB/perfcountercatgetinst.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.GetMembers/VB/perfcountercatgetinst.vb" id="Snippet6"::: + ]]> - The property is . The property might not have been set. - - -or- - + The property is . The property might not have been set. + + -or- + The category does not have an associated instance. A call to an underlying system API failed. Code that is executing without administrative privileges attempted to read a performance counter. @@ -1640,26 +1622,26 @@ if the category contains the specified performance object instance; otherwise, . - is not `static`. It requires you to create a object and to set the property. - + is not `static`. It requires you to create a object and to set the property. + > [!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. - - - -## Examples - The following code example determines whether a instance exists within a . It first creates a object, using the appropriate constructor based on whether a computer name was specified. It then uses to determine whether the specified instance exists, then informs the user. If no instance name is specified, the example uses the default single-instance name. - +> 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. + + + +## Examples + The following code example determines whether a instance exists within a . It first creates a object, using the appropriate constructor based on whether a computer name was specified. It then uses to determine whether the specified instance exists, then informs the user. If no instance name is specified, the example uses the default single-instance name. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcounterobjinstexists.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatobjinstexists.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatobjinstexists.vb" id="Snippet2"::: + ]]> The property is . The property might not have been set. @@ -1717,32 +1699,32 @@ if the category contains the specified performance object instance; otherwise, . - [!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. - - - -## Examples - The following code example uses the static overloads of to determine whether the given instance exists in the . The overload is selected based on whether a computer name is specified. If no instance name is specified, the example uses the default single-instance name. - +> 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. + + + +## Examples + The following code example uses the static overloads of to determine whether the given instance exists in the . The overload is selected based on whether a computer name is specified. If no instance name is specified, the example uses the default single-instance name. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatinstexists.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatstatinstexists.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatstatinstexists.vb" id="Snippet10"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . The parameter is an empty string (""). A call to an underlying system API failed. @@ -1793,39 +1775,39 @@ if the category contains the specified performance object instance; otherwise, . - [!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. - - - -## Examples - The following code example uses the static overloads of to determine whether the given instance exists in the . The overload is selected based on whether a computer name is specified. If no instance name is specified, the example uses the default single-instance name. - +> 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. + + + +## Examples + The following code example uses the static overloads of to determine whether the given instance exists in the . The overload is selected based on whether a computer name is specified. If no instance name is specified, the example uses the default single-instance name. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatinstexists.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatstatinstexists.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.ExistMembers/VB/perfcountercatstatinstexists.vb" id="Snippet10"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . - The parameter is an empty string (""). - - -or- - + The parameter is an empty string (""). + + -or- + The parameter is invalid. A call to an underlying system API failed. Code that is executing without administrative privileges attempted to read a performance counter. @@ -1872,14 +1854,14 @@ Gets or sets the name of the computer on which this category exists. The name of the computer on which the performance counter category and its associated counters exist. - with the constructor. It prompts the user for the and the computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. - + with the constructor. It prompts the user for the and the computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfCounterCatProps.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatprops.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.PerformanceCounterCategory.OtherMembers/VB/perfcountercatprops.vb" id="Snippet8"::: + ]]> The syntax is invalid. @@ -1919,28 +1901,28 @@ Reads all the counter and performance object instance data that is associated with this performance counter category. An that contains the counter and performance object instance data for the category. - property before you call . - - Reading the entire category at once can be as efficient as reading a single counter because of the way that the system provides the data. - + property before you call . + + Reading the entire category at once can be as efficient as reading a single counter because of the way that the system provides the data. + > [!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. - - - -## Examples - The following code example creates a for a specified name. It then uses to return an that contains instance data for all the instances of the objects within the . - +> 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. + + + +## Examples + The following code example creates a for a specified name. It then uses to return an that contains instance data for all the instances of the objects within the . + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.InstanceData.CopyTo/VB/instdatacopyto.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.InstanceData.CopyTo/VB/instdatacopyto.vb" id="Snippet6"::: + ]]> The property is . The property might not have been set. diff --git a/xml/System.Diagnostics/ProcessStartInfo.xml b/xml/System.Diagnostics/ProcessStartInfo.xml index e0214dc86fe..8fa0a9994b4 100644 --- a/xml/System.Diagnostics/ProcessStartInfo.xml +++ b/xml/System.Diagnostics/ProcessStartInfo.xml @@ -1734,8 +1734,8 @@ You can use asynchronous read operations to avoid these dependencies and their d System.String - Gets or sets the user name to use when starting the process. If you use the UPN format, @, the property must be . - The user name to use when starting the process. If you use the UPN format, @, the property must be . + Gets or sets the user name to use when starting the process. If you use the UPN format, user@DNS_domain_name, the property must be . + The user name to use when starting the process. is . - is less than 0 or greater than or equal to the length. + is less than 0 or greater than or equal to the length. diff --git a/xml/System.Diagnostics/TraceListenerCollection.xml b/xml/System.Diagnostics/TraceListenerCollection.xml index 2dcba1301ee..00eb858f2af 100644 --- a/xml/System.Diagnostics/TraceListenerCollection.xml +++ b/xml/System.Diagnostics/TraceListenerCollection.xml @@ -60,26 +60,26 @@ Provides a thread-safe list of objects. - list is used to specify the output listeners for the and the collections. You cannot create an instance of this class. - - This list is thread-safe, however the methods used to access the list and the enumerator do not take synchronization locks. Instead, the collection is copied, the copy is modified, and a reference is set to the copy of the collection. Methods like , , and modify the elements in the collection. - - The class provides the property for information about the list. It also provides the following methods: , , . - - This class also provides the following methods to modify the list: , , , and . The method copies a part of the list to an array. The method deletes the list member at a specified index number. - - - -## Examples - The following example creates a that writes to the console screen. The code then adds the new listener to the . - + list is used to specify the output listeners for the and the collections. You cannot create an instance of this class. + + This list is thread-safe, however the methods used to access the list and the enumerator do not take synchronization locks. Instead, the collection is copied, the copy is modified, and a reference is set to the copy of the collection. Methods like , , and modify the elements in the collection. + + The class provides the property for information about the list. It also provides the following methods: , , . + + This class also provides the following methods to modify the list: , , , and . The method copies a part of the list to an array. The method deletes the list member at a specified index number. + + + +## Examples + The following example creates a that writes to the console screen. The code then adds the new listener to the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Listeners Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Listeners/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Listeners Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Listeners Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -133,15 +133,15 @@ Adds a to the list. The position at which the new listener was inserted. - that outputs to the console screen. The code then adds the new listener to the . - + that outputs to the console screen. The code then adds the new listener to the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceListenerCollection.Add Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceListenerCollection/Add/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic TraceListenerCollection.Add Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic TraceListenerCollection.Add Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -365,11 +365,11 @@ if the listener is in the list; otherwise, . - method can confirm the existence of a before you perform further operations. - + method can confirm the existence of a before you perform further operations. + ]]> @@ -634,13 +634,13 @@ A to insert in the list. Inserts the listener at the specified index. - The is not a valid index in the list. @@ -708,11 +708,11 @@ Gets or sets the at the specified index. A with the specified index. - to access that . For example, to get the third , you need to specify `myTraceListenerColl[2]`. - + to access that . For example, to get the third , you need to specify `myTraceListenerColl[2]`. + ]]> The value is . @@ -775,11 +775,11 @@ Gets the first in the list with the specified name. The first in the list with the given . This item returns if no with the given name can be found. - property is case-sensitive when searching for names. That is, if two listeners exist with the names "Lname" and "lname", property will find only the with the that you specify, not both. - + property is case-sensitive when searching for names. That is, if two listeners exist with the names "Lname" and "lname", property will find only the with the that you specify, not both. + ]]> @@ -895,11 +895,11 @@ The name of the to remove from the list. Removes from the collection the first with the specified name. - method will find the specific listener you name. - + method will find the specific listener you name. + ]]> @@ -956,11 +956,11 @@ The zero-based index of the to remove from the list. Removes from the collection the at the specified index. - to delete that . For example, to remove the third , you need to specify `myTraceListenerColl.RemoveAt(2)`. - + to delete that . For example, to remove the third , you need to specify `myTraceListenerColl.RemoveAt(2)`. + ]]> The is not a valid index in the list. @@ -1020,11 +1020,11 @@ The zero-based index in at which copying begins. Copies a section of the current to the specified array of objects. - method of the class to copy all or part of the collection to an array. - + method of the class to copy all or part of the collection to an array. + ]]> @@ -1177,18 +1177,18 @@ This member is an explicit interface member implementation. It can be used only Adds a trace listener to the . The position into which the new trace listener was inserted. - method to add a new trace listener to the collection. - + method to add a new trace listener to the collection. + ]]> - is . - - -or- - + is . + + -or- + is not a . @@ -1239,11 +1239,11 @@ This member is an explicit interface member implementation. It can be used only if the is found in the ; otherwise, . - method of the class to determine whether the collection contains a specific object. - + method of the class to determine whether the collection contains a specific object. + ]]> @@ -1294,11 +1294,11 @@ This member is an explicit interface member implementation. It can be used only Determines the index of a specific object in the . The index of if found in the ; otherwise, -1. - method of the class to determine the index of a object in the collection. - + method of the class to determine the index of a object in the collection. + ]]> @@ -1350,11 +1350,11 @@ This member is an explicit interface member implementation. It can be used only The object to insert into the . Inserts a object at the specified position in the . - method of the class to insert a object into the collection. - + method of the class to insert a object into the collection. + ]]> @@ -1511,15 +1511,15 @@ This member is an explicit interface member implementation. It can be used only - The zero-based index of the to get. + The zero-based index of the value to get. Gets or sets the at the specified index in the . The at the specified index. - property or the indexer of the class to get or set a in the collection. - + property or the indexer of the class to get or set a in the collection. + ]]> @@ -1569,11 +1569,11 @@ This member is an explicit interface member implementation. It can be used only The object to remove from the . Removes an object from the . - method of the class to remove a from the collection. - + method of the class to remove a from the collection. + ]]> diff --git a/xml/System.Diagnostics/XmlWriterTraceListener.xml b/xml/System.Diagnostics/XmlWriterTraceListener.xml index 32477071c6e..ce6c758e6e7 100644 --- a/xml/System.Diagnostics/XmlWriterTraceListener.xml +++ b/xml/System.Diagnostics/XmlWriterTraceListener.xml @@ -33,81 +33,81 @@ Directs tracing or debugging output as XML-encoded data to a or to a , such as a . - [!NOTE] -> You must have unmanaged code permission to create an instance of the class. - - The class converts tracing and debugging information into an XML-encoded text stream. The description of the XML output is shown in the tables that follow. You can use the [Service Trace Viewer Tool (SvcTraceViewer.exe)](https://go.microsoft.com/fwlink/p/?LinkId=240129) to display the XML output. - -You can create an in your code. Alternatively, for .NET Framework apps, you can enable or disable an through the application configuration file and then use the configured in your application. To configure an , edit the configuration file that corresponds to the name of your application. In this file, you can add or remove a listener, set the properties for a listener, or remove listeners. The configuration file should be formatted like the following example. - -```xml - - - - - - - - - - -``` - - The class inherits the property from the base class . The property allows an additional level of trace output filtering at the listener. If there is a filter present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. - +> You must have unmanaged code permission to create an instance of the class. + + The class converts tracing and debugging information into an XML-encoded text stream. The description of the XML output is shown in the tables that follow. You can use the [Service Trace Viewer Tool (SvcTraceViewer.exe)](https://go.microsoft.com/fwlink/p/?LinkId=240129) to display the XML output. + +You can create an in your code. Alternatively, for .NET Framework apps, you can enable or disable an through the application configuration file and then use the configured in your application. To configure an , edit the configuration file that corresponds to the name of your application. In this file, you can add or remove a listener, set the properties for a listener, or remove listeners. The configuration file should be formatted like the following example. + +```xml + + + + + + + + + + +``` + + The class inherits the property from the base class . The property allows an additional level of trace output filtering at the listener. If there is a filter present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. + > [!NOTE] -> If an attempt is made to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. - +> If an attempt is made to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. + > [!NOTE] -> Listener methods are intended to be called by methods of the , , and classes. The listener methods are not intended to be called directly from application code. The listener is primarily intended for use by the class. The and methods can be called by the and classes, and default values are provided for the XML elements that and do not supply values for. - - The following table describes the elements and attributes of the XML output. - -|Element|Attributes|Output|Notes| -|-------------|----------------|------------|-----------| -|`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table that follows.| -|`Computer`|None|Always present.|The value of the property.| -|`Correlation`|`ActivityID`|Always present|If not specified, the default is an empty GUID.| -||`RelatedActivityID`|Depends on the presence of the `relatedActivityId` parameter in the Trace method call.|The `relatedActivityId` parameter of the method.| -|`DataItem`|None|Depends on the `data` parameter of the method.|This element can contain an array of elements or one element, so the values are written as a set of `DataItem` nodes under the `TraceData` element.

The data output uses the `ToString` method of the passed-in data objects.| -|`EventID`|None|Always present.|Parameter input (`id`).| -|`Execution`|`ProcessName`|Always present.|From the .| -||`ProcessID`|Always present.|From the .| -||`ThreadID`|Always present.|From the .| -|`Level`|None|Always present.|Parameter input (the numeric value of `eventType`). Parameter values greater than 255 are output as 255.| -|`LogicalOperationStack`|None|Depends on the presence of the flag in the property.|There can be more than one logical operation, so the values are written as `LogicalOperation` nodes under the `LogicalOperationStack` element.| -|`Message`|None|Depends on the presence of a message in the Trace method call.|This element is a formatted message if formatting arguments are provided.| -|`Source`|`Name`|Always present.|Parameter input.| -|`SubType`|`Name`|Always present.|Parameter input.| -|`TimeCreated`|`SystemTime`|Always present.|If not present in the , the default is the current time.| -|`TimeStamp`|None|Depends on the presence of the flag in the property.|From the .| -|`Type`|None|Always present.|Always the value 3.| - - The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes with the exception of the `DataItem` element, which is not escaped if the object passed to the `data` parameter of the method is an object. If an is used for the data object, the method is called and the entire root node is traced as unescaped data. - -|Escaped character|Value| -|-----------------------|-----------| -|&|&| -|\<|<| -|>|>| -|"|"| -|\|'| -|0xD|&\#xD;| +> Listener methods are intended to be called by methods of the , , and classes. The listener methods are not intended to be called directly from application code. The listener is primarily intended for use by the class. The and methods can be called by the and classes, and default values are provided for the XML elements that and do not supply values for. + + The following table describes the elements and attributes of the XML output. + +|Element|Attributes|Output|Notes| +|-------------|----------------|------------|-----------| +|`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table that follows.| +|`Computer`|None|Always present.|The value of the property.| +|`Correlation`|`ActivityID`|Always present|If not specified, the default is an empty GUID.| +||`RelatedActivityID`|Depends on the presence of the `relatedActivityId` parameter in the Trace method call.|The `relatedActivityId` parameter of the method.| +|`DataItem`|None|Depends on the `data` parameter of the method.|This element can contain an array of elements or one element, so the values are written as a set of `DataItem` nodes under the `TraceData` element.

The data output uses the `ToString` method of the passed-in data objects.| +|`EventID`|None|Always present.|Parameter input (`id`).| +|`Execution`|`ProcessName`|Always present.|From the .| +||`ProcessID`|Always present.|From the .| +||`ThreadID`|Always present.|From the .| +|`Level`|None|Always present.|Parameter input (the numeric value of `eventType`). Parameter values greater than 255 are output as 255.| +|`LogicalOperationStack`|None|Depends on the presence of the flag in the property.|There can be more than one logical operation, so the values are written as `LogicalOperation` nodes under the `LogicalOperationStack` element.| +|`Message`|None|Depends on the presence of a message in the Trace method call.|This element is a formatted message if formatting arguments are provided.| +|`Source`|`Name`|Always present.|Parameter input.| +|`SubType`|`Name`|Always present.|Parameter input.| +|`TimeCreated`|`SystemTime`|Always present.|If not present in the , the default is the current time.| +|`TimeStamp`|None|Depends on the presence of the flag in the property.|From the .| +|`Type`|None|Always present.|Always the value 3.| + + The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes with the exception of the `DataItem` element, which is not escaped if the object passed to the `data` parameter of the method is an object. If an is used for the data object, the method is called and the entire root node is traced as unescaped data. + +|Escaped character|Value| +|-----------------------|-----------| +|&|&| +|\<|<| +|>|>| +|"|"| +|\|'| +|0xD|&\#xD;| |0xA|&\#xA;| - -## Examples - The following code example shows the use of the class to write both escaped and non-escaped data to file logs. - + +## Examples + The following code example shows the use of the class to write both escaped and non-escaped data to file logs. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/XmlWriterTraceListener/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.XmlWriterTraceListener/VB/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.XmlWriterTraceListener/VB/module1.vb" id="Snippet1"::: + ]]> @@ -151,11 +151,11 @@ You can create an in your code. A that represents the stream the trace listener writes to. Initializes a new instance of the class, using the specified stream as the recipient of the debugging and tracing output. - property is initialized to an empty string (""). - + property is initialized to an empty string (""). + ]]> @@ -192,11 +192,11 @@ You can create an in your code. A that receives the output from the trace listener. Initializes a new instance of the class using the specified writer as the recipient of the debugging and tracing output. - property is initialized to an empty string (""). - + property is initialized to an empty string (""). + ]]> @@ -234,16 +234,16 @@ You can create an in your code. The name of the file to write to. Initializes a new instance of the class, using the specified file as the recipient of the debugging and tracing output. - class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. - + class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. + > [!NOTE] -> To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. - - The property is initialized to an empty string (""). - +> To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. + + The property is initialized to an empty string (""). + ]]> @@ -290,16 +290,16 @@ You can create an in your code. The name of the new instance. Initializes a new instance of the class with the specified name, using the specified stream as the recipient of the debugging and tracing output. - property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". - -``` -((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = - TraceOptions.Timestamp -``` - + property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + +``` +((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = + TraceOptions.Timestamp +``` + ]]> @@ -346,16 +346,16 @@ You can create an in your code. The name of the new instance. Initializes a new instance of the class with the specified name, using the specified writer as the recipient of the debugging and tracing output. - property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". - -``` -((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = - TraceOptions.Timestamp. -``` - + property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + +``` +((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = + TraceOptions.Timestamp. +``` + ]]> @@ -395,25 +395,23 @@ You can create an in your code. The name of the new instance. Initializes a new instance of the class with the specified name, using the specified file as the recipient of the debugging and tracing output. - class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. - + class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. + > [!NOTE] -> To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. - - The property is set to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". - -``` -((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = - TraceOptions.Timestamp. -``` - +> To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. + + The property is set to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + +``` +((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = + TraceOptions.Timestamp. +``` + ]]> - - is . @@ -484,11 +482,11 @@ You can create an in your code. The detailed error message to append to the error message. Writes trace information including an error message and a detailed error message to the file or stream. - instances in the collection. By default, the collection contains an instance of . You can customize this behavior by adding or removing a from the collection. - + instances in the collection. By default, the collection contains an instance of . You can customize this behavior by adding or removing a from the collection. + ]]> @@ -551,14 +549,14 @@ You can create an in your code. A data object to emit. Writes trace information, a data object, and event information to the file or stream. - [!IMPORTANT] -> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. - +> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -619,14 +617,14 @@ You can create an in your code. An array of data objects to emit. Writes trace information, data objects, and event information to the file or stream. - [!IMPORTANT] -> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. - +> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -689,14 +687,14 @@ You can create an in your code. The message to write. Writes trace information, a message, and event information to the file or stream. - [!IMPORTANT] -> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. - +> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -767,14 +765,14 @@ You can create an in your code. An object array containing zero or more objects to format. Writes trace information, a formatted message, and event information to the file or stream. - method is called, passing in the `format` string and `args` array as parameters, to format the `args` object array as the `Message` element. - + method is called, passing in the `format` string and `args` array as parameters, to format the `args` object array as the `Message` element. + > [!IMPORTANT] -> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. - +> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -828,14 +826,14 @@ You can create an in your code. A structure that identifies a related activity. Writes trace information including the identity of a related activity, a message, and event information to the file or stream. - method is used for the correlation of related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before writing, so a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Message` element. The method is called to convert the `relatedActivityId`value to a "B" formatted string, which appears in the header. The `SubTypeName` element in the footer identifies the trace event type as a . - + method is used for the correlation of related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before writing, so a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Message` element. The method is called to convert the `relatedActivityId`value to a "B" formatted string, which appears in the header. The `SubTypeName` element in the footer identifies the trace event type as a . + > [!IMPORTANT] -> The method is not intended to be called by application code. It is intended to be called by a object to emit the trace information for its method. - +> The method is not intended to be called by application code. It is intended to be called by a object to emit the trace information for its method. + ]]> @@ -874,11 +872,11 @@ You can create an in your code. The message to write. Writes a verbatim message without any additional context information to the file or stream. - method to include context information in the log output. - + method to include context information in the log output. + ]]> @@ -917,11 +915,11 @@ You can create an in your code. The message to write. Writes a verbatim message without any additional context information followed by the current line terminator to the file or stream. - method to include context information in the log output. - + method to include context information in the log output. + ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalContext.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalContext.xml index 079cb4a68f1..dd8bdd315db 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalContext.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalContext.xml @@ -30,11 +30,11 @@ Encapsulates the server or domain against which all operations are performed, the container that is used as the base of those operations, and the credentials used to perform the operations. - @@ -47,15 +47,15 @@ Initializes a new instance of the class. - constructors perform validation of the parameters and server, but not do not attempt to validate credentials. - - When the principal context object is created without specifying a container, it may be used to represent multiple distinct containers. One container may be used as the base of query operations, while additional containers can hold newly-created principal objects. For example, when users or groups are inserted into the domain context type, the Account Management API uses the default well-known user container, "CN=Users,DC=Fabrikam,DC=com". When computers are inserted in the store, the API uses the default "CN=Computers,DC=Fabrikam,DC=com" container. Note that the default container names can be changed by the domain administrator. Since the principal object constructors can only specify one principal context, additional contexts are exposed as the default behavior when the application creates a domain context without specifying a container. Since the application directory does not have well-known containers, the application must specify a container in the constructor or the is thrown. Since SAM does not have containers, a is thrown if the application attempts to specify a container in the constructor. - - In each version of the constructor that takes a user name as a parameter, the `userName` string can be in various different formats. The three supported NameFormats for are Nt4Name, UserPrincipalName, and SamAccountName. For more information about name formats, see the [ADS_NAME_TYPE_ENUM documentation](/windows/win32/api/iads/ne-iads-ads_name_type_enum). - + constructors perform validation of the parameters and server, but not do not attempt to validate credentials. + + When the principal context object is created without specifying a container, it may be used to represent multiple distinct containers. One container may be used as the base of query operations, while additional containers can hold newly-created principal objects. For example, when users or groups are inserted into the domain context type, the Account Management API uses the default well-known user container, "CN=Users,DC=Fabrikam,DC=com". When computers are inserted in the store, the API uses the default "CN=Computers,DC=Fabrikam,DC=com" container. Note that the default container names can be changed by the domain administrator. Since the principal object constructors can only specify one principal context, additional contexts are exposed as the default behavior when the application creates a domain context without specifying a container. Since the application directory does not have well-known containers, the application must specify a container in the constructor or the is thrown. Since SAM does not have containers, a is thrown if the application attempts to specify a container in the constructor. + + In each version of the constructor that takes a user name as a parameter, the `userName` string can be in various different formats. The three supported NameFormats for are Nt4Name, UserPrincipalName, and SamAccountName. For more information about name formats, see the [ADS_NAME_TYPE_ENUM documentation](/windows/win32/api/iads/ne-iads-ads_name_type_enum). + ]]> @@ -105,8 +105,8 @@ A enumeration value specifying the type of store for the principal context. - The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. - + The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. + If the name is for a context type this context is a domain controller for the domain of the user principal under which the thread is running. If the name is for a context type, this is the local machine name. This parameter cannot be for context types. Initializes a new instance of the class with the specified context type and name. To be added. @@ -135,25 +135,25 @@ A enumeration value specifying the type of store for the principal context. - The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. - + The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. + If the name is for a context type this context is a domain controller for the domain of the user principal under which the thread is running. If the name is for a context type, this is the local machine name. This parameter cannot be for context types. - The container on the store to use as the root of the context. All queries are performed under this root, and all inserts are performed into this container. - - For and context types, this parameter is the distinguished name of a container object. - + The container on the store to use as the root of the context. All queries are performed under this root, and all inserts are performed into this container. + + For and context types, this parameter is the distinguished name of a container object. + For context types, this parameter must be set to . Initializes a new instance of the class with the specified context type, name, and container. - may be thrown in subsequent directory operations calls that connect to the server if the container specified for a principal context is not a valid container. A container is defined as an object whose schema class has the principal classes, either user, group, or computer, in its possibleInferiors attribute. - + may be thrown in subsequent directory operations calls that connect to the server if the container specified for a principal context is not a valid container. A container is defined as an object whose schema class has the principal classes, either user, group, or computer, in its possibleInferiors attribute. + ]]> - A container cannot be specified when the context type is specified in the parameter. - + A container cannot be specified when the context type is specified in the parameter. + A name or container must be specified when is specified in the parameter. The parameter does not contain a valid enumeration value. @@ -186,29 +186,29 @@ A enumeration value specifying the type of store for the principal context. - The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. - + The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. + If the name is for a context type this context is a domain controller for the domain of the user principal under which the thread is running. If the name is for a context type, this is the local machine name. This parameter cannot be for context types. - The container on the store to use as the root of the context. All queries are performed under this root, and all inserts are performed into this container. - - For and context types, this parameter is the distinguished name of a container object. - + The container on the store to use as the root of the context. All queries are performed under this root, and all inserts are performed into this container. + + For and context types, this parameter is the distinguished name of a container object. + For context types, this parameter must be set to . A combination of one or more enumeration values specifying the options used to bind to the server. If this parameter is , the default options are ContextOptions.Negotiate | ContextOptions.Signing | ContextOptions.Sealing. Initializes a new instance of the class with the specified context type, name, container, and context options. - may be thrown in subsequent directory operations calls that connect to the server if the container specified for a principal context is not a valid container. A container is defined as an object whose schema class has the principal classes, either user, group, or computer, in its possibleInferiors attribute. - + may be thrown in subsequent directory operations calls that connect to the server if the container specified for a principal context is not a valid container. A container is defined as an object whose schema class has the principal classes, either user, group, or computer, in its possibleInferiors attribute. + ]]> - A container cannot be specified when the context type is specified in the parameter. - + A container cannot be specified when the context type is specified in the parameter. + A name or container must be specified when is specified in the parameter. - The parameter does not contain a valid enumeration value. - + The parameter does not contain a valid enumeration value. + The parameter does not contain a combination of valid enumeration values. @@ -234,15 +234,15 @@ A enumeration value specifying the type of store for the principal context. - The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. - + The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. + If the name is for a context type this context is a domain controller for the domain of the user principal under which the thread is running. If the name is for a context type, this is the local machine name. This parameter cannot be for context types. The username used to connect to the store. If the and parameters are both , the credentials of the current process are used. Otherwise, both and must be non-null, and the credentials they specify are used to connect to the store. The password used to connect to the store. If the and parameters are both , the credentials of the current process are used. Otherwise, both and must be non-null, and the credentials they specify are used to connect to the store. Initializes a new instance of the class with the specified context type, name, username, and password. To be added. - The and parameters must either be or contain a value. - + The and parameters must either be or contain a value. + A name must be specified when is specified in the parameter. The parameter does not contain a valid enumeration value. @@ -270,29 +270,29 @@ A enumeration value specifying the type of store for the principal context. - The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. - + The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. + If the name is for a context type this context is a domain controller for the domain of the user principal under which the thread is running. If the name is for a context type, this is the local machine name. This parameter cannot be for context types. - The container on the store to use as the root of the context. All queries are performed under this root, and all inserts are performed into this container. - - For and context types, this parameter is the distinguished name of a container object. - + The container on the store to use as the root of the context. All queries are performed under this root, and all inserts are performed into this container. + + For and context types, this parameter is the distinguished name of a container object. + For context types, this parameter must be set to . The username used to connect to the store. If the and parameters are both , the default credentials of the current principal are used. Otherwise, both and must be non-null, and the credentials they specify are used to connect to the store. The password used to connect to the store. If the and parameters are both , the default credentials of the current principal are used. Otherwise, both and must be non-null, and the credentials they specify are used to connect to the store. Initializes a new instance of the class with the specified context type, name, container, username, and password. - may be thrown in subsequent directory operations calls that connect to the server if the container specified for a principal context is not a valid container. A container is defined as an object whose schema class has the principal classes, either user, group, or computer, in its possibleInferiors attribute. - + may be thrown in subsequent directory operations calls that connect to the server if the container specified for a principal context is not a valid container. A container is defined as an object whose schema class has the principal classes, either user, group, or computer, in its possibleInferiors attribute. + ]]> - The and parameters must either be or contain a value. - - A container cannot be specified when the context type is specified in the parameter. - + The and parameters must either be or contain a value. + + A container cannot be specified when the context type is specified in the parameter. + A or must be specified when is specified in the parameter. The parameter does not contain a valid enumeration value. @@ -321,33 +321,33 @@ A enumeration value specifying the type of store for the principal context. - The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. - + The name of the domain or server for context types, the machine name for context types, or the name of the server and port hosting the instance. + If the name is for a context type this context is a domain controller for the domain of the user principal under which the thread is running. If the name is for a context type, this is the local machine name. This parameter cannot be for context types. - The container on the store to use as the root of the context. All queries are performed under this root, and all inserts are performed into this container. - - For and context types, this parameter is the distinguished name of a container object. - + The container on the store to use as the root of the context. All queries are performed under this root, and all inserts are performed into this container. + + For and context types, this parameter is the distinguished name of a container object. + For context types, this parameter must be set to . A combination of one or more enumeration values the options used to bind to the server. If this parameter is , the default options are ContextOptions.Negotiate | ContextOptions.Signing | ContextOptions.Sealing. The username used to connect to the store. If the and parameters are both , the default credentials of the current principal are used. Otherwise, both and must be non-null, and the credentials they specify are used to connect to the store. The password used to connect to the store. If the and parameters are both , the default credentials of the current principal are used. Otherwise, both and must be non-null, and the credentials they specify are used to connect to the store. Initializes a new instance of the class with the specified context type, name, container, context options, username, and password. - may be thrown in subsequent directory operations calls that connect to the server if the container specified for a principal context is not a valid container. A container is defined as an object whose schema class has the principal classes, either user, group, or computer, in its possibleInferiors attribute. - + may be thrown in subsequent directory operations calls that connect to the server if the container specified for a principal context is not a valid container. A container is defined as an object whose schema class has the principal classes, either user, group, or computer, in its possibleInferiors attribute. + ]]> - The and parameters must either be or contain a value. - - A container cannot be specified when the context type is specified in the parameter. - + The and parameters must either be or contain a value. + + A container cannot be specified when the context type is specified in the parameter. + A name or container must be specified when is specified in the parameter. - The parameter does not contain a valid enumeration value. - + The parameter does not contain a valid enumeration value. + The parameter does not contain a combination of valid enumeration values. @@ -372,11 +372,11 @@ Gets the name of the server to which the principal context is connected. The name of the server to which the principal context is connected or if the principal context is not connected to a server. - , this property returns the name of the domain controller or application directory instance. When the context type is , this property returns the machine name. - + , this property returns the name of the domain controller or application directory instance. When the context type is , this property returns the machine name. + ]]> @@ -402,11 +402,11 @@ Gets the value specified in the container parameter in the constructor. The container on the store to use as the root of the context or if the container is not specified. - and context types, this property is the distinguished name of a container object. For context types, this property must be `null`. - + and context types, this property is the distinguished name of a container object. For context types, this property must be `null`. + ]]> @@ -432,11 +432,11 @@ Gets the context type that specifies the type of store for the principal context. A enumeration value specifying the type of target to connect to. - @@ -534,11 +534,11 @@ Gets the value specified in the username parameter in the constructor. The username used to connect to the store, or if no user name exists. - @@ -551,11 +551,11 @@ Creates the connection to the server and validates the specified credentials if the connection is successful. - @@ -588,10 +588,10 @@ The `userName` argument in both overloads of this method must take the form *use if the credentials are valid; otherwise . - method binds to the server specified in the constructor. If the `username` and `password` arguments are `null`, this method validates the default credentials for the current principal. + method binds to the server specified in the constructor. If the `username` and `password` arguments are `null`, this method validates the default credentials for the current principal. The `userName` argument must take the form *userName* (for example, *mcampbell*) rather than *domain\username* or *username\@domain*. @@ -629,13 +629,13 @@ The `userName` argument must take the form *userName* (for example, *mcampbell*) if the credentials are valid; otherwise . - method binds to the server specified in the constructor. If the `username` and `password` parameters are `null`, this method validates the default credentials for the current principal. + method binds to the server specified in the constructor. If the `username` and `password` parameters are `null`, this method validates the default credentials for the current principal. + +The `userName` argument must take the form *username* (for example, *mcampbell*) rather than *domain\username* or *username\@domain*. -The `userName` argument must take the form *username* (for example, *mcampbell*) rather than *domain\username* or *username\@domain*. - ]]> The parameter must specify when the context type is . diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchedule.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchedule.xml index e151883479b..d09394b69fd 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchedule.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchedule.xml @@ -102,86 +102,86 @@ Gets or sets a three-dimensional array that indicates at what time during the week that the source is available for replication. - A three-dimensional array of elements in which the element is if the source is available for replication during that specific 15-minute interval. The element is if the source is not available for replication. - - The array is in the form RawSchedule[<day-of-week>, <hour>, <15-minute interval>]. All of these values are zero-based and the week begins at 00:00 on Sunday morning, Coordinated Universal Time. - - The following are the valid values for the day-of-week. - - Day-of-week value - - Indicated day of the week. - - 0 - - Sunday - - 1 - - Monday - - 2 - - Tuesday - - 3 - - Wednesday - - 4 - - Thursday - - 5 - - Friday - - 6 - - Saturday - - - - The hour is zero-based and specified in 24-hour format. For example, 2 P.M. would be specified as 14. Valid values are 0-23. - - The 15-minute interval specifies the 15-minute block within the hour that the source is available for replication. The following table identifies the possible values for the 15-minute interval. - - 15-minute interval - - Description - - 0 - - The source is available for replication from 0 to 14 minutes after the hour. - - 1 - - The source is available for replication from 15 to 29 minutes after the hour. - - 2 - - The source is available for replication from 30 to 44 minutes after the hour. - - 3 - - The source is available for replication from 45 to 59 minutes after the hour. - + A three-dimensional array of elements in which the element is if the source is available for replication during that specific 15-minute interval. The element is if the source is not available for replication. + + The array is in the form RawSchedule[<day-of-week>, <hour>, <15-minute interval>]. All of these values are zero-based and the week begins at 00:00 on Sunday morning, Coordinated Universal Time. + + The following are the valid values for the day-of-week. + + Day-of-week value + + Indicated day of the week. + + 0 + + Sunday + + 1 + + Monday + + 2 + + Tuesday + + 3 + + Wednesday + + 4 + + Thursday + + 5 + + Friday + + 6 + + Saturday + + + + The hour is zero-based and specified in 24-hour format. For example, 2 P.M. would be specified as 14. Valid values are 0-23. + + The 15-minute interval specifies the 15-minute block within the hour that the source is available for replication. The following table identifies the possible values for the 15-minute interval. + + 15-minute interval + + Description + + 0 + + The source is available for replication from 0 to 14 minutes after the hour. + + 1 + + The source is available for replication from 15 to 29 minutes after the hour. + + 2 + + The source is available for replication from 30 to 44 minutes after the hour. + + 3 + + The source is available for replication from 45 to 59 minutes after the hour. + - @@ -243,13 +243,13 @@ bool isAvailable = scheduleObject.RawSchedule[2, 15, (Int32)50/15]; One of the members that specifies the final 15-minute interval that the source will be available for replication. Adds a range of times for every day of the week to the schedule. - method. - + method. + ]]> @@ -299,19 +299,19 @@ bool isAvailable = scheduleObject.RawSchedule[2, 15, (Int32)50/15]; One of the members that specifies the final 15-minute interval that the source will be available for replication. Adds a range of times for a single day to the schedule. - method. - + method. + ]]> The start time is after the end time. One or more parameters is not valid. - is . + is . @@ -351,13 +351,13 @@ bool isAvailable = scheduleObject.RawSchedule[2, 15, (Int32)50/15]; One of the members that specifies the final 15-minute interval that the source will be available for replication. Adds a range of times for multiple days to the schedule. - method. - + method. + ]]> The start time is after the end time. diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchema.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchema.xml index 069760daf7a..f98eb750a98 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchema.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchema.xml @@ -53,11 +53,11 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the managed resources that are used by the object and, optionally, releases unmanaged resources. - @@ -402,9 +402,9 @@ To be added. A property with the specified name cannot be found. - is . + is . - is zero length. + is zero length. The current object has been disposed. diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaPropertyCollection.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaPropertyCollection.xml index b6dca510a6b..da4da03836f 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaPropertyCollection.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaPropertyCollection.xml @@ -301,7 +301,7 @@ A call to the underlying directory service resulted in an error. The object already exists in this collection. - is . + is . The specified is out of range of the collection. The object has not yet been saved in the Active Directory Domain Services store. diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySiteLink.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySiteLink.xml index a37dc1b8e10..9d78f060ff0 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySiteLink.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySiteLink.xml @@ -64,19 +64,19 @@ The name for the site link. Initializes a new instance of the class using the specified object and name. - A call to the underlying directory service resulted in an error. The target server is either busy or unavailable. - This exception will occur for any of the following reasons. - -- The target in the parameter is not a forest, configuration set, domain controller, or an AD LDS server. - + This exception will occur for any of the following reasons. + +- The target in the parameter is not a forest, configuration set, domain controller, or an AD LDS server. + - is an empty string. or is . @@ -113,10 +113,10 @@ To be added. A call to the underlying directory service resulted in an error. The target server is either busy or unavailable. - This exception will occur for any of the following reasons. - -- The target in the parameter is not a forest, configuration set, domain controller, or an AD LDS server. - + This exception will occur for any of the following reasons. + +- The target in the parameter is not a forest, configuration set, domain controller, or an AD LDS server. + - is an empty string. parameter or is . @@ -166,10 +166,10 @@ To be added. A call to the underlying directory service resulted in an error. The target server is either busy or unavailable. - This exception will occur for any of the following reasons. - -- The target in the parameter is not a forest, configuration set, domain controller, or an AD LDS server. - + This exception will occur for any of the following reasons. + +- The target in the parameter is not a forest, configuration set, domain controller, or an AD LDS server. + - is an empty string. or the is . @@ -592,7 +592,7 @@ Gets or sets the replication interval between sites. The replication interval between sites. To be added. - Invalid specified. + The value being set is invalid. The object has been disposed. @@ -618,11 +618,11 @@ Writes any changes to the object to the Active Directory Domain Services store. - The site object already exists. diff --git a/xml/System.DirectoryServices.ActiveDirectory/Domain.xml b/xml/System.DirectoryServices.ActiveDirectory/Domain.xml index 94ec5cb5682..26a8b2e9324 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/Domain.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/Domain.xml @@ -851,7 +851,7 @@ if the authentication of the trust is selective; if the authentication is domain-wide. To be added. - There is no trust relationship with the that is specified by the parameter. + There is no trust relationship with the that is specified by the parameter. The call to LsaQueryTrustedDomainInfoByName failed. For more information, see LsaQueryTrustedDomainInfoByName. The target server is either busy or unavailable. @@ -891,7 +891,7 @@ if SID filtering is enabled; otherwise, . To be added. - There is no trust relationship with the that is specified by the parameter. + There is no trust relationship with the that is specified by the parameter. A call to the underlying directory service resulted in an error. The target server is either busy or unavailable. @@ -930,7 +930,7 @@ Gets the trust relationship between this domain and the specified domain. A object that represents the trust relationship between this domain and the specified domain. To be added. - There is no trust relationship with the that is specified by the parameter. + There is no trust relationship with the that is specified by the parameter. A call to the underlying directory service resulted in an error. The target server is either busy or unavailable. diff --git a/xml/System.DirectoryServices.ActiveDirectory/Forest.xml b/xml/System.DirectoryServices.ActiveDirectory/Forest.xml index 7c60d16485c..bce05f44d8a 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/Forest.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/Forest.xml @@ -88,24 +88,24 @@ The password for the trust. Creates the local side of a trust relationship with the specified forest. - method. - + method. + ]]> The trust relationship already exists. A call to the underlying directory service resulted in an error. The target server is either busy or unavailable. - name or string is empty. + name or string is empty. - or is . + or is . is not a valid value. The object has been disposed. @@ -142,11 +142,11 @@ One of the members that determines the direction of the trust, relative to this forest. Creates both sides of a trust relationship with the specified forest. - method is used to create only one side of a trust. - + method is used to create only one side of a trust. + ]]> The trust relationship already exists. @@ -188,13 +188,13 @@ The DNS name of the forest that the trust exists with. Deletes the local side of a trust relationship. - method. - + method. + ]]> There is no trust relationship with the that is specified by the parameter. @@ -234,11 +234,11 @@ A object that represents the forest that the trust exists with. Deletes both sides of a trust relationship. - method. - + method. + ]]> There is no trust relationship with the specified . @@ -375,11 +375,11 @@ Finds all of the discoverable global catalogs in this forest. A that contains the collection of global catalogs that were found. - The target server is either busy or unavailable. @@ -413,13 +413,13 @@ Finds all of the discoverable global catalogs in this forest in a specified site. A that contains the collection of global catalogs that were found. - The target server is either busy or unavailable. @@ -819,13 +819,13 @@ if selective authentication is enabled; otherwise, . - There is no trust relationship with the that is specified by . @@ -1023,21 +1023,21 @@ A enumeration value that specifies the new operation level for the forest. Raises the mode of operation for the forest. - value can be raised but not lowered. This means that raising the functionality level of the forest is not reversible and the decision to do this should be made carefully. - + value can be raised but not lowered. This means that raising the functionality level of the forest is not reversible and the decision to do this should be made carefully. + For more information about forest operational modes, see [Domain and forest functionality](https://learn.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-r2-and-2008/dd894353(v%3dws.11)). - - The following table defines the valid values for `forestMode` based on the current operating mode of the forest. - -|Current mode|Mode can be raised to| -|------------------|---------------------------| -||

| -||| -||None| - + + The following table defines the valid values for `forestMode` based on the current operating mode of the forest. + +|Current mode|Mode can be raised to| +|------------------|---------------------------| +||

| +||| +||None| + ]]> A call to the underlying directory service resulted in an error. @@ -1260,11 +1260,11 @@ if SID filtering is to be enabled; otherwise, . Sets the SID filtering state with the specified forest. - There is no trust relationship with the forest that is specified by . @@ -1528,11 +1528,11 @@ A value that specifies the direction of the trust, relative to this forest. Verifies that a previously established trust with the specified forest is valid. - There is no trust relationship with the forest that is specified by , or the target forest does not have the trust direction that is specified by . diff --git a/xml/System.DirectoryServices.ActiveDirectory/ForestTrustDomainInformation.xml b/xml/System.DirectoryServices.ActiveDirectory/ForestTrustDomainInformation.xml index c5cca58f747..50d38a755de 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ForestTrustDomainInformation.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ForestTrustDomainInformation.xml @@ -127,7 +127,7 @@ One of the values that represents the status of the object. To be added. - is not a valid enumeration value. + The value being set is not a valid enumeration value. diff --git a/xml/System.DirectoryServices.ActiveDirectory/ReadOnlyStringCollection.xml b/xml/System.DirectoryServices.ActiveDirectory/ReadOnlyStringCollection.xml index 0bfe8f11e24..39f49118539 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ReadOnlyStringCollection.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ReadOnlyStringCollection.xml @@ -119,7 +119,7 @@ The zero-based index of the first matching object. Returns -1 if no member of this collection is identical to the object. To be added. - is . + is . diff --git a/xml/System.DirectoryServices.Protocols/DirectoryAttribute.xml b/xml/System.DirectoryServices.Protocols/DirectoryAttribute.xml index 6fa343b5e78..52fb8114788 100644 --- a/xml/System.DirectoryServices.Protocols/DirectoryAttribute.xml +++ b/xml/System.DirectoryServices.Protocols/DirectoryAttribute.xml @@ -107,7 +107,7 @@ The constructor creates an instance of the class using the specified attribute name and values. To be added. - or contains a null reference ( in Visual Basic). + or contains a null reference ( in Visual Basic). An element of is not of type string, byte[], or Uri. @@ -200,7 +200,7 @@ The index at which the value has been added. To be added. - contains a null reference ( in Visual Basic). + contains a null reference ( in Visual Basic). @@ -229,7 +229,7 @@ The index at which the value has been added. To be added. - contains a null reference ( in Visual Basic). + contains a null reference ( in Visual Basic). @@ -258,7 +258,7 @@ The index at which the value has been added. To be added. - contains a null reference ( in Visual Basic). + contains a null reference ( in Visual Basic). @@ -288,7 +288,7 @@ is not a byte[][], string[], or Uri[]. - contains a null reference ( in Visual Basic). + contains a null reference ( in Visual Basic). @@ -349,12 +349,12 @@ contains a null reference ( in Visual Basic). is less than zero. - This exception can occur under one of the following conditions: - + This exception can occur under one of the following conditions: + - is multidimensional. - + - is equal to, or greater than, the length of . - + - The number of elements in the source is greater than the space available from to the end of the destination . The type of the source cannot be cast automatically to the type of the destination . @@ -546,11 +546,11 @@ The property gets or sets the object at the specified index. The object at the specified index. - always attempts to convert and return the value object as a string; otherwise it returns a byte array. To get a better performance, use the method if you know the return type of the attribute value. - + always attempts to convert and return the value object as a string; otherwise it returns a byte array. To get a better performance, use the method if you know the return type of the attribute value. + ]]> @@ -608,11 +608,11 @@ The to evaluate. The method verifies that is a object. - object. - + object. + ]]> diff --git a/xml/System.DirectoryServices.Protocols/DirectoryRequest.xml b/xml/System.DirectoryServices.Protocols/DirectoryRequest.xml index 2aba282fe47..d127e9c2352 100644 --- a/xml/System.DirectoryServices.Protocols/DirectoryRequest.xml +++ b/xml/System.DirectoryServices.Protocols/DirectoryRequest.xml @@ -62,8 +62,8 @@ System.String - The property contains the specified in the request. - The specified in the request. + Gets or sets the request ID specified in the request. + The request ID specified in the request. To be added. diff --git a/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml b/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml index 1b6fc15263a..a088f9c4e66 100644 --- a/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml +++ b/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml @@ -47,11 +47,11 @@ The constructor creates an instance of the class. - @@ -479,8 +479,8 @@ System.String - The property contains the associated with the . - The associated with the . + Gets or sets the request ID associated with the . + The request ID associated with the . To be added. @@ -528,11 +528,11 @@ The property contains an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. - + using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + ]]> diff --git a/xml/System.DirectoryServices.Protocols/LdapConnection.xml b/xml/System.DirectoryServices.Protocols/LdapConnection.xml index d6aef6d415c..37b86ded2cc 100644 --- a/xml/System.DirectoryServices.Protocols/LdapConnection.xml +++ b/xml/System.DirectoryServices.Protocols/LdapConnection.xml @@ -24,11 +24,11 @@ The class creates a TCP/IP or UDP LDAP connection to Microsoft Active Directory Domain Services or an LDAP server. - property on the object and property on the object are both set, the certificate specified in the property is ignored. - + property on the object and property on the object are both set, the certificate specified in the property is ignored. + ]]> @@ -202,7 +202,7 @@ A supported authentication type. To be added. - is out of range. + The authentication type being set is out of range. @@ -599,8 +599,6 @@ If a connection was created using `ldap_connect`, and if no binding function is A object that contains the response from the server. To be added. The object is already disposed. The object handle is not valid. - - is null ( in Visual Basic). Request is of type DsmlAuthRequest. The error code returned by LDAP does not map to a enumeration error code. The server returned a object with an error. @@ -634,8 +632,6 @@ If a connection was created using `ldap_connect`, and if no binding function is A object that contains the response from the server. To be added. The object is already disposed. The object handle is not valid. - - is null ( in Visual Basic). Request is of type DsmlAuthRequest. The error code returned by LDAP does not map to a enumeration error code. The server returned a object with an error. @@ -662,11 +658,11 @@ If a connection was created using `ldap_connect`, and if no binding function is The property contains an object that specifies the session options. An object that specifies the session options. - property on the object and property on the object are both set, the certificate specified in the property is ignored. - + property on the object and property on the object are both set, the certificate specified in the property is ignored. + ]]> diff --git a/xml/System.DirectoryServices.Protocols/LdapDirectoryIdentifier.xml b/xml/System.DirectoryServices.Protocols/LdapDirectoryIdentifier.xml index 2ac1683b531..4709261d751 100644 --- a/xml/System.DirectoryServices.Protocols/LdapDirectoryIdentifier.xml +++ b/xml/System.DirectoryServices.Protocols/LdapDirectoryIdentifier.xml @@ -48,8 +48,8 @@ - The server ID. A string specifying the server which can be a domain name, LDAP server name or dotted strings representing the IP address of the LDAP server, or . If , it represents the identity of any domain controller in the domain associated with the computer account. - + The server ID. A string specifying the server which can be a domain name, LDAP server name or dotted strings representing the IP address of the LDAP server, or . If , it represents the identity of any domain controller in the domain associated with the computer account. + Optionally, this parameter may also include a port number, separated from the ID itself by a colon (:). The constructor creates an instance of the class using the specified server. To be added. @@ -143,7 +143,7 @@ The constructor creates an instance of the class using the specified server and properties. This constructor creates an identifier that represents a set of LDAP servers. To be added. - has space. + has space. @@ -209,7 +209,7 @@ The constructor creates an instance of the class using the specified server and properties. This constructor creates an identifier that represents a set of LDAP servers. To be added. - has space. + has space. diff --git a/xml/System.DirectoryServices.Protocols/SearchResultEntryCollection.xml b/xml/System.DirectoryServices.Protocols/SearchResultEntryCollection.xml index eca3dcc0e73..d0eada63b0e 100644 --- a/xml/System.DirectoryServices.Protocols/SearchResultEntryCollection.xml +++ b/xml/System.DirectoryServices.Protocols/SearchResultEntryCollection.xml @@ -81,10 +81,10 @@ is less than zero. is multidimensional. - - -or- - - The number of elements in the source is greater than the available space from to the end of the destination . + + -or- + + The number of elements in the source is greater than the available space from to the end of the destination array specified by . The type of the source cannot be cast automatically to the type of the destination . diff --git a/xml/System.DirectoryServices.Protocols/SearchResultReferenceCollection.xml b/xml/System.DirectoryServices.Protocols/SearchResultReferenceCollection.xml index b73b27d2878..56fbfe4c5ef 100644 --- a/xml/System.DirectoryServices.Protocols/SearchResultReferenceCollection.xml +++ b/xml/System.DirectoryServices.Protocols/SearchResultReferenceCollection.xml @@ -81,11 +81,11 @@ is less than zero. is multidimensional. - - -or- - + + -or- + The number of elements in the source is greater than the available space from to the end of the destination . - The type of the source cannot be cast automatically to the type of the destination . + The type of the source cannot be cast automatically to the type of the destination array specified by . diff --git a/xml/System.DirectoryServices/DirectoryServicesPermission.xml b/xml/System.DirectoryServices/DirectoryServicesPermission.xml index d3acb95a51a..3748c873bde 100644 --- a/xml/System.DirectoryServices/DirectoryServicesPermission.xml +++ b/xml/System.DirectoryServices/DirectoryServicesPermission.xml @@ -152,7 +152,7 @@ One of the values. Initializes a new instance of the class with the specified permission state. To be added. - The parameter is not a valid value of . + The parameter is not a valid value of . diff --git a/xml/System.DirectoryServices/PropertyCollection.xml b/xml/System.DirectoryServices/PropertyCollection.xml index 300799b709a..abe02d5f398 100644 --- a/xml/System.DirectoryServices/PropertyCollection.xml +++ b/xml/System.DirectoryServices/PropertyCollection.xml @@ -125,11 +125,11 @@ Gets the number of properties in this collection. The number of properties in this collection. - , so each will throw a . - + , so each will throw a . + ]]> An error occurred during the call to the underlying interface. @@ -193,13 +193,13 @@ Gets the specified property. The value of the specified property. - class. - - In JScript, you can use the default indexed properties defined by a type, but you cannot explicitly define your own. However, specifying the expando attribute on a class automatically provides a default indexed property with a type of Object and an index type of . - + class. + + In JScript, you can use the default indexed properties defined by a type, but you cannot explicitly define your own. However, specifying the expando attribute on a class automatically provides a default indexed property with a type of Object and an index type of . + ]]> @@ -227,11 +227,11 @@ Gets the names of the properties in this collection. An object that contains the names of the properties in this collection. - property, a might be thrown due to an error while accessing the underlying interface. - + property, a might be thrown due to an error while accessing the underlying interface. + ]]> @@ -272,10 +272,10 @@ is less than zero. - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in the source is greater than the available space from to the end of the destination . The type of the source cannot be cast automatically to the type of the destination . @@ -306,37 +306,37 @@ if access to the is synchronized (thread safe); otherwise, . - returns an object, which can be used to synchronize access to the . - - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - - Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions that result from changes made by other threads. - - - The following example shows how to lock the collection using the during the entire enumeration: - -```csharp -ICollection myCollection = new ICollection(); - lock(myCollection.SyncRoot) { - foreach (Object item in myCollection) { - // Insert your code here. - } - } -``` - -```vb -Dim myCollection As New ICollection() - Dim item As Object - SyncLock myCollection.SyncRoot - For Each item In myCollection - ' Insert your code here. - Next item - End SyncLock -``` - + returns an object, which can be used to synchronize access to the . + + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + + Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions that result from changes made by other threads. + + + The following example shows how to lock the collection using the during the entire enumeration: + +```csharp +ICollection myCollection = new ICollection(); + lock(myCollection.SyncRoot) { + foreach (Object item in myCollection) { + // Insert your code here. + } + } +``` + +```vb +Dim myCollection As New ICollection() + Dim item As Object + SyncLock myCollection.SyncRoot + For Each item In myCollection + ' Insert your code here. + Next item + End SyncLock +``` + ]]> @@ -367,53 +367,53 @@ Dim myCollection As New ICollection() Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - - In the absence of a Synchronized method on a collection, the expected usage for looks like this: - -```csharp -ICollection MyCollection =... - lock(MyCollection.SyncRoot) { - // Some operation on the collection, which is now thread safe. - } -``` - -```vb -Dim myCollection as New ICollection() - SyncLock myCollection.SyncRoot - ' Some operation on the collection, which is now thread safe. - End SyncLock -``` - - Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - - - The following code example shows how to lock the collection using the during the entire enumeration: - -```csharp -ICollection myCollection = new ICollection(); - lock(myCollection.SyncRoot) { - foreach (Object item in myCollection) { - // Insert your code here. - } - } -``` - -```vb -Dim myCollection As New ICollection() - Dim item As Object - SyncLock myCollection.SyncRoot - For Each item In myCollection - ' Insert your code here. - Next item - End SyncLock -``` - + namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + + In the absence of a Synchronized method on a collection, the expected usage for looks like this: + +```csharp +ICollection MyCollection =... + lock(MyCollection.SyncRoot) { + // Some operation on the collection, which is now thread safe. + } +``` + +```vb +Dim myCollection as New ICollection() + SyncLock myCollection.SyncRoot + ' Some operation on the collection, which is now thread safe. + End SyncLock +``` + + Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + + + The following code example shows how to lock the collection using the during the entire enumeration: + +```csharp +ICollection myCollection = new ICollection(); + lock(myCollection.SyncRoot) { + foreach (Object item in myCollection) { + // Insert your code here. + } + } +``` + +```vb +Dim myCollection As New ICollection() + Dim item As Object + SyncLock myCollection.SyncRoot + For Each item In myCollection + ' Insert your code here. + Next item + End SyncLock +``` + ]]> @@ -450,29 +450,29 @@ Dim myCollection As New ICollection() The to use as the value of the element to add. Adds an element with the provided key and value to the object. - property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - - - -## Examples - The following example shows how to implement the method. This code example is part of a larger example provided for the class. - + property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + + + +## Examples + The following example shows how to implement the method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet9"::: + ]]> is . An element with the same key already exists in the object. - The is read-only. - - -or- - + The is read-only. + + -or- + The has a fixed size. @@ -503,15 +503,15 @@ Dim myCollection As New ICollection() Removes all elements from the object. - method. This example is part of a larger example provided for the class. - + method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet8"::: + ]]> The object is read-only. @@ -548,19 +548,19 @@ Dim myCollection As New ICollection() if the contains an element with the key; otherwise, . - method. This example is part of a larger example provided for the class. - + method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet5"::: + ]]> - is . + is . @@ -589,22 +589,22 @@ Dim myCollection As New ICollection() if the object has a fixed size; otherwise, . - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet6"::: + ]]> @@ -635,20 +635,20 @@ Dim myCollection As New ICollection() if the object is read-only; otherwise, . - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet4"::: + ]]> @@ -689,30 +689,30 @@ Dim myCollection As New ICollection() Gets or sets the element with the specified key. The element with the specified key. - property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - - - -## Examples - The following example shows how to implement the property. This code example is part of a larger example provided for the class. - + property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + + + +## Examples + The following example shows how to implement the property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet13"::: + ]]> is . - The property is set and the object is read-only. - - -or- - + The property is set and the object is read-only. + + -or- + The property is set, does not exist in the collection, and the has a fixed size. @@ -742,20 +742,20 @@ Dim myCollection As New ICollection() Gets an object containing the keys of the object. An object containing the keys of the object. - object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. - - - -## Examples - The following example shows how to implement the property. This code example is part of a larger example provided for the class. - + object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. + + + +## Examples + The following example shows how to implement the property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet10"::: + ]]> @@ -790,23 +790,23 @@ Dim myCollection As New ICollection() The key of the element to remove. Removes the element with the specified key from the object. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb" id="Snippet7"::: + ]]> is . - The object is read-only. - - -or- - + The object is read-only. + + -or- + The has a fixed size. @@ -837,24 +837,24 @@ Dim myCollection As New ICollection() Returns an object. An .object. - also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until either or is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. To set to the first element of the collection again, you can call followed by . - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and its behavior is undefined. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - + also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until either or is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. To set to the first element of the collection again, you can call followed by . + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and its behavior is undefined. + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + ]]> @@ -886,11 +886,11 @@ Dim myCollection As New ICollection() Gets the values of the properties in this collection. An that contains the values of the properties in this collection. - property, a exception might be thrown due to an error while accessing the underlying interface. - + property, a exception might be thrown due to an error while accessing the underlying interface. + ]]>