AppContext.SetSwitch(String, Boolean) 方法


设置开关的值。Sets the value of a switch.

 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)



开关的名称。The name of the switch.


开关的值。The value of the switch.


switchNamenullswitchName is null.

switchNameEmptyswitchName is Empty.


下面的代码行设置一个名为的 Switch.AmazingLib.ThrowOnException 开关 true ,后者启用了旧行为。The following line of code sets a switch named Switch.AmazingLib.ThrowOnException to true, which enables a legacy behavior. 然后,库可以通过调用方法来检查库使用者是否已设置开关的值 TryGetSwitchThe 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类使库编写器可为其用户提供新功能的统一退出机制。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.

SetSwitch 方法由应用程序调用 (或库) ,以声明一个开关的值 (这始终是 Boolean 依赖库定义的) 值。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. 开关始终是隐式的 false ,它提供新的行为。The switch is always implicitly false, which provides the new behavior. 通过设置开关来 true 启用它,它提供了旧行为。Setting the switch to true enables it, which provides the legacy behavior. 将开关显式设置为 false 也可提供新的行为。Explicitly setting the switch to false also provides the new behavior. 然后,依赖库可以通过调用方法来检查开关的值 TryGetSwitchThe dependent library can then check the value of the switch by calling the TryGetSwitch method.


使用一致的开关名称格式是有益的,因为它们是由库公开的正式协定。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.switchnameSwitch.namespace.switchname
  • Switch.library.switchnameSwitch.library.switchname

对于在 .NET Framework 上运行的应用程序,除了以编程方式设置开关的值外,还可以设置以下内容:For applications running on .NET Framework, in addition to setting the value of a switch programmatically, it can also be set:

  • 通过向 <AppContextSwitchOverrides> <runtime> 应用程序配置文件的部分中的元素添加开关名称和值。By adding the switch name and value to the <AppContextSwitchOverrides> element in the <runtime> section of an application configuration file. 例如,下面定义了一个名为的开关, Libraries.FPLibrary.UseExactFloatingPointComparison 其值为 FalseFor example, the following defines a switch named Libraries.FPLibrary.UseExactFloatingPointComparison whose value is False.

          <AppContextSwitchOverrides value="Libraries.FPLibrary.UseExactFloatingPointComparison=false" />
  • 通过在注册表中添加 name 为 HKLM\SOFTWARE\Microsoft . NETFramework\AppContext (和 HKLM\SOFTWARE\Wow6432Node\Microsoft . NETFramework\AppContext) 子项的名称的字符串值。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. 它的值必须是可以通过方法分析的的字符串表示形式 Boolean Boolean.Parse ; 也就是说,它必须是 "true"、"true"、"false" 或 "false"。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".

如果该注册表项存在,则在调用时,它的值将被 isEnabled 参数覆盖 SetSwitchIf the registry entry exists, its value is overwritten by the isEnabled argument when SetSwitch is called. 即,对方法的最新调用将 SetSwitch 重写在注册表、应用程序配置文件中定义的值,或者在以前对方法的调用中重写 SetSwitchThat 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.

AppContext. SetSwitch 和 .NET CoreAppContext.SetSwitch and .NET Core

.NET Core 仅支持通过方法进行编程调用 SetSwitch.NET Core supports programmatic calls with the SetSwitch method only. 支持以下开关:The following switches are supported:

开关Switch Values 说明Description
System.Net.Http.SocketsHttpHandler.Http2Support truefalsetrue or false 指示是否启用对 HTTP/2 协议的支持 (true) 或禁用 (false) 。Indicates whether support for the HTTP/2 protocol is enabled (true) or disabled (false). 默认为禁用。The default is disabled. 在首次使用之前,必须设置此开关 HttpClientThe switch must be set before the first use of HttpClient. 从 .NET Core 3.0 预览版4开始提供。Available starting with .NET Core 3.0 Preview 4.
System.Net.Http.UseSocketsHttpHandler truefalsetrue or false 确定高级网络 Api (如 HttpClient 使用 System.Net.Http.SocketsHttpHandler (true) 或 System.Net.Http.HttpClientHandler (false) 。Determines whether high-level networking APIs such as HttpClient use System.Net.Http.SocketsHttpHandler (true) or System.Net.Http.HttpClientHandler (false).