AppContext.TryGetSwitch(String, Boolean) Method
Definition
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.
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 -> boolPublic Shared Function TryGetSwitch (switchName As String, ByRef isEnabled As Boolean) As BooleanParameters
- 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
true if switchName was set and the isEnabled argument contains the value of the switch; otherwise, false.
Exceptions
switchName is null.
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.
