AppContext AppContext AppContext AppContext Class

Définition

Fournit des membres pour définir et récupérer des données sur le contexte d'une application.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
Héritage
AppContextAppContextAppContextAppContext

Remarques

Le AppContext classe permet aux auteurs de bibliothèque de fournir un mécanisme d’annulations uniforme des nouvelles fonctionnalités pour les utilisateurs.The AppContext class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. Elle établit un contrat souple entre les composants pour la communication des demandes de désactivation.It establishes a loosely-coupled contract between components in order to communicate an opt-out request. Cette fonctionnalité est particulièrement importante quand une modification est apportée aux fonctionnalités existantes.This capability is typically important when a change is made to existing functionality. À l'inverse, il existe déjà une activation implicite des nouvelles fonctionnalités.Conversely, there is already an implicit opt-in for new functionality.

AppContext pour les développeurs de bibliothèqueAppContext for library developers

Bibliothèques utilisent le AppContext bascule de classe pour définir et exposer la compatibilité, tandis que les utilisateurs de bibliothèque peuvent définir ces commutateurs pour affecter le comportement de la bibliothèque.Libraries use the AppContext class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. Par défaut, les bibliothèques fournissent la nouvelle fonctionnalité et ne peuvent la modifier (c'est-à-dire fournir la version antérieure) que si le commutateur est défini.By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. Cela permet aux bibliothèques fournir un nouveau comportement pour une API existante tout en continuant à prendre en charge les appelants qui varient selon le comportement précédent.This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior.

Définir le nom du commutateurDefining the switch name

La méthode la plus courante pour permettre aux consommateurs de votre bibliothèque de refuser à un changement de comportement consiste à définir un commutateur nommé.The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. Son value élément est une paire nom/valeur qui se compose du nom d’un commutateur et ses Boolean valeur.Its value element is a name/value pair that consists of the name of a switch and its Boolean value. Par défaut, le commutateur est toujours implicitement false, qui fournit le nouveau comportement (et rend le nouveau comportement opt-in par défaut).By default, the switch is always implicitly false, which provides the new behavior (and makes the new behavior opt-in by default). Définissant le commutateur avec true lui permet, qui fournit le comportement hérité.Setting the switch to true enables it, which provides the legacy behavior. Explicitement en définissant le commutateur avec false fournit également le nouveau comportement.Explicitly setting the switch to false also provides the new behavior.

Il est préférable d’utiliser un format cohérent pour les noms de commutateur, puisqu’il s’agit d’un contrat formel exposé par une bibliothèque.It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. Voici les deux formats évidents.The following are two obvious formats.

  • Commutateur.espace de noms.nom_commutateurSwitch.namespace.switchname

  • Commutateur.bibliothèque.nom_commutateurSwitch.library.switchname

Une fois que vous définissez et documentez le commutateur, les appelants peuvent l’utiliser à l’aide du Registre, en ajoutant un <AppContextSwitchOverrides > élément dans leur fichier de configuration d’application, ou en appelant le AppContext.SetSwitch(String, Boolean) méthode par programmation.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. Consultez le AppContext pour les consommateurs de la bibliothèque section pour plus d’informations sur la façon dont les appelants utiliser et définir la valeur de AppContext changements de configuration.See the AppContext for library consumers section for more information about how callers use and set the value of AppContext configuration switches.

Lorsque le common language runtime exécute une application, il lit les paramètres de compatibilité du Registre automatiquement et charge le fichier de configuration d’application afin de renseigner l’application AppContext instance.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. Étant donné que le AppContext instance est remplie par programmation à l’appelant ou par le runtime, vous n’avez pas à intervenir, comme l’appel la SetSwitch méthode, pour configurer le AppContext instance.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.

Le paramètre de vérification de laChecking the setting

Vous pouvez ensuite vérifier si un consommateur a déclaré la valeur du commutateur et act de manière appropriée en appelant le AppContext.TryGetSwitch (méthode).You can then check if a consumer has declared the value of the switch and act appropriately by calling the AppContext.TryGetSwitch method. La méthode retourne true si le switchName argument se trouve, et lorsque la méthode est retournée, ses isEnabled argument indique la valeur du commutateur.The method returns true if the switchName argument is found, and when the method returns, its isEnabled argument indicates the value of the switch. Dans le cas contraire, la méthode retourne false.Otherwise, the method returns false.

ExempleAn example

L’exemple suivant illustre l’utilisation de la AppContext classe pour permettre au client choisir le comportement d’origine d’une méthode de bibliothèque.The following example illustrates the use of the AppContext class to allow the customer to choose the original behavior of a library method. Voici la version 1.0 d’une bibliothèque nommée StringLibrary.The following is version 1.0 of a library named StringLibrary. Il définit un SubstringStartsAt méthode qui effectue une comparaison ordinale pour déterminer l’index de départ d’une sous-chaîne dans une chaîne plus 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

L’exemple suivant utilise ensuite la bibliothèque pour rechercher l’index de départ de la sous-chaîne « archæ » dans « L’archaeologist ».The following example then uses the library to find the starting index of the substring "archæ" in "The archaeologist". Étant donné que la méthode effectue une comparaison ordinale, la sous-chaîne est introuvable.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'

Toutefois, modification de la version 2 de la bibliothèque, le SubstringStartsAt méthode à utiliser la comparaison dépendante de la culture.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

Lorsque l’application est recompilée à exécuter sur la nouvelle version de la bibliothèque, il signale désormais que la sous-chaîne « archæ » située à l’index 4 dans « L’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

Cette modification peut être empêchée de s’arrêter les applications qui reposent sur le comportement d’origine en définissant un <AppContextSwitchOverrides > basculer.This change can be prevented from breaking the applications that depend on the original behavior by defining an <AppContextSwitchOverrides> switch. Dans ce cas, le commutateur est nommé StringLibrary.DoNotUseCultureSensitiveComparison.In this case, the switch is named StringLibrary.DoNotUseCultureSensitiveComparison. Sa valeur par défaut, false, indique que la bibliothèque doit effectuer sa comparaison dépendante de la culture de version 2.0.Its default value, false, indicates that the library should perform its version 2.0 culture-sensitive comparison. true Indique que la bibliothèque doit effectuer sa comparaison ordinale version 1.0.true indicates that the library should perform its version 1.0 ordinal comparison. Une légère modification du code précédent permet au consommateur de la bibliothèque définir le commutateur pour déterminer le type de comparaison, que la méthode effectue.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 l’application peut ensuite utiliser le fichier de configuration suivant pour restaurer le comportement de la version 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>

Lorsque l’application est exécutée avec le fichier de configuration présents, il génère la sortie suivante :When the application is run with the configuration file present, it produces the following output:

'archæ' not found in 'The archaeologist'

AppContext pour les consommateurs de bibliothèqueAppContext for library consumers

Si vous êtes le consommateur d’une bibliothèque, le AppContext classe vous permet de tirer parti d’une bibliothèque ou mécanisme de désactivation de la méthode bibliothèque des nouvelles fonctionnalités.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. Les méthodes individuelles de la bibliothèque de classes que vous appelez définissent les commutateurs particuliers qui activent ou désactivent un nouveau comportement.Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. La valeur du commutateur est une valeur booléenne.The value of the switch is a Boolean. S’il s’agit 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 elle le faisait auparavant.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.

Vous pouvez définir la valeur d’un commutateur de quatre manières :You can set the value of a switch in one of four ways:

  • En appelant le AppContext.SetSwitch(String, Boolean) méthode dans votre code.By calling the AppContext.SetSwitch(String, Boolean) method in your code. Le switchName argument définit le nom du commutateur et le isEnabled propriété définit la valeur du commutateur.The switchName argument defines the switch name, and the isEnabled property defines the value of the switch. Étant donné que AppContext est une classe statique, il est disponible sur une base par domaine d’application.Because AppContext is a static class, it is available on a per-application domain basis.

    Appel de la AppContext.SetSwitch(String, Boolean) a une portée de l’application ; autrement dit, elle affecte uniquement l’application.Calling the AppContext.SetSwitch(String, Boolean) has application scope; that is, it affects only the application.

  • En ajoutant un <AppContextSwitchOverrides> élément à la <runtime > section de votre fichier app.config.By adding an <AppContextSwitchOverrides> element to the <runtime> section of your app.config file. Le commutateur a un attribut unique, value, dont la valeur est une chaîne qui représente une paire clé/valeur contenant le nom du commutateur et sa valeur.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.

    Pour définir plusieurs commutateurs, séparez la paire clé/valeur de chaque commutateur dans le <AppContextSwitchOverrides > l’élément value attribut par un point-virgule.To define multiple switches, separate each switch's key/value pair in the <AppContextSwitchOverrides> element's value attribute with a semicolon. Dans ce cas, le <AppContextSwitchOverrides> élément a le format suivant :In that case, the <AppContextSwitchOverrides> element has the following format:

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

    À l’aide de la <AppContextSwitchOverrides> élément pour définir un paramètre de configuration a une portée de l’application ; autrement dit, elle affecte uniquement l’application.Using the <AppContextSwitchOverrides> element to define a configuration setting has application scope; that is, it affects only the application.

    Notes

    Pour plus d’informations sur les commutateurs définis par le .NET Framework, consultez le <AppContextSwitchOverrides > élément.For information on the switches defined by the .NET Framework, see the <AppContextSwitchOverrides> element.

  • En ajoutant une valeur de chaîne dont le nom est le nom du commutateur à la HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext clé dans le Registre.By adding a string value whose name is the name of the switch to the HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext key in the registry. Sa valeur doit être la représentation sous forme de chaîne d’un Boolean qui peut être analysé par le Boolean.Parse méthode ; autrement dit, il doit être le « 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". Si l’exécution rencontre une autre valeur, il ignore le commutateur.If the runtime encounters any other value, it ignores the switch.

    À l’aide du Registre pour définir un AppContext commutateur a la portée de l’ordinateur ; autrement dit, elle affecte toutes les applications en cours d’exécution sur l’ordinateur.Using the registry to define an AppContext switch has machine scope; that is, it affects every application running on the machine.

  • Pour les applications ASP.NET, vous ajoutez un <Ajouter > élément à la <appSettings > section du fichier web.config.For ASP.NET applications, you add an <Add> element to the <appSettings> section of the web.config file. Par exemple :For example:

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

Si vous définissez le même commutateur dans plusieurs façons, l’ordre de priorité pour déterminer quel paramètre remplace les autres est :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 définition par programmation.The programmatic setting.

  2. Le paramètre dans le fichier de configuration d’application ou le fichier web.config.The setting in the app config file or the web.config file.

  3. Le paramètre de Registre.The registry setting.

Ce qui suit est une application simple qui transmet un URI de fichier pour le Path.GetDirectoryName (méthode).The following is a simple application that passes a file URI to the Path.GetDirectoryName method. Lors de l’exécution sous le .NET Framework 4.6, elle lève une ArgumentException car file:// n’est plus une partie d’un chemin de fichier valide.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()

Pour restaurer le comportement précédent de la méthode et empêcher l’exception, vous pouvez ajouter la Switch.System.IO.UseLegacyPathHandling basculer vers le fichier de configuration d’application pour l’exemple :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>

Voir aussiSee also

Commutateur appcontext la valeurAppContext switch

Propriétés

BaseDirectory BaseDirectory BaseDirectory BaseDirectory

Obtient le nom de chemin du répertoire de base qu’utilise le service de résolution d’assembly pour détecter les assemblys.Gets the pathname of the base directory that the assembly resolver uses to probe for assemblies.

TargetFrameworkName TargetFrameworkName TargetFrameworkName TargetFrameworkName

Obtient le nom de la version de framework ciblée par l’application actuelle.Gets the name of the framework version targeted by the current application.

Méthodes

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

Retourne la valeur de l’élément de données nommé attribué au domaine d’application actuel.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)

Définit la valeur d’un commutateur.Sets the value of a switch.

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

Tente d’obtenir la valeur d’un commutateur.Tries to get the value of a switch.

S’applique à

Voir aussi