Skip to content

Config files are .NET Framework only (System.Diagnostics) #7979

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 21, 2022
Merged

Config files are .NET Framework only (System.Diagnostics) #7979

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7215959
config files are .net framework only
gewarren Apr 20, 2022
d09a2f3
small tweak
gewarren Apr 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 13 additions & 22 deletions xml/System.Diagnostics/BooleanSwitch.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,9 @@
## Remarks
You can use a Boolean trace switch to enable or disable messages based on their importance. Use the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property to get the current value of the switch.

You can enable or disable a <xref:System.Diagnostics.BooleanSwitch> through the application configuration file and then use the configured <xref:System.Diagnostics.BooleanSwitch> value in your application. Alternately, you can create a <xref:System.Diagnostics.BooleanSwitch> in your code and set the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property directly to instrument a specific section of code.
To configure a <xref:System.Diagnostics.BooleanSwitch>, 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 <xref:System.Diagnostics.BooleanSwitch> in your code and set the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property directly to instrument a specific section of code.

For .NET Framework apps only, you can also enable or disable a <xref:System.Diagnostics.BooleanSwitch> through the application configuration file and then use the configured <xref:System.Diagnostics.BooleanSwitch> value in your application. To configure a <xref:System.Diagnostics.BooleanSwitch>, 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
<configuration>
Expand All @@ -64,13 +64,15 @@
</configuration>
```

This example configuration section defines a <xref:System.Diagnostics.BooleanSwitch> with the <xref:System.Diagnostics.Switch.DisplayName%2A> property set to `mySwitch` and the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> value set to `true`. Within your application, you can use the configured switch value by creating a <xref:System.Diagnostics.BooleanSwitch> with the same name, as shown in the following code example.
This example configuration section defines a <xref:System.Diagnostics.BooleanSwitch> with the <xref:System.Diagnostics.Switch.DisplayName%2A> property set to `mySwitch` and the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> value set to `true`. Within your .NET Framework application, you can use the configured switch value by creating a <xref:System.Diagnostics.BooleanSwitch> 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 <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property is set using the value specified in the configuration file. Configure the switch with a value of 0 to set the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property to `false`; configure the switch with a nonzero value to set the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property to `true`. If the <xref:System.Diagnostics.BooleanSwitch> constructor cannot find initial switch settings in the configuration file, the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property of the new switch is set to `false` by default.

For .NET Core and .NET 5+ apps, the <xref:System.Diagnostics.BooleanSwitch.Enabled> property of the new switch is set to `false` by default.

For .NET Framework apps, the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property is set using the value specified in the configuration file. Configure the switch with a value of 0 to set the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property to `false`; configure the switch with a nonzero value to set the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property to `true`. If the <xref:System.Diagnostics.BooleanSwitch> constructor cannot find initial switch settings in the configuration file, the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> 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.

Expand All @@ -84,9 +86,7 @@
For more information on instrumenting your application, see <xref:System.Diagnostics.Debug> and <xref:System.Diagnostics.Trace>. 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 <xref:System.Diagnostics.BooleanSwitch> members `static` in your class.


> To improve performance, you can make <xref:System.Diagnostics.BooleanSwitch> members `static` in your class.

## Examples
The following example creates a <xref:System.Diagnostics.BooleanSwitch> 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.
Expand Down Expand Up @@ -162,9 +162,9 @@
<format type="text/markdown"><![CDATA[

## Remarks
When you create a <xref:System.Diagnostics.BooleanSwitch>, the `displayName` parameter is used to find initial switch settings. If the constructor cannot find initial settings, the <xref:System.Diagnostics.BooleanSwitch.Enabled%2A> property is set to `false` (disabled).
When you create a <xref:System.Diagnostics.BooleanSwitch>, 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 <xref:System.Diagnostics.BooleanSwitch.Enabled> property is set to `false` (disabled).

To set the level of your <xref:System.Diagnostics.BooleanSwitch>, 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 <xref:System.Diagnostics.BooleanSwitch> 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
<configuration>
Expand All @@ -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 <xref:System.Diagnostics.BooleanSwitch> 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.
Expand Down Expand Up @@ -245,14 +243,7 @@
<param name="description">The description of the switch.</param>
<param name="defaultSwitchValue">The default value of the switch.</param>
<summary>Initializes a new instance of the <see cref="T:System.Diagnostics.BooleanSwitch" /> class with the specified display name, description, and default switch value.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The `displayName` parameter is used to set the value of the <xref:System.Diagnostics.Switch.DisplayName%2A> property, and the `description` parameter is use to set the value of the <xref:System.Diagnostics.Switch.Description%2A> property. The `defaultSwitchValue` parameter is saved as a field and used to initialize the <xref:System.Diagnostics.Switch.Value%2A> property on first reference. For more information about constructor use, see the <xref:System.Diagnostics.BooleanSwitch.%23ctor%28System.String%2CSystem.String%29> constructor.

]]></format>
</remarks>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="Enabled">
Expand Down
16 changes: 6 additions & 10 deletions xml/System.Diagnostics/ConsoleTraceListener.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,12 @@
Use the <xref:System.Diagnostics.ConsoleTraceListener> class to write trace and debugging messages to the console. You can initialize a <xref:System.Diagnostics.ConsoleTraceListener> object to write trace messages to the <xref:System.Console.Out%2A?displayProperty=nameWithType> stream or to the <xref:System.Console.Error%2A?displayProperty=nameWithType> stream.

> [!IMPORTANT]
> <xref:System.IDisposable> 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 <xref:System.IDisposable.Dispose%2A> 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 <xref:System.IDisposable> interface topic.
> This type implements the <xref:System.IDisposable> 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 <xref:System.IDisposable.Dispose%2A> 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 <xref:System.IDisposable> interface topic.

When trace and debugging output is enabled, the <xref:System.Diagnostics.ConsoleTraceListener> messages are written to the specified <xref:System.Console?displayProperty=nameWithType> stream, which is similar to the way messages are written with the <xref:System.Console.Write%2A?displayProperty=nameWithType> or <xref:System.Console.WriteLine%2A?displayProperty=nameWithType> methods. In a console application, the <xref:System.Console?displayProperty=nameWithType> output and error streams write messages to the existing console window, or you can redirect the streams to write to a <xref:System.IO.TextWriter?displayProperty=nameWithType> 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 <xref:System.Diagnostics.ConsoleTraceListener> object to the appropriate <xref:System.Diagnostics.Trace.Listeners%2A> collection if you want messages written through <xref:System.Diagnostics.Trace>, <xref:System.Diagnostics.TraceSource>, or <xref:System.Diagnostics.Debug> to be written to the console. In addition, you can write messages directly to the console using the <xref:System.Diagnostics.Trace.Write%2A?displayProperty=nameWithType> or <xref:System.Diagnostics.Trace.WriteLine%2A?displayProperty=nameWithType> methods.

Expand All @@ -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 <xref:System.Diagnostics.ConsoleTraceListener> object to the <xref:System.Diagnostics.Trace.Listeners%2A> collection in your code, or you can add a <xref:System.Diagnostics.ConsoleTraceListener> object to the <xref:System.Diagnostics.Trace.Listeners%2A> collection through the application configuration file. Add the <xref:System.Diagnostics.ConsoleTraceListener> object in your code to write messages for a specific code section or execution path. Add the <xref:System.Diagnostics.ConsoleTraceListener> object in your application configuration file to direct all trace and debug messages to the console while the application executes.
You can add a <xref:System.Diagnostics.ConsoleTraceListener> object to the <xref:System.Diagnostics.Trace.Listeners%2A> collection in your code. Or, for .NET Framework apps, you can add a <xref:System.Diagnostics.ConsoleTraceListener> object to the <xref:System.Diagnostics.Trace.Listeners%2A> collection through the application configuration file. Add the <xref:System.Diagnostics.ConsoleTraceListener> object in your code to write messages for a specific code section or execution path. Add the <xref:System.Diagnostics.ConsoleTraceListener> 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 <xref:System.Diagnostics.ConsoleTraceListener> object and add it to the <xref:System.Diagnostics.Trace.Listeners%2A> collection. Instrument the section of code that contains messages using the <xref:System.Diagnostics.Trace> or <xref:System.Diagnostics.Debug> classes. At the end of the code section, remove the <xref:System.Diagnostics.ConsoleTraceListener> object from the <xref:System.Diagnostics.Trace.Listeners%2A> collection, and call the <xref:System.Diagnostics.TextWriterTraceListener.Close%2A> method on the <xref:System.Diagnostics.ConsoleTraceListener>.

To direct all trace and debug messages to the console while the application executes, add a <xref:System.Diagnostics.ConsoleTraceListener> 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 <xref:System.Diagnostics.ConsoleTraceListener>.

The following example adds a <xref:System.Diagnostics.ConsoleTraceListener> object named `configConsoleListener` to the <xref:System.Diagnostics.Trace.Listeners%2A> collection.
For .NET Framework apps, to direct all trace and debug messages to the console while the application executes, add a <xref:System.Diagnostics.ConsoleTraceListener> object to the application configuration file. The following example adds a <xref:System.Diagnostics.ConsoleTraceListener> object named `configConsoleListener` to the <xref:System.Diagnostics.Trace.Listeners%2A> collection.

```xml
<configuration>
<system.diagnostics>
<trace autoflush="false" indentsize="4">
<listeners>
<add name="configConsoleListener" type="System.Diagnostics.ConsoleTraceListener" />
<add name="configConsoleListener" type="System.Diagnostics.ConsoleTraceListener" />
</listeners>
</trace>
</system.diagnostics>
</configuration>
```

For details about adding trace listeners in the application configuration file, see [&lt;listeners&gt;](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-trace).


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

## Examples
The following code example implements a console application consisting of a class with two public methods.
Expand Down
Loading