AppContext Klasse

Definition

Stellt Member zum Festlegen und Abrufen von Daten für einen Anwendungskontext bereit.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
Vererbung
AppContext

Hinweise

Mit AppContext der-Klasse können Bibliotheks Schreiber einen einheitlichen Opt-Out-Mechanismus für neue Funktionen für Ihre Benutzer bereitstellen.The AppContext class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. Sie richtet einen lose gekoppelten Vertrag zwischen den Komponenten ein, um eine Anforderung zur Abwahl zu übermitteln.It establishes a loosely-coupled contract between components in order to communicate an opt-out request. Diese Möglichkeit ist in der Regel wichtig, wenn vorhandene Funktionalitäten verändert werden.This capability is typically important when a change is made to existing functionality. Im Gegensatz dazu existiert bereits eine implizite Auswahloption für neue Funktionalitäten.Conversely, there is already an implicit opt-in for new functionality.

AppContext für Bibliotheks EntwicklerAppContext for library developers

Bibliotheken verwenden die AppContext -Klasse, um Kompatibilitäts Switches zu definieren und verfügbar zu machen, während Bibliotheks Benutzer diese Switches festlegen können, um das Verhalten der Bibliothek zu beeinflussen.Libraries use the AppContext class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. Standardmäßig stellen Bibliotheken die neue Funktionalität bereit. Nur wenn die Option festgelegt ist, stellen sie die vorherige Funktionalität bereit.By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. Dadurch können Bibliotheken neues Verhalten für eine vorhandene API bereitstellen und gleichzeitig Aufrufer weiterhin unterstützen, die vom vorherigen Verhalten abhängen.This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior.

Definieren des switchnamensDefining the switch name

Die gängigste Methode, mit der Consumer Ihrer Bibliothek eine Änderung des Verhaltens ablehnen können, besteht darin, einen benannten Switch zu definieren.The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. Das zugehörige- Boolean ElementisteinName-Wert-Paar,dasausdemNameneinesSchaltersundseinemWertbesteht.valueIts value element is a name/value pair that consists of the name of a switch and its Boolean value. Standardmäßig ist der Switch immer implizit false, der das neue Verhalten bereitstellt (und das neue Verhalten standardmäßig aktiviert).By default, the switch is always implicitly false, which provides the new behavior (and makes the new behavior opt-in by default). Wenn Sie den Schalter true auf festlegen, wird dieser aktiviert, was das Legacy Verhalten bereitstellt.Setting the switch to true enables it, which provides the legacy behavior. Wenn Sie den Schalter explizit false auf festlegen, wird auch das neue Verhalten bereitstellt.Explicitly setting the switch to false also provides the new behavior.

Die Verwendung eines konsistenten Formats für Switchnamen ist von Vorteil, da Sie ein formaler Vertrag sind, der von einer Bibliothek verfügbar gemacht wird.It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. Das folgende Beispiel zeigt zwei offensichtliche Formate.The following are two obvious formats.

  • Switch.namespace.switchnameSwitch.namespace.switchname

  • Switch.library.switchnameSwitch.library.switchname

Nachdem Sie den Switch definiert und dokumentiert haben, können Aufrufer ihn mithilfe der Registrierung verwenden, indem Sie der Anwendungs Konfigurationsdatei ein <appcontextionwitchoverrides-> Element hinzufügen AppContext.SetSwitch(String, Boolean) , oder indem Sie die-Methode Programm gesteuert aufrufen.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. Weitere Informationen zur Verwendung von Aufrufern und zum Festlegen des Werts von AppContext Konfigurations Schaltern finden Sie im Abschnitt appContext for Library Consumers .See the AppContext for library consumers section for more information about how callers use and set the value of AppContext configuration switches.

Wenn das Common Language Runtime eine Anwendung ausführt, liest es automatisch die Kompatibilitäts Einstellungen der Registrierung und lädt die Anwendungs Konfigurationsdatei, um die AppContext Instanz der Anwendung aufzufüllen.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. Da die AppContext Instanz entweder Programm gesteuert vom Aufrufer oder von der Laufzeit aufgefüllt wird, müssen Sie keine Aktion ausführen, wie z. b. das SetSwitch Aufrufen der-Methode, AppContext um die Instanz zu konfigurieren.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.

Überprüfen der EinstellungChecking the setting

Sie können dann überprüfen, ob ein Consumer den Wert des Schalters deklariert hat und ordnungsgemäß reagieren AppContext.TryGetSwitch , indem Sie die-Methode aufrufen.You can then check if a consumer has declared the value of the switch and act appropriately by calling the AppContext.TryGetSwitch method. Die-Methode true gibt zurück switchName , wenn das-Argument gefunden wird, und wenn isEnabled die-Methode zurückgibt, gibt das-Argument den Wert des Schalters an.The method returns true if the switchName argument is found, and when the method returns, its isEnabled argument indicates the value of the switch. Andernfalls gibt diese Methode false zurück.Otherwise, the method returns false.

BeispielAn example

Im folgenden Beispiel wird die Verwendung AppContext der-Klasse veranschaulicht, um dem Kunden zu ermöglichen, das ursprüngliche Verhalten einer Bibliotheks Methode auszuwählen.The following example illustrates the use of the AppContext class to allow the customer to choose the original behavior of a library method. Im folgenden finden Sie die Version 1,0 einer Bibliothek StringLibrarymit dem Namen.The following is version 1.0 of a library named StringLibrary. Es definiert eine SubstringStartsAt Methode, die einen Ordinalvergleich durchführt, um den Start Index einer Teil Zeichenfolge innerhalb einer größeren Zeichenfolge zu bestimmen.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

Im folgenden Beispiel wird dann die Bibliothek verwendet, um den Start Index der Teil Zeichenfolge "archæ" in "The Archäologin" zu suchen.The following example then uses the library to find the starting index of the substring "archæ" in "The archaeologist". Da die Methode einen Ordinalvergleich durchführt, kann die Teil Zeichenfolge nicht gefunden werden.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'

In Version 2 der Bibliothek wird jedoch die SubstringStartsAt -Methode so geändert, dass Kultur abhängige Vergleiche verwendet werden.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

Wenn die APP für die Ausführung mit der neuen Version der Bibliothek neu kompiliert wird, meldet Sie nun, dass sich die Teil Zeichenfolge "archæ" Unterindex 4 in "The Archäologin" befindet.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

Diese Änderung kann verhindert werden, wenn die Anwendungen, die vom ursprünglichen Verhalten abhängen, durch Definieren eines <appcontextwitchoverrides-> Schalters unterbrochen werden.This change can be prevented from breaking the applications that depend on the original behavior by defining an <AppContextSwitchOverrides> switch. In diesem Fall wird der Schalter benannt StringLibrary.DoNotUseCultureSensitiveComparison.In this case, the switch is named StringLibrary.DoNotUseCultureSensitiveComparison. Der Standardwert false,, gibt an, dass die Bibliothek den Kultur abhängigen Vergleich der Version 2,0 durchführen soll.Its default value, false, indicates that the library should perform its version 2.0 culture-sensitive comparison. trueGibt an, dass die Bibliothek den Ordinalvergleich der Version 1,0 durchführen soll.true indicates that the library should perform its version 1.0 ordinal comparison. Eine geringfügige Änderung des vorangehenden Codes ermöglicht es dem Bibliotheksconsumer, den Schalter festzulegen, um die Art des Vergleichs zu bestimmen, den die Methode ausführt.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

Wenn die Anwendung die folgende Konfigurationsdatei verwenden kann, um das Verhalten der Version 1,0 wiederherzustellen.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>

Wenn die Anwendung mit der Konfigurationsdatei ausgeführt wird, wird die folgende Ausgabe erzeugt:When the application is run with the configuration file present, it produces the following output:

'archæ' not found in 'The archaeologist'

AppContext für BibliotheksconsumerAppContext for library consumers

Wenn Sie der Consumer einer Bibliothek sind, können Sie AppContext mit der-Klasse den Opt-Out-Mechanismus einer Bibliothek oder Bibliothek Methode für neue Funktionen nutzen.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. Einzelne Methoden der Klassenbibliothek, die Sie aufrufen, definieren bestimmte Switches, die ein neues Verhalten aktivieren oder deaktivieren.Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. Der Wert des Schalters ist ein boolescher Wert.The value of the switch is a Boolean. Wenn dies der falseFall ist, was in der Regel der Standardwert ist, wird das neue Verhalten aktiviert true. ist dies der Fall, wird das neue Verhalten deaktiviert, und der Member verhält sich wie zuvor.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.

Sie können den Wert eines Schalters auf eine von vier weisen festlegen:You can set the value of a switch in one of four ways:

  • Durch Aufrufen der AppContext.SetSwitch(String, Boolean) -Methode in Ihrem Code.By calling the AppContext.SetSwitch(String, Boolean) method in your code. Das switchName -Argument definiert den Switchnamen, und isEnabled die-Eigenschaft definiert den Wert des Schalters.The switchName argument defines the switch name, and the isEnabled property defines the value of the switch. Da AppContext eine statische Klasse ist, ist Sie pro Anwendungsdomäne verfügbar.Because AppContext is a static class, it is available on a per-application domain basis.

    Der Aufruf AppContext.SetSwitch(String, Boolean) von weist den Anwendungsbereich auf, d. h. er wirkt sich nur auf die Anwendung aus.Calling the AppContext.SetSwitch(String, Boolean) has application scope; that is, it affects only the application.

  • Durch Hinzufügen <AppContextSwitchOverrides> eines Elements <zum Lauf Zeit > Abschnitt Ihrer Datei "App. config".By adding an <AppContextSwitchOverrides> element to the <runtime> section of your app.config file. Der Switch verfügt über ein einzelnes Attribut value,, dessen Wert eine Zeichenfolge ist, die ein Schlüssel-Wert-Paar darstellt, das sowohl den Namen des Schalters als auch seinen Wert enthält.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.

    Wenn Sie mehrere Switches definieren möchten, trennen Sie das Schlüssel-Wert-Paar jedes Switchs in der <appcontextswitchoverrides - value Eigenschaft des Elements > durch ein Semikolon.To define multiple switches, separate each switch's key/value pair in the <AppContextSwitchOverrides> element's value attribute with a semicolon. In diesem Fall hat das <AppContextSwitchOverrides> -Element das folgende Format:In that case, the <AppContextSwitchOverrides> element has the following format:

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

    Die Verwendung <AppContextSwitchOverrides> des-Elements zum Definieren einer Konfigurationseinstellung hat einen Anwendungsbereich, d. h., Sie wirkt sich nur auf die Anwendung aus.Using the <AppContextSwitchOverrides> element to define a configuration setting has application scope; that is, it affects only the application.

    Hinweis

    Informationen zu den von der .NET Framework definierten Switches finden Sie im <>-Element von appcontextwitchoverrides.For information on the switches defined by the .NET Framework, see the <AppContextSwitchOverrides> element.

  • Durch Hinzufügen eines Zeichen folgen Werts, dessen Name der Name des Schalters HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext zum Schlüssel in der Registrierung ist.By adding a string value whose name is the name of the switch to the HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext key in the registry. Der Wert muss die Zeichen folgen Darstellung eines Boolean -Werts sein, der von der Boolean.Parse -Methode analysiert werden kann, d. h., er muss "true", "true", "false" oder "false" sein.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". Wenn die Laufzeit einen anderen Wert erkennt, wird der Schalter ignoriert.If the runtime encounters any other value, it ignores the switch.

    Die Verwendung der Registrierung zum Definieren AppContext eines Schalters weist einen Computerbereich auf, d. h., er wirkt sich auf jede auf dem Computer laufende Anwendung aus.Using the registry to define an AppContext switch has machine scope; that is, it affects every application running on the machine.

  • Für ASP.NET-Anwendungen fügen Sie dem <appSettings-> Abschnitt der Datei "Web. config" ein <Add > -Element hinzu.For ASP.NET applications, you add an <Add> element to the <appSettings> section of the web.config file. Beispiel:For example:

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

Wenn Sie denselben Switch auf mehr als eine Art und Weise festlegen, ist die Rangfolge, die festlegt, welche Einstellung die anderen Einstellungen überschreibt, wie folgt:If you set the same switch in more than one way, the order of precedence for determining which setting overrides the others is:

  1. Die programmgesteuerte Einstellung.The programmatic setting.

  2. Die Einstellung in der APP-Konfigurationsdatei oder der Datei "Web. config".The setting in the app config file or the web.config file.

  3. Die Registrierungs Einstellung.The registry setting.

Im folgenden finden Sie eine einfache Anwendung, die einen Datei-URI Path.GetDirectoryName an die-Methode übergibt.The following is a simple application that passes a file URI to the Path.GetDirectoryName method. Wenn Sie unter dem .NET Framework 4,6 ausgeführt wird, wird ArgumentException eine file:// ausgelöst, da kein gültiger Teil eines Dateipfads mehr ist.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()

Um das vorherige Verhalten der Methode wiederherzustellen und die Ausnahme zu verhindern, können Sie Switch.System.IO.UseLegacyPathHandling den Schalter der Anwendungs Konfigurationsdatei für das Beispiel hinzufügen: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>

Siehe auchSee also

AppContext-SchalterAppContext switch

Eigenschaften

BaseDirectory

Ruft den Pfadnamen des Basisverzeichnisses ab, das der Assemblyresolver für die Suche nach Assemblys verwendet.Gets the pathname of the base directory that the assembly resolver uses to probe for assemblies.

TargetFrameworkName

Ruft den Namen der Frameworkversion ab, auf die die aktuelle Anwendung abzielt.Gets the name of the framework version targeted by the current application.

Methoden

GetData(String)

Gibt den Wert des benannten Datenelements zurück, das der aktuellen Anwendungsdomäne zugewiesen ist.Returns the value of the named data element assigned to the current application domain.

SetSwitch(String, Boolean)

Legt den Wert eines Schalters fest.Sets the value of a switch.

TryGetSwitch(String, Boolean)

Versucht, den Wert eines Schalters abzurufen.Tries to get the value of a switch.

Gilt für:

Siehe auch