AppContext AppContext AppContext AppContext Class

Definição

Fornece membros para definir e recuperar dados sobre o contexto de um aplicativo.Provides members for setting and retrieving data about an application's context.

public ref class AppContext abstract sealed
public static class AppContext
type AppContext = class
Public Class AppContext
Herança
AppContextAppContextAppContextAppContext

Comentários

O AppContext classe permite aos escritores de biblioteca fornecer um mecanismo de recusa uniforme para a nova funcionalidade para seus usuários.The AppContext class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. Ela estabelece um contrato flexível entre componentes a fim de comunicar uma solicitação de recusa.It establishes a loosely-coupled contract between components in order to communicate an opt-out request. Normalmente, essa funcionalidade é importante quando uma alteração é feita na funcionalidade existente.This capability is typically important when a change is made to existing functionality. Por outro lado, já existe uma aceitação implícita da nova funcionalidade.Conversely, there is already an implicit opt-in for new functionality.

AppContext para desenvolvedores de bibliotecasAppContext for library developers

Usam bibliotecas de AppContext alterna de classe para definir e expor a compatibilidade, enquanto os usuários da biblioteca podem definir essas opções para afetar o comportamento da biblioteca.Libraries use the AppContext class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. Por padrão, as bibliotecas fornecem a nova funcionalidade, e apenas a alteram (ou seja, eles fornecem a funcionalidade anterior) se a opção for definida.By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. Isso permite que as bibliotecas fornecer o novo comportamento para uma API existente enquanto continua a dar suporte a chamadores que dependem do comportamento anterior.This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior.

Definindo o nome do comutadorDefining the switch name

A maneira mais comum para permitir que os consumidores da sua biblioteca recusar uma alteração de comportamento é definir uma opção nomeada.The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. Sua value elemento é um par de nome/valor que consiste no nome de um comutador e seu Boolean valor.Its value element is a name/value pair that consists of the name of a switch and its Boolean value. Por padrão, a opção é sempre implicitamente false, que fornece o novo comportamento (e torna o novo comportamento de aceitação por padrão).By default, the switch is always implicitly false, which provides the new behavior (and makes the new behavior opt-in by default). Definição da opção true permite a ele, que fornece o comportamento herdado.Setting the switch to true enables it, which provides the legacy behavior. Definir explicitamente a opção false também fornece o novo comportamento.Explicitly setting the switch to false also provides the new behavior.

É útil usar um formato consistente para nomes de comutador, já que eles são um contrato formal exposto por uma biblioteca.It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. Veja a seguir dois formatos óbvios.The following are two obvious formats.

  • Opção.namespace.nomedaopçãoSwitch.namespace.switchname

  • Opção.biblioteca.nomedaopçãoSwitch.library.switchname

Depois de definir e documentar o comutador, os chamadores podem usar usando o registro, adicionando um <AppContextSwitchOverrides > elemento ao seu arquivo de configuração do aplicativo ou chamando o AppContext.SetSwitch(String, Boolean) método programaticamente.Once you define and document the switch, callers can use it by using the registry, by adding an <AppContextSwitchOverrides> element to their application configuration file, or by calling the AppContext.SetSwitch(String, Boolean) method programmatically. Consulte a AppContext para os clientes de biblioteca para obter mais informações sobre como os chamadores usar e definem o valor de AppContext switches de configuração.See the AppContext for library consumers section for more information about how callers use and set the value of AppContext configuration switches.

Quando o common language runtime executa um aplicativo, ele automaticamente lê as configurações de compatibilidade do registro e carrega o arquivo de configuração de aplicativo para preencher o aplicativo AppContext instância.When the common language runtime runs an application, it automatically reads the registry's compatibility settings and loads the application configuration file in order to populate the application's AppContext instance. Porque o AppContext instância é preenchida por meio de programação pelo chamador ou pelo tempo de execução, você não precisa realizar nenhuma ação, por exemplo, chamar o SetSwitch método para configurar o AppContext instância.Because the AppContext instance is populated either programmatically by the caller or by the runtime, you do not have to take any action, such as calling the SetSwitch method, to configure the AppContext instance.

Verificando a configuraçãoChecking the setting

Você pode então verificar se um consumidor declarou o valor do comutador e act adequadamente chamando o AppContext.TryGetSwitch método.You can then check if a consumer has declared the value of the switch and act appropriately by calling the AppContext.TryGetSwitch method. O método retornará true se o switchName argumento for encontrado e, quando o método retornar, sua isEnabled argumento indica o valor da opção.The method returns true if the switchName argument is found, and when the method returns, its isEnabled argument indicates the value of the switch. Do contrário, o método retorna false.Otherwise, the method returns false.

Um exemploAn example

O exemplo a seguir ilustra o uso da AppContext classe para permitir que o cliente escolher o comportamento original de um método de biblioteca.The following example illustrates the use of the AppContext class to allow the customer to choose the original behavior of a library method. A seguir está a versão 1.0 de uma biblioteca denominada StringLibrary.The following is version 1.0 of a library named StringLibrary. Ele define uma SubstringStartsAt método que executa uma comparação ordinal para determinar o índice inicial de uma subcadeia de caracteres dentro de uma cadeia de caracteres maior.It defines a SubstringStartsAt method that performs an ordinal comparison to determine the starting index of a substring within a larger string.

using System;
using System.Reflection;

[assembly: AssemblyVersion("1.0.0.0")]

public static class StringLibrary
{
   public static int SubstringStartsAt(String fullString, String substr)
   {
      return fullString.IndexOf(substr, StringComparison.Ordinal);
   }
}
Imports System.Reflection

<Assembly: AssemblyVersion("1.0.0.0")>

Public Class StringLibrary
   Public Shared Function SubstringStartsAt(fullString As String, substr As String) As Integer
      Return fullString.IndexOf(substr, StringComparison.Ordinal)
   End Function
End Class

O exemplo a seguir, em seguida, usa a biblioteca para localizar o índice inicial da subcadeia de caracteres "archæ" em "O archaeologist".The following example then uses the library to find the starting index of the substring "archæ" in "The archaeologist". Como o método executa uma comparação ordinal, a subcadeia de caracteres não pode ser encontrada.Because the method performs an ordinal comparison, the substring cannot be found.

using System;

public class Example
{
   public static void Main()
   {
      String value = "The archaeologist";
      String substring = "archæ";
      int position = StringLibrary.SubstringStartsAt(value, substring); 
      if (position >= 0) 
         Console.WriteLine("'{0}' found in '{1}' starting at position {2}",
                        substring, value, position);
      else
         Console.WriteLine("'{0}' not found in '{1}'", substring, value);
   }
}
// The example displays the following output:
//       'archæ' not found in 'The archaeologist'
Public Module Example
   Public Sub Main()
      Dim value As String = "The archaeologist"
      Dim substring As String = "archæ"
      Dim position As Integer = StringLibrary.SubstringStartsAt(value, substring) 
      If position >= 0 Then 
         Console.WriteLine("'{0}' found in '{1}' starting at position {2}",
                        substring, value, position)
      Else
         Console.WriteLine("'{0}' not found in '{1}'", substring, value)
      End If                  
   End Sub
End Module
' The example displays the following output:
'       'archæ' not found in 'The archaeologist'

A versão 2 da biblioteca, no entanto, altera o SubstringStartsAt método usar comparação sensível à cultura.Version 2 of the library, however, changes the SubstringStartsAt method to use culture-sensitive comparison.

using System;
using System.Reflection;

[assembly: AssemblyVersion("2.0.0.0")]

public static class StringLibrary
{
   public static int SubstringStartsAt(String fullString, String substr)
   {
      return fullString.IndexOf(substr, StringComparison.CurrentCulture);
   }
}
Imports System.Reflection

<Assembly: AssemblyVersion("2.0.0.0")>

Public Class StringLibrary
   Public Shared Function SubstringStartsAt(fullString As String, substr As String) As Integer
      Return fullString.IndexOf(substr, StringComparison.CurrentCulture)
   End Function
End Class

Quando o aplicativo é recompilado para ser executado em relação a nova versão da biblioteca, ele agora relata que a subcadeia de caracteres "archæ" foi encontrado no índice 4 em "O archaeologist".When the app is recompiled to run against the new version of the library, it now reports that the substring "archæ" is found at index 4 in "The archaeologist".

using System;

public class Example
{
   public static void Main()
   {
      String value = "The archaeologist";
      String substring = "archæ";
      int position = StringLibrary.SubstringStartsAt(value, substring); 
      if (position >= 0) 
         Console.WriteLine("'{0}' found in '{1}' starting at position {2}",
                        substring, value, position);
      else
         Console.WriteLine("'{0}' not found in '{1}'", substring, value);
   }
}
// The example displays the following output:
//       'archæ' found in 'The archaeologist' starting at position 4   
Public Module Example
   Public Sub Main()
      Dim value As String = "The archaeologist"
      Dim substring As String = "archæ"
      Dim position As Integer = StringLibrary.SubstringStartsAt(value, substring) 
      If position >= 0 Then 
         Console.WriteLine("'{0}' found in '{1}' starting at position {2}",
                        substring, value, position)
      Else
         Console.WriteLine("'{0}' not found in '{1}'", substring, value)
      End If                  
   End Sub
End Module
' The example displays the following output:
'       'archæ' found in 'The archaeologist' starting at position 4

Essa alteração pode ser impedida de interromper os aplicativos que dependem do comportamento original, definindo um <AppContextSwitchOverrides > alternar.This change can be prevented from breaking the applications that depend on the original behavior by defining an <AppContextSwitchOverrides> switch. Nesse caso, a opção é denominada StringLibrary.DoNotUseCultureSensitiveComparison.In this case, the switch is named StringLibrary.DoNotUseCultureSensitiveComparison. Seu valor padrão, false, indica que a biblioteca deve realizar sua comparação sensível à cultura de versão 2.0.Its default value, false, indicates that the library should perform its version 2.0 culture-sensitive comparison. true indica que a biblioteca deve realizar sua comparação ordinal da versão 1.0.true indicates that the library should perform its version 1.0 ordinal comparison. Uma leve modificação do código anterior permite que o consumidor de biblioteca definir a opção para determinar o tipo de comparação que executa o método.A slight modification of the previous code allows the library consumer to set the switch to determine the kind of comparison the method performs.

using System;
using System.Reflection;

[assembly: AssemblyVersion("2.0.0.0")]

public static class StringLibrary
{
   public static int SubstringStartsAt(String fullString, String substr)
   {
      bool flag;
      if (AppContext.TryGetSwitch("StringLibrary.DoNotUseCultureSensitiveComparison", out flag) && flag == true)
         return fullString.IndexOf(substr, StringComparison.Ordinal);
      else
         return fullString.IndexOf(substr, StringComparison.CurrentCulture);
         
   }
}
Imports System.Reflection

<Assembly: AssemblyVersion("2.0.0.0")>

Public Class StringLibrary
   Public Shared Function SubstringStartsAt(fullString As String, substr As String) As Integer
      Dim flag As Boolean
      If AppContext.TryGetSwitch("StringLibrary.DoNotUseCultureSensitiveComparison", flag) AndAlso flag = True Then
         Return fullString.IndexOf(substr, StringComparison.Ordinal)
      Else
         Return fullString.IndexOf(substr, StringComparison.CurrentCulture)
      End If   
   End Function
End Class

Se o aplicativo pode usar o arquivo de configuração a seguir para restaurar o comportamento da versão 1.0.If application can then use the following configuration file to restore the version 1.0 behavior.


<configuration>
   <runtime>
      <AppContextSwitchOverrides value="StringLibrary.DoNotUseCultureSensitiveComparison=true" />
   </runtime>
</configuration>

Quando o aplicativo é executado com o arquivo de configuração presente, ele produz a saída a seguir:When the application is run with the configuration file present, it produces the following output:

'archæ' not found in 'The archaeologist'

AppContext para os clientes de bibliotecaAppContext for library consumers

Se você for o consumidor de uma biblioteca, o AppContext classe permite que você tire proveito de uma biblioteca ou mecanismo de recusa do método de biblioteca para a nova funcionalidade.If you are the consumer of a library, the AppContext class allows you to take advantage of a library or library method's opt-out mechanism for new functionality. Métodos individuais da biblioteca de classes que você está chamando definem comutadores específicos que habilitam ou desabilitam a um novo comportamento.Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. O valor da opção é um valor booliano.The value of the switch is a Boolean. Se ele estiver false, que normalmente é o valor padrão, o novo comportamento está habilitado; se for true, o novo comportamento está desabilitado e o membro se comporta como anteriormente.If it is false, which is typically the default value, the new behavior is enabled; if it is true, the new behavior is disabled, and the member behaves as it did previously.

Você pode definir o valor de uma opção em uma das quatro maneiras:You can set the value of a switch in one of four ways:

  • Chamando o AppContext.SetSwitch(String, Boolean) método em seu código.By calling the AppContext.SetSwitch(String, Boolean) method in your code. O switchName argumento define o nome do comutador e o isEnabled propriedade define o valor da opção.The switchName argument defines the switch name, and the isEnabled property defines the value of the switch. Porque AppContext é uma classe estática, ele está disponível em uma base de domínio de aplicativo.Because AppContext is a static class, it is available on a per-application domain basis.

    Chamar o AppContext.SetSwitch(String, Boolean) tem escopo de aplicativo; ou seja, ele afeta somente o aplicativo.Calling the AppContext.SetSwitch(String, Boolean) has application scope; that is, it affects only the application.

  • Adicionando um <AppContextSwitchOverrides> elemento para o <tempo de execução > seção do seu arquivo App. config.By adding an <AppContextSwitchOverrides> element to the <runtime> section of your app.config file. A opção tem um único atributo, value, cujo valor é uma cadeia de caracteres que representa um par chave/valor que contém o nome do comutador e seu valor.The switch has a single attribute, value, whose value is a string that represents a key/value pair containing both the switch name and its value.

    Para definir várias opções, separe o par de chave/valor da cada opção na <AppContextSwitchOverrides > do elemento value atributo com um ponto e vírgula.To define multiple switches, separate each switch's key/value pair in the <AppContextSwitchOverrides> element's value attribute with a semicolon. Nesse caso, o <AppContextSwitchOverrides> elemento tem o seguinte formato:In that case, the <AppContextSwitchOverrides> element has the following format:

    <AppContextSwitchOverrides value="switchName1=value1;switchName2=value2" />
    

    Usando o <AppContextSwitchOverrides> elemento para definir um parâmetro de configuração tem escopo do aplicativo; ou seja, ele afeta somente o aplicativo.Using the <AppContextSwitchOverrides> element to define a configuration setting has application scope; that is, it affects only the application.

    Observação

    Para obter informações sobre as opções definidas pelo .NET Framework, consulte o <AppContextSwitchOverrides > elemento.For information on the switches defined by the .NET Framework, see the <AppContextSwitchOverrides> element.

  • Adicionando um valor de cadeia de caracteres cujo nome é o nome do comutador para o HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext chave no registro.By adding a string value whose name is the name of the switch to the HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext key in the registry. Seu valor deve ser a representação de cadeia de caracteres de um Boolean que pode ser analisado pelo Boolean.Parse método; ou seja, ele deve ser "True", "true", "False" ou "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". Se o tempo de execução encontrar qualquer outro valor, ele ignora o comutador.If the runtime encounters any other value, it ignores the switch.

    Usando o registro para definir um AppContext switch tem escopo do computador; ou seja, ele afeta todos os aplicativos em execução no computador.Using the registry to define an AppContext switch has machine scope; that is, it affects every application running on the machine.

  • Para aplicativos ASP.NET, você adiciona uma <Adicionar > elemento para o <appSettings > seção do arquivo Web. config.For ASP.NET applications, you add an <Add> element to the <appSettings> section of the web.config file. Por exemplo:For example:

    <appSettings>
       <add key="AppContext.SetSwitch:switchName1" value="switchValue1" />
       <add key="AppContext.SetSwitch:switchName2" value="switchValue2" />
    </appSettings>
    

Se você definir o mesmo comutador em mais de uma maneira, a ordem de precedência para determinar qual configuração substituirá os outros é:If you set the same switch in more than one way, the order of precedence for determining which setting overrides the others is:

  1. A configuração programática.The programmatic setting.

  2. A configuração no arquivo de configuração de aplicativo ou o arquivo Web. config.The setting in the app config file or the web.config file.

  3. A configuração do registro.The registry setting.

O seguinte é um aplicativo simples que passa um URI de arquivo para o Path.GetDirectoryName método.The following is a simple application that passes a file URI to the Path.GetDirectoryName method. Quando executado no .NET Framework 4.6, ele gerará uma ArgumentException porque file:// não é parte de um caminho de arquivo válida.When run under the .NET Framework 4.6, it throws an ArgumentException because file:// is no longer a valid part of a file path.

using System;
using System.IO;
using System.Runtime.Versioning;

[assembly:TargetFramework(".NETFramework,Version=v4.6.2")]

public class Example
{
   public static void Main()
   {
      Console.WriteLine(Path.GetDirectoryName("file://c/temp/dirlist.txt")); 
   }
}
// The example displays the following output:
//    Unhandled Exception: System.ArgumentException: The path is not of a legal form.
//       at System.IO.Path.NewNormalizePathLimitedChecks(String path, Int32 maxPathLength, Boolean expandShortPaths)
//       at System.IO.Path.NormalizePath(String path, Boolean fullCheck, Int32 maxPathLength, Boolean expandShortPaths)
//       at System.IO.Path.InternalGetDirectoryName(String path)
//       at Example.Main()
Imports System.IO
Imports System.Runtime.Versioning

<assembly:TargetFramework(".NETFramework,Version=v4.6.2")>

Module Example
   Public Sub Main()
      Console.WriteLine(Path.GetDirectoryName("file://c/temp/dirlist.txt")) 
   End Sub
End Module
' The example displays the following output:
'    Unhandled Exception: System.ArgumentException: The path is not of a legal form.
'       at System.IO.Path.NewNormalizePathLimitedChecks(String path, Int32 maxPathLength, Boolean expandShortPaths)
'       at System.IO.Path.NormalizePath(String path, Boolean fullCheck, Int32 maxPathLength, Boolean expandShortPaths)
'       at System.IO.Path.InternalGetDirectoryName(String path)
'       at Example.Main()

Para restaurar o comportamento do método anterior e evitar a exceção, você pode adicionar o Switch.System.IO.UseLegacyPathHandling alternar para o arquivo de configuração de aplicativo para o exemplo:To restore the method's previous behavior and prevent the exception, you can add the Switch.System.IO.UseLegacyPathHandling switch to the application configuration file for the example:

<configuration>
    <runtime>
        <AppContextSwitchOverrides value="Switch.System.IO.UseLegacyPathHandling=true" />
    </runtime>
</configuration>

Consulte tambémSee also

Opção de AppContextAppContext switch

Propriedades

BaseDirectory BaseDirectory BaseDirectory BaseDirectory

Obtém o nome do caminho do diretório base usado pelo resolvedor de assembly para investigar assemblies.Gets the pathname of the base directory that the assembly resolver uses to probe for assemblies.

TargetFrameworkName TargetFrameworkName TargetFrameworkName TargetFrameworkName

Obtém o nome da versão da estrutura de direcionada pelo aplicativo atual.Gets the name of the framework version targeted by the current application.

Métodos

GetData(String) GetData(String) GetData(String) GetData(String)

Retorna o valor do elemento de dados nomeado atribuído ao domínio do aplicativo atual.Returns the value of the named data element assigned to the current application domain.

SetSwitch(String, Boolean) SetSwitch(String, Boolean) SetSwitch(String, Boolean) SetSwitch(String, Boolean)

Define o valor de uma opção.Sets the value of a switch.

TryGetSwitch(String, Boolean) TryGetSwitch(String, Boolean) TryGetSwitch(String, Boolean) TryGetSwitch(String, Boolean)

Tenta obter o valor de um comutador.Tries to get the value of a switch.

Aplica-se a

Veja também