AppContext.SetSwitch(String, Boolean) Method

Reference

Definition

Namespace:: System

Assemblies:: mscorlib.dll, System.AppContext.dll

Assembly:: System.Runtime.dll

Assembly:: System.AppContext.dll

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Source:: AppContext.cs

Source:: AppContext.cs

Source:: AppContext.cs

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Sets the value of a switch.

public:
 static void SetSwitch(System::String ^ switchName, bool isEnabled);

public static void SetSwitch (string switchName, bool isEnabled);

static member SetSwitch : string * bool -> unit

Public Shared Sub SetSwitch (switchName As String, isEnabled As Boolean)

Parameters

switchName: String

The name of the switch.

isEnabled: Boolean

The value of the switch.

Exceptions

ArgumentNullException

switchName is null.

ArgumentException

switchName is Empty.

Examples

The following line of code sets a switch named Switch.AmazingLib.ThrowOnException to true, which enables a legacy behavior. The library can then check whether a library consumer has set the value of the switch by calling the TryGetSwitch method.

AppContext.SetSwitch("Switch.AmazingLib.ThrowOnException", true);

AppContext.SetSwitch("Switch.AmazingLib.ThrowOnException", true)

AppContext.SetSwitch("Switch.AmazingLib.ThrowOnException", True)

Remarks

The AppContext class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. It establishes a loosely coupled contract between components in order to communicate an opt-out request. This capability is typically important when a change is made to existing functionality. Conversely, there is already an implicit opt-in for new functionality.

The SetSwitch method is called by an application (or a library) to declare the value of a switch (which is always a Boolean value) that a dependent library defines. The switch is always implicitly false, which provides the new behavior. Setting the switch to true enables it, which provides the legacy behavior. Explicitly setting the switch to false also provides the new behavior. The dependent library can then check the value of the switch by calling the TryGetSwitch method.

Note

It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. The following are two obvious formats.

Switch.namespace.switchname
Switch.library.switchname

For applications running on .NET Framework, in addition to setting the value of a switch programmatically, it can also be set:

By adding the switch name and value to the <AppContextSwitchOverrides> element in the <runtime> section of an application configuration file. For example, the following defines a switch named Libraries.FPLibrary.UseExactFloatingPointComparison whose value is False.
```
<configuration>
   <runtime>
      <AppContextSwitchOverrides value="Libraries.FPLibrary.UseExactFloatingPointComparison=false" />
   </runtime>
</configuration>
```
By adding a string value whose name is the name of the switch to the HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext (and HKLM\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\AppContext) subkeys in the registry. Its value must be the string representation of a Boolean that can be parsed by the Boolean.Parse method; that is, it must be "True", "true", "False", or "false".

If the registry entry exists, its value is overwritten by the isEnabled argument when SetSwitch is called. That is, the most recent call to the SetSwitch method overrides the value defined in the registry, in an app configuration file, or by previous calls to the SetSwitch method.

Applies to

Dela via