AppContext.TryGetSwitch(String, Boolean) Method

Definition

Namespace:

System

Assembly:

System.Runtime.dll

Source:

AppContext.cs

Tries to get the value of a switch.

public:
 static bool TryGetSwitch(System::String ^ switchName, [Runtime::InteropServices::Out] bool % isEnabled);

public static bool TryGetSwitch (string switchName, out bool isEnabled);

static member TryGetSwitch : string * bool -> bool

Public Shared Function TryGetSwitch (switchName As String, ByRef isEnabled As Boolean) As Boolean

Parameters

switchName

String

The name of the switch.

isEnabled

Boolean

When this method returns, contains the value of switchName if switchName was found, or false if switchName was not found. This parameter is passed uninitialized.

Returns

Boolean

true if switchName was set and the isEnabled argument contains the value of the switch; otherwise, false.

Exceptions

ArgumentNullException

switchName is null.

ArgumentException

switchName is Empty.

Examples

The following example determines whether a library consumer has set a switch named Switch.AmazingLib.ThrowOnException.

public class AmazingLib
{
   private bool shouldThrow;

   public void PerformAnOperation()
   {
      if (!AppContext.TryGetSwitch("Switch.AmazingLib.ThrowOnException", out shouldThrow)) {
         // This is the case where the switch value was not set by the application.
         // The library can choose to get the value of shouldThrow by other means.
         // If no overrides or default values are specified, the value should be 'false'.
         // A false value implies the latest behavior.
      }

      // The library can use the value of shouldThrow to throw exceptions or not.
      if (shouldThrow) {
         // old code
      }
      else {
          // new code
      }
   }
}

module AmazingLib =
    let performAnOperation () =
        match AppContext.TryGetSwitch "Switch.AmazingLib.ThrowOnException" with
        | false, _ ->
            // This is the case where the switch value was not set by the application.
            // The library can choose to get the value of shouldThrow by other means.
            // If no overrides or default values are specified, the value should be 'false'.
            // A false value implies the latest behavior.
            ()
        | true, shouldThrow ->
            // The library can use the value of shouldThrow to throw exceptions or not.
            if shouldThrow then
                // old code
                ()
            else
                // new code
                ()

Public Class AmazingLib

   Private shouldThrow As Boolean

   Public Sub PerformAnOperation()
      If Not AppContext.TryGetSwitch("Switch.AmazingLib.ThrowOnException", shouldThrow) Then 
         ' This is the case where the switch value was not set by the application. 
         ' The library can choose to get the value of shouldThrow by other means. 
         ' If no overrides or default values are specified, the value should be 'false'. 
         ' A false value implies the latest behavior.
      End If

      ' The library can use the value of shouldThrow to throw exceptions or not.
      If shouldThrow Then
         ' old code
      Else 
          ' new code
      End If
   End Sub
End Class

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 common language runtime automatically populates the switches assigned to an AppContext instance by reading the registry and the application's configuration file. The value of these switches can then be overridden, and new switches added, by calling the SetSwitch method.

A library calls the TryGetSwitch method to check whether its consumers have declared the value of the switch and then act appropriately on it. By default, if the switch is not defined, the new functionality is enabled. If the switch is defined and its value is false, the new functionality is also enabled. If its value is true, the legacy behavior is enabled.

See also

• SetSwitch(String, Boolean)