Jo Shields a575963da9 Imported Upstream version 3.6.0
Former-commit-id: da6be194a6b1221998fc28233f2503bd61dd9d14
2014-08-13 10:39:27 +01:00

328 lines
24 KiB
XML

<?xml version="1.0" encoding="utf-8"?>
<Type Name="TraceSwitch" FullName="System.Diagnostics.TraceSwitch">
<TypeSignature Language="C#" Value="public class TraceSwitch : System.Diagnostics.Switch" Maintainer="auto" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi beforefieldinit TraceSwitch extends System.Diagnostics.Switch" />
<AssemblyInfo>
<AssemblyName>System</AssemblyName>
<AssemblyPublicKey>[00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00]</AssemblyPublicKey>
<AssemblyVersion>1.0.3300.0</AssemblyVersion>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the &lt;link location="node:gtk-sharp/programming/threads"&gt;Gtk# Thread Programming&lt;/link&gt; for details.</ThreadSafetyStatement>
<Base>
<BaseTypeName>System.Diagnostics.Switch</BaseTypeName>
</Base>
<Interfaces />
<Attributes>
<Attribute>
<AttributeName>System.Diagnostics.SwitchLevel(typeof(System.Diagnostics.TraceLevel))</AttributeName>
</Attribute>
</Attributes>
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>You can use a trace switch to filter out messages based on their importance. The <see cref="T:System.Diagnostics.TraceSwitch" /> class provides the <see cref="P:System.Diagnostics.TraceSwitch.TraceError" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceWarning" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceInfo" />, and <see cref="P:System.Diagnostics.TraceSwitch.TraceVerbose" /> properties to test the level of the switch. The <see cref="P:System.Diagnostics.TraceSwitch.Level" /> property gets or sets the switch's <see cref="T:System.Diagnostics.TraceLevel" />.</para>
<para>You can set the level of a <see cref="T:System.Diagnostics.TraceSwitch" /> through the application configuration file and then use the configured <see cref="T:System.Diagnostics.TraceSwitch" /> level in your application. Alternately, you can create a <see cref="T:System.Diagnostics.TraceSwitch" /> in your code and set the level directly to instrument a specific section of code.</para>
<para>To configure a <see cref="T:System.Diagnostics.TraceSwitch" />, edit the <format type="text/html"><a href="86bd26d3-737e-4484-9782-19b17f34cd1f">configuration file</a></format> 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: </para>
<code>&lt;configuration&gt;
&lt;system.diagnostics&gt;
&lt;switches&gt;
&lt;add name="mySwitch" value="1" /&gt;
&lt;/switches&gt;
&lt;/system.diagnostics&gt;
&lt;/configuration&gt;</code>
<para>This configuration section defines a <see cref="T:System.Diagnostics.TraceSwitch" /> with the <see cref="P:System.Diagnostics.Switch.DisplayName" /> set to mySwitch, and the <see cref="P:System.Diagnostics.TraceSwitch.Level" /> set to 1, which corresponds to the enumeration value <see cref="F:System.Diagnostics.TraceLevel.Error" />. </para>
<block subset="none" type="note">
<para>In the .NET Framework version 2.0, you can use text to specify the value for a switch. For example, true for a <see cref="T:System.Diagnostics.BooleanSwitch" /> or the text representing an enumeration value, such as Error for a <see cref="T:System.Diagnostics.TraceSwitch" />. The line &lt;add name="mySwitch" value="Error" /&gt; is equivalent to &lt;add name="mySwitch" value="1" /&gt;.</para>
</block>
<para> In your application, you can use the configured switch level by creating a <see cref="T:System.Diagnostics.TraceSwitch" /> with the same name, as shown in the following example:</para>
<para>code reference: Classic TraceSwitch.TraceError Example#3</para>
<para>By default, the switch <see cref="P:System.Diagnostics.TraceSwitch.Level" /> property is set using the value specified in the configuration file. If the <see cref="Overload:System.Diagnostics.TraceSwitch.#ctor" /> constructor cannot find initial switch settings in the configuration file, the <see cref="P:System.Diagnostics.TraceSwitch.Level" /> of the new switch defaults to <see cref="F:System.Diagnostics.TraceLevel.Off" />.</para>
<para>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.</para>
<list type="bullet">
<item>
<para>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.</para>
</item>
<item>
<para>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.</para>
</item>
</list>
<block subset="none" type="note">
<para>These debug and trace compiler switches are not required when using the <see cref="T:System.Diagnostics.TraceSwitch" /> class in isolation. They are only required in conjunction with <see cref="T:System.Diagnostics.Trace" /> or <see cref="T:System.Diagnostics.Debug" /> methods that are conditionally compiled.</para>
</block>
<para>For more information on instrumenting your application, see <see cref="T:System.Diagnostics.Debug" /> and <see cref="T:System.Diagnostics.Trace" />. For more information about configuring and using trace switches, see <format type="text/html"><a href="8ab913aa-f400-4406-9436-f45bc6e54fbe">Trace Switches</a></format>.</para>
<block subset="none" type="note">
<para>To improve performance, you can make <see cref="T:System.Diagnostics.TraceSwitch" /> members static in your class.</para>
</block>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Provides a multilevel switch to control tracing and debug output without recompiling your code.</para>
</summary>
</Docs>
<Members>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public TraceSwitch (string displayName, string description);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string displayName, string description) cil managed" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue />
<Parameters>
<Parameter Name="displayName" Type="System.String" />
<Parameter Name="description" Type="System.String" />
</Parameters>
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>To set the level of your <see cref="T:System.Diagnostics.TraceSwitch" />, 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: </para>
<code>&lt;configuration&gt;
&lt;system.diagnostics&gt;
&lt;switches&gt;
&lt;add name="mySwitch" value="1" /&gt;
&lt;/switches&gt;
&lt;/system.diagnostics&gt;
&lt;/configuration&gt;</code>
<block subset="none" type="note">
<para>In the .NET Framework version 2.0, you can use text to specify the value for a switch. For example, true for a <see cref="T:System.Diagnostics.BooleanSwitch" /> or the text representing an enumeration value, such as Error for a <see cref="T:System.Diagnostics.TraceSwitch" />. The line &lt;add name="mySwitch" value="Error" /&gt; is equivalent to &lt;add name="mySwitch" value="1" /&gt;.</para>
</block>
<para>In your application, you can use the configured switch level by creating a <see cref="T:System.Diagnostics.TraceSwitch" /> with the same name, as shown in the following example:</para>
<para>code reference: Classic TraceSwitch.TraceError Example#3</para>
<para>When the <see cref="Overload:System.Diagnostics.TraceSwitch.#ctor" /> constructor cannot find initial switch settings in the configuration file, the <see cref="P:System.Diagnostics.TraceSwitch.Level" /> property of the new switch is set to <see cref="F:System.Diagnostics.TraceLevel.Off" />.</para>
<para>The <see cref="T:System.Diagnostics.TraceSwitch" /> class provides the <see cref="P:System.Diagnostics.TraceSwitch.TraceError" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceWarning" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceInfo" />, and <see cref="P:System.Diagnostics.TraceSwitch.TraceVerbose" /> properties to test the <see cref="P:System.Diagnostics.TraceSwitch.Level" /> of the switch. The <see cref="P:System.Diagnostics.TraceSwitch.Level" /> property gets or sets the switch's <see cref="T:System.Diagnostics.TraceLevel" />.</para>
<block subset="none" type="note">
<para>To improve performance, you can make <see cref="T:System.Diagnostics.TraceSwitch" /> members static in your class.</para>
</block>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Initializes a new instance of the <see cref="T:System.Diagnostics.TraceSwitch" /> class, using the specified display name and description.</para>
</summary>
<param name="displayName">
<attribution license="cc4" from="Microsoft" modified="false" />The name to display on a user interface. </param>
<param name="description">
<attribution license="cc4" from="Microsoft" modified="false" />The description of the switch. </param>
</Docs>
</Member>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public TraceSwitch (string displayName, string description, string defaultSwitchValue);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string displayName, string description, string defaultSwitchValue) cil managed" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters>
<Parameter Name="displayName" Type="System.String" />
<Parameter Name="description" Type="System.String" />
<Parameter Name="defaultSwitchValue" Type="System.String" />
</Parameters>
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>The <paramref name="displayName" /> parameter is used to set the value of the <see cref="P:System.Diagnostics.Switch.DisplayName" /> property, the <paramref name="description" /> parameter is use to set the value of the <see cref="P:System.Diagnostics.Switch.Description" /> property, and the <paramref name="defaultSwitchValue" /> parameter is saved as a field and used to initialize the <see cref="P:System.Diagnostics.Switch.Value" /> property on first reference. See the <see cref="M:System.Diagnostics.TraceSwitch.#ctor(System.String,System.String)" /> constructor for more information and a code example.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Initializes a new instance of the <see cref="T:System.Diagnostics.TraceSwitch" /> class, using the specified display name, description, and default value for the switch. </para>
</summary>
<param name="displayName">
<attribution license="cc4" from="Microsoft" modified="false" />The name to display on a user interface. </param>
<param name="description">
<attribution license="cc4" from="Microsoft" modified="false" />The description of the switch. </param>
<param name="defaultSwitchValue">
<attribution license="cc4" from="Microsoft" modified="false" />The default value of the switch.</param>
</Docs>
</Member>
<Member MemberName="Level">
<MemberSignature Language="C#" Value="public System.Diagnostics.TraceLevel Level { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance valuetype System.Diagnostics.TraceLevel Level" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Diagnostics.TraceLevel</ReturnType>
</ReturnValue>
<Parameters>
</Parameters>
<Docs>
<value>To be added: an object of type 'TraceLevel'</value>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>To set the level of your <see cref="T:System.Diagnostics.TraceSwitch" />, 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: </para>
<code>&lt;configuration&gt;
&lt;system.diagnostics&gt;
&lt;switches&gt;
&lt;add name="mySwitch" value="0" /&gt;
&lt;add name="myNewSwitch" value="3" /&gt;
&lt;remove name="mySwitch" /&gt;
&lt;clear/&gt;
&lt;/switches&gt;
&lt;/system.diagnostics&gt;
&lt;/configuration&gt;</code>
<block subset="none" type="note">
<para>In the .NET Framework version 2.0, you can use text to specify the value for a switch. For example, true for a <see cref="T:System.Diagnostics.BooleanSwitch" /> or the text representing an enumeration value, such as Error for a <see cref="T:System.Diagnostics.TraceSwitch" />. The line &lt;add name="mySwitch" value="Error" /&gt; is equivalent to &lt;add name="mySwitch" value="1" /&gt;.</para>
</block>
<para>When the <see cref="Overload:System.Diagnostics.TraceSwitch.#ctor" /> constructor cannot find initial switch settings in the configuration file, the <see cref="P:System.Diagnostics.TraceSwitch.Level" /> property of the new switch is set to <see cref="F:System.Diagnostics.TraceLevel.Off" />.</para>
<para>Setting this property updates the <see cref="P:System.Diagnostics.TraceSwitch.TraceError" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceWarning" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceInfo" />, and <see cref="P:System.Diagnostics.TraceSwitch.TraceVerbose" /> properties to reflect the new value.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Gets or sets the trace level that determines the messages the switch allows.</para>
</summary>
</Docs>
</Member>
<Member MemberName="OnSwitchSettingChanged">
<MemberSignature Language="C#" Value="protected override void OnSwitchSettingChanged ();" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig virtual instance void OnSwitchSettingChanged() cil managed" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>The <see cref="M:System.Diagnostics.TraceSwitch.OnSwitchSettingChanged" /> method is used by the .NET framework to validate and correct the value of a switch initialized via a configuration file. A message is written to all trace listeners if the switch value specified in the configuration file is not defined by the <see cref="T:System.Diagnostics.TraceLevel" /> enumeration and the switch is set to a defined value.</para>
<para>If you attempt in your code to set the <see cref="P:System.Diagnostics.TraceSwitch.Level" /> property to a value that is not defined by the <see cref="T:System.Diagnostics.TraceLevel" /> enumeration, an <see cref="T:System.ArgumentException" /> exception is thrown.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Updates and corrects the level for this switch.</para>
</summary>
</Docs>
</Member>
<Member MemberName="OnValueChanged">
<MemberSignature Language="C#" Value="protected override void OnValueChanged ();" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig virtual instance void OnValueChanged() cil managed" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>This method is called internally when the <see cref="P:System.Diagnostics.Switch.Value" /> property of the switch changes. The method ensures that the properties relating to the switch's value reflect the new value.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Sets the <see cref="P:System.Diagnostics.Switch.SwitchSetting" /> property to the integer equivalent of the <see cref="P:System.Diagnostics.Switch.Value" /> property.</para>
</summary>
</Docs>
</Member>
<Member MemberName="TraceError">
<MemberSignature Language="C#" Value="public bool TraceError { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool TraceError" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<value>To be added: an object of type 'bool'</value>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>You can use the <see cref="P:System.Diagnostics.TraceSwitch.TraceError" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceWarning" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceInfo" />, and <see cref="P:System.Diagnostics.TraceSwitch.TraceVerbose" /> properties in conjunction with the <see cref="T:System.Diagnostics.Debug" /> and <see cref="T:System.Diagnostics.Trace" /> classes to emit all messages with a specified importance or greater. When the <see cref="P:System.Diagnostics.TraceSwitch.Level" /> property is set to the highest importance, <see cref="F:System.Diagnostics.TraceLevel.Error" />, <see cref="F:System.Diagnostics.TraceLevel.Error" /> , only error-handling messages are emitted.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Gets a value indicating whether the switch allows error-handling messages.</para>
</summary>
</Docs>
</Member>
<Member MemberName="TraceInfo">
<MemberSignature Language="C#" Value="public bool TraceInfo { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool TraceInfo" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<value>To be added: an object of type 'bool'</value>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>You can use the <see cref="P:System.Diagnostics.TraceSwitch.TraceError" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceWarning" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceInfo" />, and <see cref="P:System.Diagnostics.TraceSwitch.TraceVerbose" /> properties in conjunction with the <see cref="T:System.Diagnostics.Debug" /> and <see cref="T:System.Diagnostics.Trace" /> classes to emit all messages with a specified importance or greater. When the <see cref="P:System.Diagnostics.TraceSwitch.Level" /> property is set to <see cref="F:System.Diagnostics.TraceLevel.Warning" />, informational messages, warnings, and error-handling messages are emitted.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Gets a value indicating whether the switch allows informational messages.</para>
</summary>
</Docs>
</Member>
<Member MemberName="TraceVerbose">
<MemberSignature Language="C#" Value="public bool TraceVerbose { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool TraceVerbose" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<value>To be added: an object of type 'bool'</value>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>You can use the <see cref="P:System.Diagnostics.TraceSwitch.TraceError" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceWarning" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceInfo" />, and <see cref="P:System.Diagnostics.TraceSwitch.TraceVerbose" /> properties in conjunction with the <see cref="T:System.Diagnostics.Debug" /> and <see cref="T:System.Diagnostics.Trace" /> classes to emit all messages with a specified importance or greater. When the <see cref="P:System.Diagnostics.TraceSwitch.Level" /> property is set to <see cref="F:System.Diagnostics.TraceLevel.Verbose" />, all debugging and tracing messages are transmitted.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Gets a value indicating whether the switch allows all messages.</para>
</summary>
</Docs>
</Member>
<Member MemberName="TraceWarning">
<MemberSignature Language="C#" Value="public bool TraceWarning { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool TraceWarning" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<value>To be added: an object of type 'bool'</value>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>You can use the <see cref="P:System.Diagnostics.TraceSwitch.TraceError" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceWarning" />, <see cref="P:System.Diagnostics.TraceSwitch.TraceInfo" />, and <see cref="P:System.Diagnostics.TraceSwitch.TraceVerbose" /> properties in conjunction with the <see cref="T:System.Diagnostics.Debug" /> and <see cref="T:System.Diagnostics.Trace" /> classes to emit all messages with a specified importance or greater. When the <see cref="P:System.Diagnostics.TraceSwitch.Level" /> property is set to <see cref="F:System.Diagnostics.TraceLevel.Warning" />, warnings and error-handling messages are emitted.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Gets a value indicating whether the switch allows warning messages.</para>
</summary>
</Docs>
</Member>
</Members>
</Type>