AppContext Clase

Definición

public ref class AppContext abstract sealed

public static class AppContext

type AppContext = class

Public Class AppContext

Herencia

Object

AppContext

Comentarios

La AppContext clase permite a los escritores de bibliotecas proporcionar un mecanismo uniforme de exclusión para la nueva funcionalidad para sus usuarios. Establece un contrato de acoplamiento flexible entre componentes para comunicar una solicitud de exclusión. Esta funcionalidad suele ser importante cuando se realiza un cambio en la funcionalidad existente. Por el contrario, ya hay un consentimiento implícito para la nueva funcionalidad.

AppContext para desarrolladores de bibliotecas

Las bibliotecas usan la AppContext clase para definir y exponer modificadores de compatibilidad, mientras que los usuarios de biblioteca pueden establecer esos modificadores para que afecten al comportamiento de la biblioteca. De forma predeterminada, las bibliotecas proporcionan la nueva funcionalidad y solo la modifican (es decir, proporcionan la funcionalidad anterior) si se establece el interruptor. Esto permite que las bibliotecas introduzcan nueva funcionalidad a una API existente mientras continúan apoyando a los usuarios que dependen del comportamiento anterior.

Definir el nombre del interruptor

La manera más común de permitir que los consumidores de tu biblioteca desactiven un cambio de funcionamiento es definir un conmutador con nombre. Su value elemento es un par nombre-valor compuesto por el nombre de un interruptor y su Boolean valor. De forma predeterminada, el interruptor siempre es implícitamente false, lo que proporciona el nuevo comportamiento (y lo hace opcional por defecto). Configurar el interruptor true hace que se habilite, lo que proporciona el comportamiento heredado. Al establecer explícitamente el conmutador en false, también se proporciona el nuevo comportamiento.

Es beneficioso usar un formato coherente para los nombres de interruptores, ya que son un contrato formal que presenta una biblioteca. A continuación se muestran dos formatos obvios:

• Modificador.espacio de nombres.nombre del modificador
• Modificador.biblioteca.nombre del modificador

Una vez que defina y documente el conmutador, los autores de llamadas pueden usarlo llamando al método AppContext.SetSwitch(String, Boolean) mediante programación.

Comprobación de la configuración

Puede comprobar si un consumidor ha declarado el valor del interruptor y actuar en consecuencia llamando al método AppContext.TryGetSwitch. El método devuelve true si se encuentra el argumento switchName, y el argumento isEnabled indica el valor del interruptor. De lo contrario, el método devuelve false.

Ejemplo

En el ejemplo siguiente se muestra el uso de la AppContext clase para permitir al cliente elegir el comportamiento original de un método de biblioteca. A continuación se muestra la versión 1.0 de una biblioteca denominada StringLibrary. Define un método que realiza una SubstringStartsAt comparación ordinal para determinar el índice inicial de una subcadena dentro de una cadena mayor.

using System;
using System.Reflection;

[assembly: AssemblyVersion("1.0.0.0")]

public static class StringLibrary1
{
    public static int SubstringStartsAt(string fullString, string substr)
    {
        return fullString.IndexOf(substr, StringComparison.Ordinal);
    }
}

open System
open System.Reflection

[<assembly: AssemblyVersion("1.0.0.0")>]
do ()

module StringLibrary =
    let substringStartsAt (fullString: string) (substr: string) =
        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

A continuación, en el ejemplo siguiente se usa la biblioteca para buscar el índice inicial de la subcadena "archæ" en "The archaeologist". Dado que el método realiza una comparación ordinal, no se encuentra la subcadena.

using System;

public class Example1
{
    public static void Main()
    {
        string value = "The archaeologist";
        string substring = "archæ";
        int position = StringLibrary1.SubstringStartsAt(value, substring);
        if (position >= 0)
            Console.WriteLine($"'{substring}' found in '{value}' starting at position {position}");
        else
            Console.WriteLine($"'{substring}' not found in '{value}'");
    }
}
// The example displays the following output:
//       'archæ' not found in 'The archaeologist'

let value = "The archaeologist"
let substring = "archæ"

let position =
    StringLibrary.substringStartsAt value substring

if position >= 0 then
    printfn $"'{substring}' found in '{value}' starting at position {position}"
else
    printfn $"'{substring}' not found in '{value}'"

// The example displays the following output:
//       'archæ' not found in 'The archaeologist'

Public Module Example4
    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'

Sin embargo, la versión 2.0 de la biblioteca cambia el método SubstringStartsAt para usar una comparación sensible a la cultura.

using System;
using System.Reflection;

[assembly: AssemblyVersion("2.0.0.0")]

public static class StringLibrary2
{
    public static int SubstringStartsAt(string fullString, string substr)
    {
        return fullString.IndexOf(substr, StringComparison.CurrentCulture);
    }
}

open System
open System.Reflection

[<assembly: AssemblyVersion("2.0.0.0")>]
do ()

module StringLibrary =
    let substringStartsAt (fullString: string) (substr: string) =
        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 en "El arqueólogo".

using System;

public class Example2
{
    public static void Main()
    {
        string value = "The archaeologist";
        string substring = "archæ";
        int position = StringLibrary2.SubstringStartsAt(value, substring);
        if (position >= 0)
            Console.WriteLine($"'{substring}' found in '{value}' starting at position {position}");
        else
            Console.WriteLine($"'{substring}' not found in '{value}'");
    }
}
// The example displays the following output:
//       'archæ' found in 'The archaeologist' starting at position 4

let value = "The archaeologist"
let substring = "archæ"

let position =
    StringLibrary.substringStartsAt value substring

if position >= 0 then
    printfn $"'{substring}' found in '{value}' starting at position {position}"
else
    printfn $"'{substring}' not found in '{value}'"

// The example displays the following output:
//       'archæ' found in 'The archaeologist' starting at position 4

Public Module Example6
    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

Se puede evitar que este cambio interrumpa las aplicaciones que dependen del comportamiento original definiendo un conmutador. En este caso, el interruptor se denomina StringLibrary.DoNotUseCultureSensitiveComparison. Su valor predeterminado, false, indica que la biblioteca debe realizar una comparación según la referencia cultural en su versión 2.0. true indica que la biblioteca debe realizar su comparación ordinal de la versión 1.0. Una ligera modificación del código anterior permite al consumidor de la biblioteca establecer el interruptor para determinar el tipo de comparación que realiza el método.

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);
   }
}

open System
open System.Reflection

[<assembly: AssemblyVersion("2.0.0.0")>]
do ()

AppContext.SetSwitch("StringLibrary.DoNotUseCultureSensitiveComparison",true)

module StringLibrary =
    let substringStartsAt (fullString: string) (substr: string) =
        match AppContext.TryGetSwitch "StringLibrary.DoNotUseCultureSensitiveComparison" with 
        | true, true -> fullString.IndexOf(substr, StringComparison.Ordinal)
        | _ -> 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

AppContext para consumidores de bibliotecas

Si es el consumidor de una biblioteca, la clase AppContext le permite aprovechar el mecanismo de una biblioteca o método de la biblioteca para cancelar la participación con nueva funcionalidad. Los métodos individuales de la biblioteca de clases que está llamando definen interruptores específicos que habilitan o deshabilitan un nuevo comportamiento. El valor del interruptor es un Booleano. 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 hizo anteriormente.

Puede establecer el valor de un interruptor llamando al método AppContext.SetSwitch(String, Boolean) en su código. El switchName argumento define el nombre del modificador y la isEnabled propiedad define el valor del modificador. Dado AppContext que es una clase estática, está disponible por dominio de aplicación. Llamar a AppContext.SetSwitch(String, Boolean) tiene ámbito de aplicación; es decir, afecta solo a la aplicación.

Para las aplicaciones de ASP.NET Core, establezca un modificador agregando un elemento /<Add> a la sección <appSettings> del archivo web.config. Por ejemplo:

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

Si cambia el mismo modificador de más de una forma, el orden de prioridad para determinar qué parámetro invalida a los demás es el siguiente:

1. La configuración programática.
2. Configuración del archivo web.config (para aplicaciones de ASP.NET Core).