AppContext AppContext AppContext AppContext Class

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
AppContextAppContextAppContextAppContext

Hinweise

Die AppContext Klasse ermöglicht Autoren von Bibliotheken, die ihren Benutzern einen einheitlichen abwahlmechanismus für neue Funktionalitäten bereitzustellen.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 Entwickler von BibliothekenAppContext for library developers

Verwenden von Bibliotheken die AppContext Klasse definieren und Bereitstellen von Anwendungskompatibilitäts-wechselt, während der Benutzer diese Optionen beeinflussen das Verhalten der Bibliothek festlegen können.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, um das neues Verhalten für eine vorhandene API bereitstellen, während Sie weiterhin Aufrufer zu unterstützen, die dem bisherigen 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 den Namen des SwitchesDefining the switch name

Die gängigste Methode zum Consumer Ihrer Bibliothek zum Deaktivieren einer Änderung des Verhaltens ermöglichen ist zum Definieren eines angegebenen Schalters.The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. Die value Element ist ein Name/Wert-Paar, das den Namen einer Option besteht und die zugehörige Boolean Wert.Its value element is a name/value pair that consists of the name of a switch and its Boolean value. Standardmäßig die Option ist immer implizit false, bietet das neue Verhalten (und macht das neue Verhalten sich in der Standardeinstellung).By default, the switch is always implicitly false, which provides the new behavior (and makes the new behavior opt-in by default). Festlegen der Option auf true ermöglicht, die das Legacyverhalten bereitstellt.Setting the switch to true enables it, which provides the legacy behavior. Explizites Festlegen der Option zum false bietet auch das neue Verhalten.Explicitly setting the switch to false also provides the new behavior.

Jetzt ist es vorteilhaft, die ein konsistentes Format für die Switch-Namen verwenden, da sie eine formellen Vertrag, der von einer Bibliothek verfügbar gemacht werden können.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

Nach dem definieren und Dokumentieren Sie den Schalter können Aufrufer können sie mithilfe der Registrierungs durch Hinzufügen einer <AppContextSwitchOverrides > Element der Konfigurationsdatei ihrer Anwendung oder durch Aufrufen der AppContext.SetSwitch(String, Boolean) -Methode programmgesteuert.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. Finden Sie unter den AppContext für Bibliotheksconsumer Abschnitt, um weitere Informationen darüber, wie Aufrufer verwenden, und legen Sie den Wert der AppContext Konfigurationsschalter.See the AppContext for library consumers section for more information about how callers use and set the value of AppContext configuration switches.

Wenn die common Language Runtime eine Anwendung ausgeführt wird, wird automatisch der Registrierungs kompatibilitätseinstellungen liest und lädt die Anwendungskonfigurationsdatei zum Auffüllen der Anwendung AppContext Instanz.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 wird entweder programmgesteuert vom Aufrufer oder von der Laufzeit aufgefüllt, Sie müssen keine keinen Aktionen wie ein Aufruf der SetSwitch Methode, die zum Konfigurieren der AppContext Instanz.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 die EinstellungChecking the setting

Sie können Sie überprüfen, ob ein Consumer den Wert des Switches und Act, die entsprechend durch den Aufruf deklariert hat die AppContext.TryGetSwitch Methode.You can then check if a consumer has declared the value of the switch and act appropriately by calling the AppContext.TryGetSwitch method. Gibt die Methode zurück true Wenn die switchName Argument gefunden wird und wenn die Methode zurückgegeben, dessen isEnabled Argument gibt den Wert des Schalters.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

Das folgende Beispiel veranschaulicht die Verwendung der AppContext Klasse, um den Kunden an, wählen Sie das ursprüngliche Verhalten einer Methode für die Bibliothek zu ermöglichen.The following example illustrates the use of the AppContext class to allow the customer to choose the original behavior of a library method. Folgendes ist Version 1.0 von einer Bibliothek namens StringLibrary.The following is version 1.0 of a library named StringLibrary. Definiert eine SubstringStartsAt Methode, die einen Ordinalvergleich, um zu bestimmen, die ab Index einer Teilzeichenfolge innerhalb einer größeren Zeichenfolge ausführt.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 den Anfangsindex der Teilzeichenfolge "Archæ" in "Archaeologist" zu finden.The following example then uses the library to find the starting index of the substring "archæ" in "The archaeologist". Da die Methode einen Ordinalvergleich ausführt, nicht die Teilzeichenfolge 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'

Version 2 der Bibliothek, ändert sich jedoch die SubstringStartsAt zu kulturabhängigen Vergleich zu verwendende Methode.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 erneut kompiliert wird, für die neue Version der Bibliothek ausgeführt wird, meldet es jetzt, der die Teilzeichenfolge "Archæ" Index "4" in "Archaeologist" gefunden wird.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, von den Anwendungen, die auf das ursprüngliche Verhalten abhängig, durch die Definition sind einer <AppContextSwitchOverrides > wechseln.This change can be prevented from breaking the applications that depend on the original behavior by defining an <AppContextSwitchOverrides> switch. In diesem Fall heißt der Switch StringLibrary.DoNotUseCultureSensitiveComparison.In this case, the switch is named StringLibrary.DoNotUseCultureSensitiveComparison. Der Standardwert false, gibt an, dass die Bibliothek der Version 2.0 kulturabhängigen Vergleich durchführen soll.Its default value, false, indicates that the library should perform its version 2.0 culture-sensitive comparison. true Gibt an, dass die Bibliothek der Version 1.0 Ordinalvergleich ausführen soll.true indicates that the library should perform its version 1.0 ordinal comparison. Eine kleine Änderung des obigen Codes ermöglicht es Bibliothek, legen Sie die Umstellung auf die Art des Vergleichs zu bestimmen, die 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 eine Anwendung kann die folgende Konfigurationsdatei verwenden, um das Versionsverhalten 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 vorhanden ausgeführt wird, erzeugt es die folgende Ausgabe:When the application is run with the configuration file present, it produces the following output:

'archæ' not found in 'The archaeologist'

AppContext für ConsumerAppContext for library consumers

Wenn Sie mit der Consumer einer Bibliothek, sind die AppContext Klasse können Sie eine Bibliothek oder Bibliotheksmethode des abwahlmechanismus 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. Bestimmte Schalter, die aktivieren oder deaktivieren ein neues Verhalten definieren, einzelne Methoden der Klassenbibliothek, die Sie aufrufen.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. Ist dies false, die normalerweise der Standardwert ist, wird das neue Verhalten aktiviert ist; wenn es sich handelt true, die das neue Verhalten ist deaktiviert und das Element 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 vier Arten festlegen:You can set the value of a switch in one of four ways:

  • Durch Aufrufen der AppContext.SetSwitch(String, Boolean) Methode im Code.By calling the AppContext.SetSwitch(String, Boolean) method in your code. Die switchName Argument definiert den Namen des Switches, und die isEnabled 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 ist eine statische Klasse, ist es auf einer Basis pro Anwendungsdomäne verfügbar.Because AppContext is a static class, it is available on a per-application domain basis.

    Aufrufen der AppContext.SetSwitch(String, Boolean) hat Anwendungsbereich; d.h., sie wirkt sich auf nur die Anwendung.Calling the AppContext.SetSwitch(String, Boolean) has application scope; that is, it affects only the application.

  • Durch das Hinzufügen einer <AppContextSwitchOverrides> Element der <Runtime > -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, deren Wert ist eine Zeichenfolge, die ein Schlüssel/Wert-Paar, das mit den Namen des Switches und den Wert darstellt.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.

    Um mehrere Switches zu definieren, trennen Sie jeden Schalter des Schlüssel-Wert-Paar in der <AppContextSwitchOverrides > des Elements value Attribut mit einem 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 die <AppContextSwitchOverrides> Element weist das folgende Format:In that case, the <AppContextSwitchOverrides> element has the following format:

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

    Mithilfe der <AppContextSwitchOverrides> -Element zum Definieren einer Konfigurationseinstellung ist Anwendungsbereich; d.h., sie wirkt sich auf nur die Anwendung.Using the <AppContextSwitchOverrides> element to define a configuration setting has application scope; that is, it affects only the application.

    Hinweis

    Informationen auf den Switches, die von .NET Framework definiert werden, finden Sie unter den <AppContextSwitchOverrides >-Element.For information on the switches defined by the .NET Framework, see the <AppContextSwitchOverrides> element.

  • Durch das Hinzufügen eines String-Wert, dessen Name der Name des Schalters ist, der HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext -Schlüssel in der Registrierung.By adding a string value whose name is the name of the switch to the HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext key in the registry. Muss sein Wert die Zeichenfolgendarstellung einer Boolean , die analysiert werden kann, indem die Boolean.Parse -Methode, d. h., es muss "True", "true", "False" oder "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". Wenn die Runtime einen anderen Wert auftritt, wird den Schalter ignoriert.If the runtime encounters any other value, it ignores the switch.

    Verwenden die Registrierung zum Definieren einer AppContext Switch verfügt über die Computerebene, d. h., sie wirkt sich auf jede Anwendung, die auf dem Computer ausgeführt.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 eine <hinzufügen > Element der <AppSettings > -Abschnitt der Datei "Web.config".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 den gleichen Switch auf mehrere Weise festlegen, ist die Reihenfolge zu bestimmen, welche Einstellung die anderen überschreibt: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 Datei "App.config" oder die Datei "Web.config".The setting in the app config file or the web.config file.

  3. Die registrierungseinstellung.The registry setting.

Im folgenden finden Sie eine einfache Anwendung, die einen Datei-URI übergeben, die Path.GetDirectoryName Methode.The following is a simple application that passes a file URI to the Path.GetDirectoryName method. Wenn unter .NET Framework 4.6 ausgeführt werden, sie löst eine ArgumentException da file:// ist nicht mehr ein gültiger Teil einen Dateipfad.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 der Methode, vorherige Verhalten wiederherstellen, und die Ausnahme zu verhindern, können Sie Hinzufügen der Switch.System.IO.UseLegacyPathHandling wechseln Sie zur Konfigurationsdatei Anwendung für das Beispiel: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 BaseDirectory BaseDirectory 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 TargetFrameworkName TargetFrameworkName 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) GetData(String) GetData(String) 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) SetSwitch(String, Boolean) SetSwitch(String, Boolean) SetSwitch(String, Boolean)

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

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

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

Gilt für:

Siehe auch