AppContext Clase

Definición

Proporciona miembros para configurar y recuperar datos sobre el contexto de una aplicación.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
Herencia
AppContext

Comentarios

La AppContext clase permite a los escritores de biblioteca proporcionar un mecanismo de cancelación uniforme para la nueva funcionalidad para sus usuarios.The AppContext class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. Establece un contrato flexible entre los componentes para poder comunicar una solicitud de cancelación de la participación.It establishes a loosely-coupled contract between components in order to communicate an opt-out request. Esta capacidad normalmente es importante cuando se realiza un cambio en la funcionalidad existente.This capability is typically important when a change is made to existing functionality. Por el contrario, la nueva funcionalidad participa de forma implícita.Conversely, there is already an implicit opt-in for new functionality.

AppContext para desarrolladores de bibliotecasAppContext for library developers

Las bibliotecas usan AppContext la clase para definir y exponer modificadores de compatibilidad, mientras que los usuarios de la biblioteca pueden establecer esos modificadores para que afecten al comportamiento de la biblioteca.Libraries use the AppContext class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. De forma predeterminada, las bibliotecas proporcionan la nueva funcionalidad y solo la modifican (es decir, ofrecen la funcionalidad anterior) si el modificador está establecido.By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. Esto permite que las bibliotecas proporcionen un nuevo comportamiento para una API existente mientras continúan admitiendo los llamadores que dependen del comportamiento anterior.This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior.

Definir el nombre del modificadorDefining the switch name

La forma más común de permitir que los consumidores de la biblioteca no se concedan a un cambio de comportamiento es definir un modificador con nombre.The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. Su value elemento es un par nombre-valor que consta del nombre de un modificador y su Boolean valor.Its value element is a name/value pair that consists of the name of a switch and its Boolean value. De forma predeterminada, el modificador siempre es falseimplícitamente, lo que proporciona el nuevo comportamiento (y hace que el nuevo comportamiento se opte de forma predeterminada).By default, the switch is always implicitly false, which provides the new behavior (and makes the new behavior opt-in by default). Al establecer el modificador en true , se habilita, lo que proporciona el comportamiento heredado.Setting the switch to true enables it, which provides the legacy behavior. Establecer explícitamente el modificador en false también proporciona el nuevo comportamiento.Explicitly setting the switch to false also provides the new behavior.

Es beneficioso usar un formato coherente para los nombres de conmutador, ya que son un contrato formal que expone una biblioteca.It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. Las siguientes son dos formatos obvios.The following are two obvious formats.

  • Modificador.espacio de nombres.nombre del modificadorSwitch.namespace.switchname

  • Modificador.biblioteca.nombre del modificadorSwitch.library.switchname

Una vez que se define y documenta el modificador, los llamadores pueden utilizarlo mediante el registro, < agregando un elemento de > de AppContextSwitchOverrides al archivo de configuración de AppContext.SetSwitch(String, Boolean) la aplicación o llamando al método mediante programación.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 la sección AppContext para los consumidores de la biblioteca para obtener más información sobre cómo los autores de la AppContext llamada usan y establecen el valor de los modificadores de configuración.See the AppContext for library consumers section for more information about how callers use and set the value of AppContext configuration switches.

Cuando el Common Language Runtime ejecuta una aplicación, lee automáticamente la configuración de compatibilidad del registro y carga el archivo de configuración de la aplicación para rellenar AppContext la instancia de la aplicación.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. Dado que la SetSwitch AppContext instancia se rellena mediante programación por el autor de la llamada o por el Runtime, no es necesario realizar ninguna acción, como llamar al método, para configurar la instancia. AppContextBecause 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.

Comprobando la configuraciónChecking the setting

Después, puede comprobar si un consumidor ha declarado el valor del modificador y actuar correctamente llamando al 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. El método devuelve true si se switchName encuentra el argumento y, cuando el método vuelve, su isEnabled argumento indica el valor del modificador.The method returns true if the switchName argument is found, and when the method returns, its isEnabled argument indicates the value of the switch. De lo contrario, el método devuelve false.Otherwise, the method returns false.

Un ejemploAn example

En el ejemplo siguiente se muestra el uso de AppContext la clase para permitir al cliente elegir el comportamiento original de un 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 continuación se indica la versión 1,0 de una StringLibrarybiblioteca denominada.The following is version 1.0 of a library named StringLibrary. Define un SubstringStartsAt método que realiza una comparación ordinal para determinar el índice inicial de una subcadena en una cadena más grande.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

En el ejemplo siguiente se usa la biblioteca para buscar el índice inicial de la subcadena "archæ" en "archaeologist".The following example then uses the library to find the starting index of the substring "archæ" in "The archaeologist". Dado que el método realiza una comparación ordinal, no se puede encontrar la subcadena.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'

La versión 2 de la biblioteca, sin embargo, SubstringStartsAt cambia el método para usar la comparación dependiente de la referencia cultural.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

Cuando se vuelve a compilar la aplicación para que se ejecute con la nueva versión de la biblioteca, ahora informa de que la subcadena "archæ" se encuentra en el índice 4 de "The 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

Este cambio puede evitarse interrumpir las aplicaciones que dependen del comportamiento original definiendo un < modificador de > de AppContextSwitchOverrides.This change can be prevented from breaking the applications that depend on the original behavior by defining an <AppContextSwitchOverrides> switch. En este caso, el modificador se StringLibrary.DoNotUseCultureSensitiveComparisondenomina.In this case, the switch is named StringLibrary.DoNotUseCultureSensitiveComparison. Su valor predeterminado, false, indica que la biblioteca debe realizar su comparación con la referencia cultural de la versión 2,0.Its default value, false, indicates that the library should perform its version 2.0 culture-sensitive comparison. trueindica que la biblioteca debe realizar su comparación ordinal de la versión 1,0.true indicates that the library should perform its version 1.0 ordinal comparison. Una ligera modificación del código anterior permite que el consumidor de la biblioteca establezca el modificador para determinar el tipo de comparación que realiza el 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

Si la aplicación puede usar el siguiente archivo de configuración para restaurar el comportamiento de la versión 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>

Cuando la aplicación se ejecuta con el archivo de configuración presente, genera el siguiente resultado:When the application is run with the configuration file present, it produces the following output:

'archæ' not found in 'The archaeologist'

AppContext para los consumidores de la bibliotecaAppContext for library consumers

Si es el consumidor de una biblioteca, la clase AppContext le permite aprovechar el mecanismo de cancelación de una biblioteca o un método de biblioteca para la nueva funcionalidad.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. Los métodos individuales de la biblioteca de clases a la que se llama definen los modificadores concretos que habilitan o deshabilitan un nuevo comportamiento.Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. El valor del modificador es un booleano.The value of the switch is a Boolean. Si es false, que suele ser el valor predeterminado, el nuevo comportamiento está habilitado; si es true, el nuevo comportamiento está deshabilitado y el miembro se comporta como lo hacía 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.

Puede establecer el valor de un modificador de una de estas cuatro maneras:You can set the value of a switch in one of four ways:

  • Llamando al AppContext.SetSwitch(String, Boolean) método en el código.By calling the AppContext.SetSwitch(String, Boolean) method in your code. El switchName argumento define el nombre del modificador y isEnabled la propiedad define el valor del modificador.The switchName argument defines the switch name, and the isEnabled property defines the value of the switch. Dado AppContext que es una clase estática, está disponible en cada dominio de aplicación.Because AppContext is a static class, it is available on a per-application domain basis.

    Llamar a AppContext.SetSwitch(String, Boolean) tiene ámbito de aplicación; es decir, solo afecta a la aplicación.Calling the AppContext.SetSwitch(String, Boolean) has application scope; that is, it affects only the application.

  • Agregando un <AppContextSwitchOverrides> elemento a la <sección > en tiempo de ejecución del archivo app. config.By adding an <AppContextSwitchOverrides> element to the <runtime> section of your app.config file. El modificador tiene un único atributo value,, cuyo valor es una cadena que representa un par clave-valor que contiene el nombre del modificador y su 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 varios modificadores, separe cada par clave-valor del modificador < en el atributo del value elemento > de AppContextSwitchOverrides con un punto y coma.To define multiple switches, separate each switch's key/value pair in the <AppContextSwitchOverrides> element's value attribute with a semicolon. En ese caso, el <AppContextSwitchOverrides> elemento tiene el formato siguiente:In that case, the <AppContextSwitchOverrides> element has the following format:

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

    Usar el <AppContextSwitchOverrides> elemento para definir un valor de configuración tiene ámbito de aplicación; es decir, solo afecta a la aplicación.Using the <AppContextSwitchOverrides> element to define a configuration setting has application scope; that is, it affects only the application.

    Nota

    Para obtener información sobre los modificadores definidos por el .NET Framework, vea el <elemento > de AppContextSwitchOverrides.For information on the switches defined by the .NET Framework, see the <AppContextSwitchOverrides> element.

  • Agregando un valor de cadena cuyo nombre es el nombre del modificador a HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext la clave en el 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. Su valor debe ser la representación de cadena de Boolean un que puede ser analizado por Boolean.Parse el método; es decir, debe ser "true", "true", "false" o "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". Si el tiempo de ejecución encuentra cualquier otro valor, omite el modificador.If the runtime encounters any other value, it ignores the switch.

    El uso del registro para definir AppContext un conmutador tiene ámbito de equipo; es decir, afecta a todas las aplicaciones que se ejecutan en la máquina.Using the registry to define an AppContext switch has machine scope; that is, it affects every application running on the machine.

  • En el caso de las aplicaciones ASP.net, agregue un <elemento Add > a la <sección > appSettings del archivo Web. config.For ASP.NET applications, you add an <Add> element to the <appSettings> section of the web.config file. Por ejemplo:For example:

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

Si establece el mismo modificador de más de una manera, el orden de prioridad para determinar qué configuración reemplaza a los demás es:If you set the same switch in more than one way, the order of precedence for determining which setting overrides the others is:

  1. La configuración de programación.The programmatic setting.

  2. La configuración en el archivo de configuración de la aplicación o en el archivo Web. config.The setting in the app config file or the web.config file.

  3. La configuración del registro.The registry setting.

La siguiente es una aplicación sencilla que pasa un URI de archivo al Path.GetDirectoryName método.The following is a simple application that passes a file URI to the Path.GetDirectoryName method. Cuando se ejecuta en el .NET Framework 4,6, produce una ArgumentException excepción porque file:// ya no es una parte válida de una ruta de acceso de archivo.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 el comportamiento anterior del método y evitar la excepción, puede Agregar el Switch.System.IO.UseLegacyPathHandling modificador al archivo de configuración de la aplicación para el ejemplo: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>

Vea tambiénSee also

Modificador AppContextAppContext switch

Propiedades

BaseDirectory

Obtiene el nombre de ruta de acceso del directorio base que la resolución de ensamblado usa para sondear ensamblados.Gets the pathname of the base directory that the assembly resolver uses to probe for assemblies.

TargetFrameworkName

Obtiene el nombre de la versión de Framework de destino de la aplicación actual.Gets the name of the framework version targeted by the current application.

Métodos

GetData(String)

Devuelve el valor del elemento de datos con nombre asignado al dominio de aplicación actual.Returns the value of the named data element assigned to the current application domain.

SetSwitch(String, Boolean)

Establece el valor de un conmutador.Sets the value of a switch.

TryGetSwitch(String, Boolean)

Intenta obtener el valor de un conmutador.Tries to get the value of a switch.

Se aplica a

Consulte también: