AppContext Classe

Définition

public ref class AppContext abstract sealed

public static class AppContext

type AppContext = class

Public Class AppContext

Héritage

Object

AppContext

Remarques

La AppContext classe permet aux auteurs de bibliothèque de fournir un mécanisme d'annulation uniforme pour les nouvelles fonctionnalités à leurs utilisateurs. Il établit un contrat faiblement couplé entre les composants afin de communiquer une demande d’opt-out. Cette fonctionnalité est généralement importante lorsqu’une modification est apportée aux fonctionnalités existantes. À l’inverse, il existe déjà un opt-in implicite pour de nouvelles fonctionnalités.

AppContext pour les développeurs de bibliothèques

Les bibliothèques utilisent la AppContext classe pour définir et exposer des commutateurs de compatibilité, tandis que les utilisateurs de la bibliothèque peuvent définir ces commutateurs pour affecter le comportement de la bibliothèque. Par défaut, les bibliothèques fournissent les nouvelles fonctionnalités et les modifient uniquement (autrement dit, elles fournissent la fonctionnalité précédente) si le commutateur est défini. Cela permet aux bibliothèques de fournir un nouveau comportement pour une API existante tout en continuant à prendre en charge les appelants qui dépendent du comportement précédent.

Définir le nom du commutateur

La façon la plus courante de permettre aux consommateurs de votre bibliothèque de refuser un changement de comportement consiste à définir un commutateur nommé. Son value élément est une paire nom/valeur qui se compose du nom d’un commutateur et de sa Boolean valeur. Par défaut, le commutateur est toujours implicitement false, ce qui fournit le nouveau comportement (et le rend activé par défaut). Pour obtenir le comportement hérité, définissez le commutateur sur true pour l’activer. En définissant explicitement le commutateur sur false, on obtient également le nouveau comportement.

Il est préférable d'utiliser un format cohérent pour les noms de commutateurs, car il s'agit d'un contrat formel exposé par une bibliothèque. Voici deux formats évidents :

• Switch.espace de noms.switchname
• Commutateur.bibliothèque.nom_commutateur

Une fois que vous avez défini et documenté le commutateur, les appelants peuvent l’utiliser en appelant la AppContext.SetSwitch(String, Boolean) méthode par programmation.

Vérifier le paramètre

Vous pouvez vérifier si un consommateur a déclaré la valeur du commutateur et agir correctement en appelant la AppContext.TryGetSwitch méthode. La méthode retourne true si l’argument switchName est trouvé et son isEnabled argument indique la valeur du commutateur. Sinon, la méthode retourne false.

Exemple

L’exemple suivant illustre l’utilisation de la AppContext classe pour permettre au client de choisir le comportement d’origine d’une méthode de bibliothèque. Voici la version 1.0 d’une bibliothèque nommée StringLibrary. Il définit une méthode qui effectue une SubstringStartsAt comparaison ordinale pour déterminer l’index de départ d’une sous-chaîne dans une chaîne plus grande.

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

L’exemple suivant utilise ensuite la bibliothèque pour trouver l’index de départ de la sous-chaîne « archæ » dans « L’archéologue ». Étant donné que la méthode effectue une comparaison ordinale, la sous-chaîne est introuvable.

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'

Toutefois, la méthode de la version 2.0 de la bibliothèque est modifiée pour utiliser une comparaison qui est dotée d'une sensibilité culturelle.

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

Lorsque l’application est recompilée pour s’exécuter sur la nouvelle version de la bibliothèque, elle signale maintenant que la sous-chaîne « archæ » est trouvée à l’index 4 dans « L’archéologue ».

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

Cette modification peut être empêchée de briser les applications qui dépendent du comportement d’origine en définissant un commutateur. Dans ce cas, le commutateur est nommé StringLibrary.DoNotUseCultureSensitiveComparison. Sa valeur par défaut, false, indique que la bibliothèque doit effectuer sa comparaison prenant en compte les sensibilités culturelles de la version 2.0. true indique que la bibliothèque doit effectuer sa comparaison ordinale de la version 1.0. Une légère modification du code précédent permet au consommateur de bibliothèque de définir le commutateur pour déterminer le type de comparaison effectué par la méthode.

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 pour les consommateurs de bibliothèque

Si vous êtes utilisateur d’une bibliothèque, la classe AppContext vous permet de tirer parti d’un mécanisme de désactivation d’une méthode de bibliothèque pour introduire de nouvelles fonctionnalités. Les méthodes individuelles de la bibliothèque de classes que vous appelez définissent des commutateurs particuliers qui activent ou désactivent un nouveau comportement. La valeur du commutateur est une valeur booléenne. Si la valeur est false, qui est généralement la valeur par défaut, le nouveau comportement est activé ; si elle est true, le nouveau comportement est désactivé et le membre se comporte comme auparavant.

Vous pouvez définir la valeur d’un commutateur en appelant la AppContext.SetSwitch(String, Boolean) méthode dans votre code. L’argument switchName définit le nom du commutateur et la isEnabled propriété définit la valeur du commutateur. Étant donné qu’il AppContext s’agit d’une classe statique, elle est disponible par domaine d’application. L'appel de AppContext.SetSwitch(String, Boolean) a une portée d'application ; cela signifie qu'il n'affecte que l'application.

Pour les applications ASP.NET Core, vous définissez un commutateur en ajoutant un élément <Add> à la section <appSettings> du fichier web.config. Par exemple:

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

Si vous définissez le même commutateur de plusieurs façons, l’ordre de priorité pour déterminer quel paramètre remplace les autres est :

1. Réglage programmatique.
2. Paramètre dans le fichier web.config (pour les applications ASP.NET Core).