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. 然后,库可以通过调用 TryGetSwitch 方法来检查库使用者是否已设置开关的值。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 类,库编写器可为其用户提供新功能的统一退出机制。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. 然后,依赖库可以通过调用 TryGetSwitch 方法来检查开关的值。The 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 the .NET Framework, in addition to setting the value of a switch programmatically, it can also be set:

  • 通过在应用程序配置文件的<运行时 >部分中将开关名称和值添加到<AppContextSwitchOverrides >元素。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" />
  • 添加一个 string 值,其 name 为注册表中 HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext 项的开关的名称。By adding a string value whose name is the name of the switch to the HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext key in the registry. 其值必须是可以由 Boolean.Parse 方法分析的 Boolean 的字符串表示形式;也就是说,它必须是 "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".

如果 switchName 已存在,则 isEnabled 参数会覆盖其值。If switchName already exists, its value is overwritten by the isEnabled argument. 也就是说,对 SetSwitch 方法的最近调用将重写在注册表中定义的值、应用程序配置文件中或以前对 SetSwitch 方法的调用。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.

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. 在首次使用 HttpClient之前,必须设置此开关。The 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.SocketsHttpHandlertrue)或 System.Net.Http.HttpClientHandlerfalse)。Determines whether high-level networking APIs such as HttpClient use System.Net.Http.SocketsHttpHandler (true) or System.Net.Http.HttpClientHandler (false).