From 72159592a0f05c5acf74defdd945445ece00deec Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 20 Apr 2022 16:10:58 -0700 Subject: [PATCH 1/2] config files are .net framework only --- xml/System.Diagnostics/BooleanSwitch.xml | 26 ++++---- .../ConsoleTraceListener.xml | 16 ++--- xml/System.Diagnostics/Debug.xml | 51 ++++++++-------- .../DefaultTraceListener.xml | 10 ++-- .../DelimitedListTraceListener.xml | 17 ++++-- .../EventLogTraceListener.xml | 14 ++--- .../EventSchemaTraceListener.xml | 8 +-- xml/System.Diagnostics/EventTypeFilter.xml | 6 +- .../PresentationTraceSources.xml | 15 +++-- xml/System.Diagnostics/SourceSwitch.xml | 10 ++-- xml/System.Diagnostics/Switch.xml | 10 ++-- .../TextWriterTraceListener.xml | 6 +- xml/System.Diagnostics/Trace.xml | 59 +++++++++---------- xml/System.Diagnostics/TraceLevel.xml | 19 +----- xml/System.Diagnostics/TraceOptions.xml | 8 +-- xml/System.Diagnostics/TraceSource.xml | 30 +++++----- xml/System.Diagnostics/TraceSwitch.xml | 56 ++++++++---------- .../XmlWriterTraceListener.xml | 12 ++-- 18 files changed, 165 insertions(+), 208 deletions(-) diff --git a/xml/System.Diagnostics/BooleanSwitch.xml b/xml/System.Diagnostics/BooleanSwitch.xml index f5ca7499411..53a97229183 100644 --- a/xml/System.Diagnostics/BooleanSwitch.xml +++ b/xml/System.Diagnostics/BooleanSwitch.xml @@ -50,9 +50,9 @@ ## Remarks You can use a Boolean trace switch to enable or disable messages based on their importance. Use the property to get the current value of the switch. - You can enable or disable a through the application configuration file and then use the configured value in your application. Alternately, you can create a in your code and set the property directly to instrument a specific section of code. - - To configure a , edit the configuration file that corresponds to the name of your application. Within this file, you can add or remove a switch, set a switch's value, or clear all the switches previously set by the application. The configuration file should be formatted like the following example. +You can create a in your code and set the property directly to instrument a specific section of code. + +For .NET Framework apps only, you can also enable or disable a through the application configuration file and then use the configured value in your application. To configure a , edit the configuration file that corresponds to the name of your application. Within this file, you can add or remove a switch, set a switch's value, or clear all the switches previously set by the application. The configuration file should be formatted like the following example. ```xml @@ -64,13 +64,15 @@ ``` - This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your application, you can use the configured switch value by creating a with the same name, as shown in the following code example. + This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your .NET Framework application, you can use the configured switch value by creating a with the same name, as shown in the following code example. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BooleanSwitch.BooleanSwitch Example/CPP/remarks.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/BooleanSwitch/Overview/remarks.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BooleanSwitch.BooleanSwitch Example/VB/remarks.vb" id="Snippet2"::: - - By default, the property is set using the value specified in the configuration file. Configure the switch with a value of 0 to set the property to `false`; configure the switch with a nonzero value to set the property to `true`. If the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to `false` by default. + +For .NET Core and .NET 5+ apps, the property of the new switch is set to `false` by default. + +For .NET Framework apps, the property is set using the value specified in the configuration file. Configure the switch with a value of 0 to set the property to `false`; configure the switch with a nonzero value to set the property to `true`. If the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to `false` by default. You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -84,9 +86,7 @@ For more information on instrumenting your application, see and . For more information about configuring and using trace switches, see [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches). > [!NOTE] -> To improve performance, you can make members `static` in your class. - - +> To improve performance, you can make members `static` in your class. ## Examples The following example creates a and uses the switch to determine whether to print an error message. You create the switch at the class level. The `Main` method passes its location to `MyMethod`, which prints an error message and where the error occurred. @@ -162,9 +162,9 @@ , the `displayName` parameter is used to find initial switch settings. If the constructor cannot find initial settings, the property is set to `false` (disabled). + When you create a , the `displayName` parameter is used to find initial switch settings for .NET Framework apps. If the constructor cannot find initial settings, or for .NET Core and .NET 5+ apps, the property is set to `false` (disabled). - To set the level of your , edit the configuration file corresponding to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all switches previously set by the application. The configuration file should be formatted like the following example: + To set the level of your in a .NET Framework app, edit the configuration file corresponding to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all switches previously set by the application. The configuration file should be formatted like the following example: ```xml @@ -180,9 +180,7 @@ ``` > [!NOTE] -> The switches you created should be `static`. - - +> The switches you created should be `static`. ## Examples The following example creates a and uses the switch to determine whether to print an error message. The switch is created at the class level. The `Main` method passes its location to `MyMethod`, which prints an error message and where the error occurred. diff --git a/xml/System.Diagnostics/ConsoleTraceListener.xml b/xml/System.Diagnostics/ConsoleTraceListener.xml index 6a021ccc5cc..66dab0b6459 100644 --- a/xml/System.Diagnostics/ConsoleTraceListener.xml +++ b/xml/System.Diagnostics/ConsoleTraceListener.xml @@ -31,12 +31,12 @@ Use the class to write trace and debugging messages to the console. You can initialize a object to write trace messages to the stream or to the stream. > [!IMPORTANT] -> interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. When trace and debugging output is enabled, the messages are written to the specified stream, which is similar to the way messages are written with the or methods. In a console application, the output and error streams write messages to the existing console window, or you can redirect the streams to write to a instance. > [!NOTE] -> If the console does not exist, as in a Windows-based application, messages written to the console are not displayed. +> If the console does not exist, as in a Windows-based application, messages written to the console are not displayed. Add a object to the appropriate collection if you want messages written through , , or to be written to the console. In addition, you can write messages directly to the console using the or methods. @@ -49,29 +49,25 @@ - To enable tracing in C#, add the **/d:TRACE** flag to the compiler command line when you compile your code, or add **#define TRACE** to the top of your file. In Visual Basic, add the **/d:TRACE=True** flag to the compiler command line. - You can add a object to the collection in your code, or you can add a object to the collection through the application configuration file. Add the object in your code to write messages for a specific code section or execution path. Add the object in your application configuration file to direct all trace and debug messages to the console while the application executes. + You can add a object to the collection in your code. Or, for .NET Framework apps, you can add a object to the collection through the application configuration file. Add the object in your code to write messages for a specific code section or execution path. Add the object in your application configuration file to direct all trace and debug messages to the console while the application executes. To write trace and debug messages to the console for a specific section of code, initialize a object and add it to the collection. Instrument the section of code that contains messages using the or classes. At the end of the code section, remove the object from the collection, and call the method on the . - To direct all trace and debug messages to the console while the application executes, add a object to the application configuration file. Edit the configuration file that corresponds to the name of your application, or the app.config file in a Visual Studio 2005 project. In this file, insert an element for a . - - The following example adds a object named `configConsoleListener` to the collection. +For .NET Framework apps, to direct all trace and debug messages to the console while the application executes, add a object to the application configuration file. The following example adds a object named `configConsoleListener` to the collection. ```xml - + ``` - For details about adding trace listeners in the application configuration file, see [<listeners>](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-trace). - - + For details about adding trace listeners in the application configuration file, see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-trace). ## Examples The following code example implements a console application consisting of a class with two public methods. diff --git a/xml/System.Diagnostics/Debug.xml b/xml/System.Diagnostics/Debug.xml index f657149c1fb..74a04081035 100644 --- a/xml/System.Diagnostics/Debug.xml +++ b/xml/System.Diagnostics/Debug.xml @@ -54,11 +54,17 @@ class to print debugging information and check your logic with assertions, you can make your code more robust without impacting the performance and code size of your shipping product. - This class provides methods to display an dialog box, and to emit an assertion that will always fail. This class provides write methods in the following variations: , , , and . +To make your code more robust without impacting the performance and code size of your shipping product, use methods in the class to print debugging information and check your logic with assertions. - The and classes provide means to dynamically control the tracing output. You can modify the values of these switches without recompiling your application. For information on using the configuration file to set a switch, see the class and the [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches) article. + This class provides methods to display an dialog box, and to emit an assertion that will always fail. This class provides write methods in the following variations: + +- +- +- +- + + The and classes provide means to dynamically control the tracing output. For .NET Framework apps, you can modify the values of these switches without recompiling your application. For information on using the configuration file to set a switch in .NET Framework apps, see the class and the [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches) article. You can customize the tracing output's target by adding instances to or removing instances from the collection. The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. By default, the class emits trace output. @@ -67,7 +73,7 @@ You can modify the level of indentation using the method or the property. To modify the indent spacing, use the property. You can specify whether to automatically flush the output buffer after each write by setting the property to `true`. - To set the and for , you can edit the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. +For .NET Framework apps, you can set the and for by editing your app's configuration file. The configuration file should be formatted as shown in the following example. ```xml @@ -77,10 +83,10 @@ ``` - The attribute is applied to the methods of . Compilers that support ignore calls to these methods unless "DEBUG" is defined as a conditional compilation symbol. Refer to a compiler's documentation to determine whether is supported and the syntax for defining a conditional compilation symbol. + The attribute is applied to the methods of . Compilers that support ignore calls to these methods unless `DEBUG` is defined as a conditional compilation symbol. Refer to a compiler's documentation to determine whether is supported and the syntax for defining a conditional compilation symbol. > [!NOTE] -> In Visual Studio C# and Visual Basic projects, by default, the `DEBUG` conditional compilation symbol is defined for debug builds, and the `TRACE` symbol is defined for both debug and release builds. For information about how to disable this behavior, see the Visual Studio documentation. For information about conditional debugging in Visual C++, see [Debug class (C++/CLI)](/cpp/dotnet/debug-class-cpp-cli). +> In Visual Studio C# and Visual Basic projects, by default, the `DEBUG` conditional compilation symbol is defined for debug builds, and the `TRACE` symbol is defined for both debug and release builds. For information about conditional debugging in Visual C++, see [Debug class (C++/CLI)](/cpp/dotnet/debug-class-cpp-cli). To define the `DEBUG` conditional compilation symbol in C#, add the `/d:DEBUG` option to the compiler command line when you compile your code using a command line, or add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` option to the compiler command line or add `#Const DEBUG=True` to the file. @@ -180,20 +186,17 @@ The following example uses to indicate the begin ## Remarks By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). -> [!IMPORTANT] -> The `Assert` methods are not available for Windows Store apps. - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends a failure message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> Windows 8.x Store apps do not support modal dialog boxes, so they behave the same in user interface mode and non-user interface mode. The message is written to the active trace listeners in debugging mode, or no message is written in release mode. +> Windows 8.x apps do not support modal dialog boxes, so they behave the same in user interface mode and non-user interface mode. The message is written to the active trace listeners in debugging mode, or no message is written in release mode. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -290,9 +293,9 @@ This overload was introduced in .NET 6 to improve performance. In comparison to When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear> element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) or the [<remove> element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -383,9 +386,9 @@ This overload was introduced in .NET 6 to improve performance. In comparison to When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -491,9 +494,9 @@ This overload was introduced in .NET 6 to improve performance. In comparison to When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear> element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) or the [<remove> element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -585,9 +588,9 @@ This overload was introduced in .NET 6 to improve performance. In comparison to When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -697,9 +700,9 @@ The following example checks whether the `type` parameter is valid. If `type` is When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -760,7 +763,7 @@ The following example checks whether the `type` parameter is valid. If `type` is Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. - To set the and for , you can also edit the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. +For .NET Framework apps, you can also set the and properties for by editing the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. ```xml @@ -1316,7 +1319,7 @@ End of list of errors ## Remarks A interprets this number as spaces. An ignores this value. - To set the and for , you can also edit the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. +For .NET Framework apps, you can also set the and properties for by editing the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. ```xml diff --git a/xml/System.Diagnostics/DefaultTraceListener.xml b/xml/System.Diagnostics/DefaultTraceListener.xml index a9054cabbe8..af3a6e4dfd7 100644 --- a/xml/System.Diagnostics/DefaultTraceListener.xml +++ b/xml/System.Diagnostics/DefaultTraceListener.xml @@ -56,7 +56,7 @@ The method, by default, displays a message box when the application is running in a user interface mode; it also emits the message using . > [!NOTE] -> The display of the message box for and method calls depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), by the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box for and method calls depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. You must enable tracing or debugging to use a trace listener. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -64,7 +64,7 @@ - To enable tracing in C#, add the `/d:TRACE` flag to the compiler command line when you compile your code, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` flag to the compiler command line. - To add a trace listener, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its type and set its parameters, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted similar to the following example: +For .NET Framework apps, you can add a trace listener by editing the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its type and set its parameters, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted similar to the following example: ```xml @@ -72,14 +72,12 @@ - + -``` - - +``` ## Examples The following code example calculates binomial coefficients, which are values used in probability and statistics. This example uses a to trace results and log errors. It creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. diff --git a/xml/System.Diagnostics/DelimitedListTraceListener.xml b/xml/System.Diagnostics/DelimitedListTraceListener.xml index 66a9fe03376..63c5dec0d2c 100644 --- a/xml/System.Diagnostics/DelimitedListTraceListener.xml +++ b/xml/System.Diagnostics/DelimitedListTraceListener.xml @@ -44,14 +44,14 @@ The trace output is in a delimited text format that uses the delimiter specified by the property. The delimiter is used to terminate each field in a line of output. For example, to display the trace output in a Microsoft Excel spreadsheet, you might specify a comma (",") as a delimiter and create a comma-separated value (CSV) file. > [!IMPORTANT] -> interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - You can enable or disable a through the application configuration file and then use the configured in your application. Alternately, you can create a in your code. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + +You can create a in your code. Alternatively, in .NET Framework apps only, you can enable or disable a through the application configuration file and then use the configured in your application. > [!NOTE] > The delimits only text that is emitted by using the methods that have names starting with the word `Trace`, such as or . Trace data that is emitted by using the and methods is not delimited. - To configure a , edit the configuration file that corresponds to the name of your application. In this file, you can add a listener, set the properties for a listener, or remove a listener. The configuration file should be formatted as shown in the following example: +To configure a in a .NET Framework app, edit the configuration file that corresponds to the name of your application. In this file, you can add a listener, set the properties for a listener, or remove a listener. The configuration file should be formatted as shown in the following example: ```xml @@ -435,7 +435,10 @@ property using the `delimiter` attribute in a configuration file: + +The default delimiter is ";" (semicolon). + +The following configuration file example shows how to set the property using the `delimiter` attribute in a configuration file for a .NET Framework app: ```xml @@ -506,7 +509,9 @@ is used to set the property. The following configuration file example shows the use of the `delimiter` attribute to set the property: + A custom attribute is an attribute that is not inherited from the base class that can be used to set a property for the class. The custom attribute for is used to set the property. + +The following .NET Framework application configuration file example shows the use of the `delimiter` attribute to set the property: ```xml diff --git a/xml/System.Diagnostics/EventLogTraceListener.xml b/xml/System.Diagnostics/EventLogTraceListener.xml index d7c83bfe9d6..1846120bdf2 100644 --- a/xml/System.Diagnostics/EventLogTraceListener.xml +++ b/xml/System.Diagnostics/EventLogTraceListener.xml @@ -29,9 +29,9 @@ can be added to the , , or collections to send output from tracing or debugging to an . You can add the instance in your code or specify it in the application configuration file. To add an using an application configuration file, edit the file that corresponds to the name of your application or the app.config file in a Visual Studio 2005 project. In this file, insert an element for a type. - - The following example adds a object named `myListener` to the collection. The `initializeData` parameter specifies the name of the event log source that is to be passed to the constructor. + An instance of this can be added to the , , or collections to send output from tracing or debugging to an . You can add the instance in your code or, for a .NET Framework app, specify it in the application configuration file. + +To add an using a .NET Framework application configuration file, edit the file that corresponds to the name of your application. In this file, insert an element for a type. The following example adds a object named `myListener` to the collection. The `initializeData` parameter specifies the name of the event log source that is to be passed to the constructor. ```xml @@ -45,9 +45,7 @@ -``` - - For more information about how to add trace listeners in the application configuration file, see or . +``` > [!NOTE] > If the for the event log that is associated with the instance does not exist, a new event source is created. To create an event source in Windows Vista, Windows XP Professional, or Windows Server 2003, you must have administrative privileges. @@ -61,9 +59,7 @@ The method closes the event log so it no longer receives tracing or debugging output. The and methods write a message to the event log. > [!NOTE] -> To avoid the possibility of writing large amounts of data to the event log, the does not output the optional trace data specified by the property. - - +> To avoid the possibility of writing large amounts of data to the event log, the does not output the optional trace data specified by the property. ## Examples The following example creates a trace listener that sends output to an event log. First, the code creates a new that uses the source `myEventLogSource`. Next, `myTraceListener` is added to the collection. Finally, the example sends a line of output to the object. diff --git a/xml/System.Diagnostics/EventSchemaTraceListener.xml b/xml/System.Diagnostics/EventSchemaTraceListener.xml index fbd2656d69e..f747f96ee6c 100644 --- a/xml/System.Diagnostics/EventSchemaTraceListener.xml +++ b/xml/System.Diagnostics/EventSchemaTraceListener.xml @@ -26,9 +26,9 @@ The class converts tracing and debugging information into an XML-encoded text stream. The description of the XML output is shown in the tables later in this section. - You can enable or disable an object through the application configuration file, and then use the configured object in your application. Alternately, you can create an object in your code. We recommend that you enable trace listeners through the application configuration file. For information about the use of configuration files for tracing and debugging, see [Trace and Debug Settings Schema](/dotnet/framework/configure-apps/file-schema/trace-debug/). +You can create an object in your code. Alternatively, for .NET Framework apps, you can enable or disable an object through the application configuration file, and then use the configured object in your application. For information about the use of configuration files for tracing and debugging in .NET Framework apps, see [Trace and Debug Settings Schema](/dotnet/framework/configure-apps/file-schema/trace-debug/). - To configure an object, modify the configuration file that corresponds to the name of your application. In this file, you can add, remove, or set the properties for a listener. The configuration file should be formatted as follows: + To configure an object in a .NET Framework app, modify the configuration file that corresponds to the name of your application. In this file, you can add, remove, or set the properties for a listener. The configuration file should be formatted as follows: ```xml @@ -96,9 +96,7 @@ |"|"| |\|'| |0xD|&\#xD;| -|0xA|&\#xA;| - - +|0xA|&\#xA;| ## Examples The following code example demonstrates how to use the class. diff --git a/xml/System.Diagnostics/EventTypeFilter.xml b/xml/System.Diagnostics/EventTypeFilter.xml index 4f72c630c73..6692913d66f 100644 --- a/xml/System.Diagnostics/EventTypeFilter.xml +++ b/xml/System.Diagnostics/EventTypeFilter.xml @@ -43,9 +43,9 @@ ## Remarks One of several different types of filters can be assigned to a trace listener through the property to provide a layer of screening beyond that provided by the . The filter can be used to control the event types that are produced by the listener. - This class filters events based on the value of the property. This property can be set by code or in a configuration file to specify the event type of messages that should be traced by the listener. The value of the property indicates the threshold at which to begin tracing. Event types at and above the specified level are traced. The method, called by listeners to determine if an event should be traced, uses the value of the property. + This class filters events based on the value of the property. This property can be set by code or, for .NET Framework apps, in a configuration file to specify the event type of messages that should be traced by the listener. The value of the property indicates the threshold at which to begin tracing. Event types at and above the specified level are traced. The method, called by listeners to determine if an event should be traced, uses the value of the property. - To set the event type at which to begin tracing, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its filter type, and specify the event type to trace. The configuration file should be formatted as follows. +To set the event type at which to begin tracing in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its filter type, and specify the event type to trace. The configuration file should be formatted as follows. ```xml @@ -60,7 +60,7 @@ ``` - For more information about how to initialize data for an , see [<filter>](/dotnet/framework/configure-apps/file-schema/trace-debug/filter-element-for-add-for-sharedlisteners). + For more information about how to initialize data for an , see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/filter-element-for-add-for-sharedlisteners). ]]> diff --git a/xml/System.Diagnostics/PresentationTraceSources.xml b/xml/System.Diagnostics/PresentationTraceSources.xml index db9f66de55b..d10d8ed1814 100644 --- a/xml/System.Diagnostics/PresentationTraceSources.xml +++ b/xml/System.Diagnostics/PresentationTraceSources.xml @@ -23,20 +23,19 @@ diff --git a/xml/System.Diagnostics/SourceSwitch.xml b/xml/System.Diagnostics/SourceSwitch.xml index 3a1c863ad73..2cb2f95c9a3 100644 --- a/xml/System.Diagnostics/SourceSwitch.xml +++ b/xml/System.Diagnostics/SourceSwitch.xml @@ -110,7 +110,7 @@ ## Remarks The `name` parameter is used to set the value of the property. - To set the level of your , edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. To add a source switch, the configuration file should be formatted as shown in the following example. + To set the level of your in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. To add a source switch, the configuration file should be formatted as shown in the following example. ```xml @@ -170,9 +170,9 @@ The `displayName` parameter is used to set the value of the property; the `defaultSwitchValue` parameter is saved as a field and used to initialize the property on first reference. > [!NOTE] -> If the switch is defined in a configuration file and the `value` attribute is specified, the configuration file value takes precedence and the `defaultSwitchValue` is ignored. +> For .NET Framework apps, if the switch is defined in a configuration file and the `value` attribute is specified, the configuration file value takes precedence and the `defaultSwitchValue` is ignored. - To set the level of your , edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. To add a source switch, the configuration file should be formatted as shown in the following example. +To set the level of your in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. To add a source switch, the configuration file should be formatted as shown in the following example. ```xml @@ -182,9 +182,7 @@ -``` - - +``` ## Examples The following code example creates a with the name "SourceSwitch" and a default value of . This code example is part of a larger example provided for the class. diff --git a/xml/System.Diagnostics/Switch.xml b/xml/System.Diagnostics/Switch.xml index f0c9e2e0978..5127fac5cbc 100644 --- a/xml/System.Diagnostics/Switch.xml +++ b/xml/System.Diagnostics/Switch.xml @@ -44,7 +44,7 @@ ## Remarks A switch provides an efficient mechanism for controlling tracing and debugging output at run time using external settings. The class implements default behavior for switches, allowing you to change the switch level at run time. - This class is the base class for the , and the classes. These switches meet most debugging and tracing needs. For more information about trace switches, see [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches). + This class is the base class for the , , and classes. These switches meet most debugging and tracing needs. For more information about trace switches, see [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches). You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -52,7 +52,7 @@ - To enable tracing using in C#, add the `/d:TRACE` flag to the compiler command line when you compile your code, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` flag to the compiler command line. - To set the level of your switch, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: + To set the level of your switch in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: ```xml @@ -67,9 +67,7 @@ This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your application, you can use the configured switch value by creating a with the same name, as shown in the following code example. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Switch Example/CPP/remarks.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/remarks.cs" id="Snippet4"::: - - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/remarks.cs" id="Snippet4"::: ## Examples The following example shows how to define a new class with four levels of tracing that can be used to trace a call stack. You can use the switch to instrument your application to log each time the method is entered or exited. @@ -165,7 +163,7 @@ ## Remarks When you create a new object, the value of the `displayName` parameter is used to find initial switch settings. The default value is an empty string (""). - Within the XML configuration file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. Dynamic changes to the configuration file are not detected while the application is executing. You must stop and restart an application before changes to the configuration file take effect. The configuration file should be formatted like the following example: + Within the XML configuration file of a .NET Framework app, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. Dynamic changes to the configuration file are not detected while the application is executing. You must stop and restart an application before changes to the configuration file take effect. The configuration file should be formatted like the following example: ```xml diff --git a/xml/System.Diagnostics/TextWriterTraceListener.xml b/xml/System.Diagnostics/TextWriterTraceListener.xml index a3fff8bfd95..ac81b10c675 100644 --- a/xml/System.Diagnostics/TextWriterTraceListener.xml +++ b/xml/System.Diagnostics/TextWriterTraceListener.xml @@ -55,7 +55,7 @@ - To enable tracing in C#, add the `/d:TRACE` flag to the compiler command line when you compile your code, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` flag to the compiler command line. - To add a trace listener, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its type and set its parameter, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted like the following example. + To add a trace listener in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its type and set its parameter, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted like the following example. ```xml @@ -73,9 +73,7 @@ ``` > [!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. ## Examples The following example implements an instance of the class that uses a called `myOutputWriter` to write to a file named `TestFile.txt`. First the example creates a file for output. Then it creates the for the first text writer, assigns it the output file, and adds it to the . Then, the code outputs one line of text to the file. Finally, the example flushes the output buffer. diff --git a/xml/System.Diagnostics/Trace.xml b/xml/System.Diagnostics/Trace.xml index fa8926c71b4..fc2941448de 100644 --- a/xml/System.Diagnostics/Trace.xml +++ b/xml/System.Diagnostics/Trace.xml @@ -44,9 +44,14 @@ ## Remarks You can use the properties and methods in the class to instrument release builds. Instrumentation allows you to monitor the health of your application running in real-life settings. Tracing helps you isolate problems and fix them without disturbing a running system. - This class provides methods to display an dialog box, and to emit an assertion that will always . This class provides write methods in the following variations: , , , and . + This class provides methods to display an dialog box, and to emit an assertion that will always . This class provides write methods in the following variations: + +- +- +- +- - The and classes provide means to dynamically control the tracing output. You can modify the values of these switches without recompiling your application. For information on using the configuration file to set a switch, see the class and the [How to: Create, Initialize and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches) topic. + The and classes provide means to dynamically control the tracing output. In .NET Framework apps, you can modify the values of these switches without recompiling your application. For information on using the configuration file to set a switch in a .NET Framework app, see the class and [How to: Create, Initialize, and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches). You can customize the tracing output's target by adding instances to or removing instances from the collection. The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. By default, trace output is emitted using the class. @@ -56,9 +61,9 @@ > [!NOTE] > If you add trace listeners to partially trusted code, you will get a exception, because adding trace listeners requires permission. To trace partially trusted code that is running in a sandbox in Visual Studio, do not add trace listeners. Instead, view the and messages in the **Output** window. - The class provides properties to get or set the level of , the , and whether to after each write. + The class provides properties to get or set the level of and the , and whether to after each write. - To set the and for , you can edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: +In .NET Framework apps, you can set the and for by editing the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: ```xml @@ -68,16 +73,14 @@ ``` - The attribute is applied to the methods of . Compilers that support ignore calls to these methods unless "TRACE" is defined as a conditional compilation symbol. Refer to a compiler's documentation to determine whether is supported and the syntax for defining a conditional compilation symbol. + The attribute is applied to the methods of . Compilers that support ignore calls to these methods unless `TRACE` is defined as a conditional compilation symbol. Refer to a compiler's documentation to determine whether is supported and the syntax for defining a conditional compilation symbol. > [!NOTE] -> In Visual Studio projects, by default, the "DEBUG" conditional compilation symbol is defined for debug builds, and the "TRACE" symbol is defined for both debug and release builds. For information about how to disable this behavior, see the Visual Studio documentation. +> In Visual Studio projects, by default, the `DEBUG` conditional compilation symbol is defined for debug builds, and the `TRACE` symbol is defined for both debug and release builds. - To define the "TRACE" conditional compilation symbol in C#, add the `/d:TRACE` option to the compiler command line when you compile your code using a command line, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` option to the compiler command line or add `#Const TRACE=True` to the file. + To define the `TRACE` conditional compilation symbol in C#, add the `/d:TRACE` option to the compiler command line when you compile your code using a command line, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` option to the compiler command line or add `#Const TRACE=True` to the file. - is not supported by the C++ compiler. To provide equivalent functionality, you must enclose calls to the methods of in an `#if defined(TRACE) ... #endif` block, and add the `/DTRACE` option to the compiler command line or add `#define TRACE` to the file. - - + is not supported by the C++ compiler. To provide equivalent functionality, you must enclose calls to the methods of in an `#if defined(TRACE) ... #endif` block, and add the `/DTRACE` option to the compiler command line or add `#define TRACE` to the file. ## Examples The following example uses to indicate the beginning and the end of a program's execution. The example also uses the and methods to distinguish the tracing output. For a more complete example of the use of , see [How to: Add Trace Statements to Application Code](/dotnet/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code). @@ -166,9 +169,9 @@ When the application runs in user-interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. + +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -180,9 +183,7 @@ -``` - - +``` ## Examples The following example creates an index for an array. Then some action is performed that sets the value of the index. Next the code calls to verify the index value is valid. If it is not valid, the outputs the call stack. @@ -261,9 +262,9 @@ When the application runs in user-interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. + +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -275,9 +276,7 @@ -``` - - +``` ## Examples The following example checks to see that the `type` parameter is valid. If the `type` passed in is `null`, the outputs a message. @@ -358,9 +357,9 @@ When the application runs in user-interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. + +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -372,9 +371,7 @@ -``` - - +``` ## Examples The following example checks to see that the `type` parameter is valid. If the `type` passed in is `null`, the outputs a message. @@ -439,7 +436,7 @@ Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. - To set the and for , you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: + To set the and for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: ```xml @@ -1011,7 +1008,7 @@ End of list of errors This property is stored on per-thread/per-request basis. - To set the and for , you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: + To set the and for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: ```xml @@ -1684,7 +1681,7 @@ End of list of errors ## Remarks The global lock is always used if the trace listener is not thread safe, regardless of the value of . The property is used to determine if the listener is thread safe. The global lock is not used only if the value of is `false` and the value of is `true`. The default behavior is to use the global lock. - To set the for , you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: + To set the for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: ```xml diff --git a/xml/System.Diagnostics/TraceLevel.xml b/xml/System.Diagnostics/TraceLevel.xml index 8b49f773a8f..2e74487f939 100644 --- a/xml/System.Diagnostics/TraceLevel.xml +++ b/xml/System.Diagnostics/TraceLevel.xml @@ -51,24 +51,7 @@ For more information on instrumenting your application, see and . -> [!NOTE] -> In the .NET Framework version 2.0, you can use text to specify the value for a switch. For example, `true` for a or the text representing an enumeration value such as `Error` for a . The line `` is equivalent to ``. - - In the .NET Framework versions 1.0 and 1.1, trace levels in configuration files are set using the integer value corresponding to the enumeration member, rather than the enumeration member itself, as the following example demonstrates. - -```xml - - - - - - - -``` - - In addition to setting trace levels using the integer value of the enumeration, the .NET Framework version 2.0 trace levels can be set using the text representation of the enumeration value. For example, `Verbose` for a . The line `` is equivalent to ``. - - The following table shows the relationship between the enumeration members and their corresponding configuration file entries. +In .NET Framework app configuration files, you can use text to specify the value for a switch. For example, `true` for a , or the text representing an enumeration value such as `Error` for a . The line `` is equivalent to ``. You can also set trace levels using the integer value of the enumeration. The following table shows the relationship between the enumeration members and their corresponding configuration file entries. |Trace Level|Configuration File Value| |-----------------|------------------------------| diff --git a/xml/System.Diagnostics/TraceOptions.xml b/xml/System.Diagnostics/TraceOptions.xml index ae8c4e79656..0eb7b971b8d 100644 --- a/xml/System.Diagnostics/TraceOptions.xml +++ b/xml/System.Diagnostics/TraceOptions.xml @@ -48,7 +48,7 @@ ## Remarks This enumeration is used by trace listeners to determine which options, or elements, should be included in the trace output. Trace listeners store the trace options in the property. - The following example shows the use of the `traceOutputOptions` attribute to specify the trace output options for a that is enabled using a configuration file. + The following example shows the use of the `traceOutputOptions` attribute to specify the trace output options for a . Using a configuration file like this is only possible in .NET Framework apps. ```xml @@ -64,7 +64,7 @@ ``` - For details about adding trace listeners to the application configuration file, see [<listeners>](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-trace). + For details about adding trace listeners to the application configuration file, see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-trace). The enumeration is not used by the following classes and methods: @@ -72,9 +72,7 @@ - The `Write` and `WriteLine` methods of the , , and classes. -- The and methods of the class when they are not overridden in a derived class. - - +- The and methods of the class when they are not overridden in a derived class. ## Examples The following code example shows the use of the enumeration to programmatically set the property for a console trace listener. The console trace listener is one of the listeners enumerated in the property of a trace source. This code example is part of a larger example provided for the class. diff --git a/xml/System.Diagnostics/TraceSource.xml b/xml/System.Diagnostics/TraceSource.xml index d21d11a66b5..8fdf3790ff9 100644 --- a/xml/System.Diagnostics/TraceSource.xml +++ b/xml/System.Diagnostics/TraceSource.xml @@ -41,7 +41,9 @@ class is used by applications to produce traces that can be associated with the application. provides tracing methods that allow you to easily trace events, trace data, and issue informational traces. Trace output from can be controlled by configuration file settings. The configuration file is located in the folder with the application executable and has the name of the application with the .config file name extension added. For example, the name of the configuration file for TraceSourceSample.exe is TraceSourceSample.exe.config. The configuration file can be used to determine where the trace information is to be sent and what levels of activity are to be traced. The following example shows the contents of a sample application configuration file. + The class is used by applications to produce traces that can be associated with the application. provides tracing methods that allow you to easily trace events, trace data, and issue informational traces. + +In .NET Framework apps, trace output from can be controlled by configuration file settings. The configuration file is located in the folder with the application executable and has the name of the application with the .config extension added. For example, the name of the configuration file for TraceSourceSample.exe is TraceSourceSample.exe.config. The configuration file can be used to specify where the trace information is to be sent and what levels of activity are to be traced. The following example shows the contents of a sample .NET Framework application configuration file. ```xml @@ -82,21 +84,23 @@ > [!NOTE] > You should not call the tracing methods during finalization. Doing so can result in an being thrown. - You can customize the tracing output's target by adding or removing instances to or from the collection stored in the property. By default, trace output is produced using an instance of the class. The preceding configuration file example demonstrates removing the and adding a to produce the trace output for the trace source. For more information, see [<listeners>](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-source) and [<sharedListeners>](/dotnet/framework/configure-apps/file-schema/trace-debug/sharedlisteners-element). + You can customize the tracing output's target by adding or removing instances to or from the collection stored in the property. By default, trace output is produced using an instance of the class. + +The preceding .NET Framework app configuration file example demonstrates removing the and adding a to produce the trace output for the trace source. For more information, see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-source) and [\](/dotnet/framework/configure-apps/file-schema/trace-debug/sharedlisteners-element). > [!NOTE] > Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. - The class provides the means to dynamically control the tracing output. The preceding configuration file example shows how you can turn off tracing from a trace source and control the level at which tracing occurs. You can modify the value of the source switch without recompiling your application. For information on using the configuration file to set a switch, see and [How to: Create, Initialize and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches). + The class provides the means to dynamically control the tracing output. For .NET Framework apps, the preceding configuration file example shows how you can turn off tracing from a trace source and control the level at which tracing occurs. You can modify the value of the source switch without recompiling your application. For information on using the configuration file to set a switch, see and [How to: Create, Initialize and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches). > [!NOTE] > If you modify a configuration file while an application is executing, the application must be stopped and restarted or the method must be called before the new settings take effect. The enumeration is used to define the event type of the trace message. Trace filters use the to determine if a trace listener should produce the trace message. - The trace listeners can optionally have an additional layer of filtering through a trace filter. If a trace listener has an associated filter, the listener calls the method on that filter to determine whether or not to produce the trace information. + The trace listeners can optionally have an additional layer of filtering through a trace filter. If a trace listener has an associated filter, the listener calls the method on that filter to determine whether or not to produce the trace information. - The trace listeners use the values of the class properties , , and to format trace output. You can use configuration file attributes to set the , , and properties. The following example sets the property to `false` and the property to 3. + The trace listeners use the values of the class properties , , and to format trace output. In .NET Framework apps, you can use configuration file attributes to set the , , and properties. The following example sets the property to `false` and the property to 3. ```xml @@ -104,9 +108,7 @@ -``` - - +``` ## Examples The following code example shows the use of the class to forward traces to listeners. The example also demonstrates switch and filter usage. @@ -572,9 +574,9 @@ @@ -585,12 +587,10 @@ -``` - - +``` ## Examples - The following code sample shows how to name a trace source in the constructor call. This code example is part of a larger example provided for the class. + The following code sample shows how to name a trace source in the constructor call. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource2/VB/program.vb" id="Snippet9"::: diff --git a/xml/System.Diagnostics/TraceSwitch.xml b/xml/System.Diagnostics/TraceSwitch.xml index c952ed06c53..d83e831e6e7 100644 --- a/xml/System.Diagnostics/TraceSwitch.xml +++ b/xml/System.Diagnostics/TraceSwitch.xml @@ -48,11 +48,11 @@ class provides the , , , and properties to test the level of the switch. The property gets or sets the switch's . - - You can set the level of a through the application configuration file and then use the configured level in your application. Alternately, you can create a in your code and set the level directly to instrument a specific section of code. - - To configure a , edit the configuration file for your application. In this file, you can add or remove a switch, set a switch's value, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: + You can use a trace switch to filter out messages based on their importance. The class provides the , , , and properties to test the level of the switch. The property gets or sets the switch's . + +You can create a in your code and set the level directly to instrument a specific section of code. + +In .NET Framework apps only, you can also set the level of a through the application configuration file and then use the configured level in your application. In the application configuration file, you can add or remove a switch, set a switch's value, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: ```xml @@ -67,31 +67,31 @@ This configuration section defines a with the set to `mySwitch`, and the set to 1, which corresponds to the enumeration value . > [!NOTE] -> In the .NET Framework version 2.0, you can use text to specify the value for a switch. For example, `true` for a or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. +> You can also use text to specify the value for a switch. For example, `true` for a , or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. In your application, you can use the configured switch level by creating a with the same name, as shown in the following example: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CPP/remarks.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/remarks.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/VB/remarks.vb" id="Snippet3"::: - - By default, the switch property is set using the value specified in the configuration file. If the constructor cannot find initial switch settings in the configuration file, the of the new switch defaults to . + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/VB/remarks.vb" id="Snippet3"::: + +In .NET Core and .NET 5+ apps, the of the new switch defaults to . + +In .NET Framework apps, the switch property defaults to the value specified in the configuration file. If the constructor cannot find initial switch settings in the configuration file, of the new switch defaults to . You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. -- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. +- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. -- To enable tracing in C#, add the `/d:TRACE` flag to the compiler command line when you compile your code, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` flag to the compiler command line. +- To enable tracing in C#, add the `/d:TRACE` flag to the compiler command line when you compile your code, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` flag to the compiler command line. > [!NOTE] -> These debug and trace compiler switches are not required when using the class in isolation. They are only required in conjunction with or methods that are conditionally compiled. +> These debug and trace compiler switches are not required when using the class in isolation. They are only required in conjunction with or methods that are conditionally compiled. For more information on instrumenting your application, see and . For more information about configuring and using trace switches, see [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches). > [!NOTE] -> To improve performance, you can make members `static` in your class. - - +> To improve performance, you can make members `static` in your class. ## Examples The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . @@ -168,7 +168,8 @@ , edit the configuration file that corresponds to the name of your application. In this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: + +For .NET Framework apps, to set the level of your , edit the configuration file that corresponds to the name of your application. In this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: ```xml @@ -180,23 +181,20 @@ ``` -> [!NOTE] -> In the .NET Framework version 2.0, you can use text to specify the value for a switch. For example, `true` for a or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. +You can also use text to specify the value for a switch. For example, `true` for a or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. In your application, you can use the configured switch level by creating a with the same name, as shown in the following example: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CPP/remarks.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/remarks.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/VB/remarks.vb" id="Snippet3"::: - - When the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to . + +This constructor sets the property of the new switch to . Or, for .NET Framework apps, the switch settings are obtained from the configuration file, if available. The class provides the , , , and properties to test the of the switch. The property gets or sets the switch's . > [!NOTE] -> To improve performance, you can make members `static` in your class. - - +> To improve performance, you can make members `static` in your class. ## Examples The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . @@ -310,7 +308,8 @@ , edit the configuration file that corresponds to the name of your application. In this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: + +For .NET Framework apps, to set the level of your , edit the configuration file that corresponds to the name of your application. In this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: ```xml @@ -325,14 +324,11 @@ ``` -> [!NOTE] -> In the .NET Framework version 2.0, you can use text to specify the value for a switch. For example, `true` for a or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. - - When the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to . +You can also use text to specify the value for a switch. For example, `true` for a or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. - Setting this property updates the , , , and properties to reflect the new value. +The default value of the property is . Or, for .NET Framework apps, the level is obtained from the configuration file, if available. - + Setting this property updates the , , , and properties to reflect the new value. ## Examples The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . diff --git a/xml/System.Diagnostics/XmlWriterTraceListener.xml b/xml/System.Diagnostics/XmlWriterTraceListener.xml index 6122cc6bd8a..84784fa2969 100644 --- a/xml/System.Diagnostics/XmlWriterTraceListener.xml +++ b/xml/System.Diagnostics/XmlWriterTraceListener.xml @@ -33,10 +33,8 @@ > 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 enable or disable an through the application configuration file and then use the configured in your application. Alternately, you can create an in your code. - - 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. + +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 @@ -54,7 +52,7 @@ ``` - 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. + 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. @@ -94,9 +92,7 @@ |"|"| |\|'| |0xD|&\#xD;| -|0xA|&\#xA;| - - +|0xA|&\#xA;| ## Examples The following code example shows the use of the class to write both escaped and non-escaped data to file logs. From d09a2f33861cf819630ba6cc61e0b62b61ee3ab6 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 20 Apr 2022 16:38:35 -0700 Subject: [PATCH 2/2] small tweak --- xml/System.Diagnostics/BooleanSwitch.xml | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/xml/System.Diagnostics/BooleanSwitch.xml b/xml/System.Diagnostics/BooleanSwitch.xml index 53a97229183..af91ce67579 100644 --- a/xml/System.Diagnostics/BooleanSwitch.xml +++ b/xml/System.Diagnostics/BooleanSwitch.xml @@ -72,7 +72,7 @@ For .NET Framework apps only, you can also enable or disable a property of the new switch is set to `false` by default. -For .NET Framework apps, the property is set using the value specified in the configuration file. Configure the switch with a value of 0 to set the property to `false`; configure the switch with a nonzero value to set the property to `true`. If the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to `false` by default. +For .NET Framework apps, the property is set using the value specified in the configuration file. Configure the switch with a value of 0 to set the property to `false`; configure the switch with a nonzero value to set the property to `true`. If the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to `false`. You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -162,7 +162,7 @@ For .NET Framework apps, the , the `displayName` parameter is used to find initial switch settings for .NET Framework apps. If the constructor cannot find initial settings, or for .NET Core and .NET 5+ apps, the property is set to `false` (disabled). + When you create a , the `displayName` parameter is used to find the initial switch settings for .NET Framework apps in the application configuration file. If the constructor cannot find initial settings, or for .NET Core and .NET 5+ apps, the property is set to `false` (disabled). To set the level of your in a .NET Framework app, edit the configuration file corresponding to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all switches previously set by the application. The configuration file should be formatted like the following example: @@ -243,14 +243,7 @@ For .NET Framework apps, the The description of the switch. The default value of the switch. Initializes a new instance of the class with the specified display name, description, and default switch value. - - property, and the `description` parameter is use to set the value of the property. The `defaultSwitchValue` parameter is saved as a field and used to initialize the property on first reference. For more information about constructor use, see the constructor. - - ]]> - + To be added.