AppContext Klasa

Definicja

Zapewnia członków do ustawiania i pobierania danych dotyczących kontekstu aplikacji.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
Dziedziczenie
AppContext

Uwagi

Klasa AppContext pozwala autorom biblioteki zapewnić jednolity mechanizm rezygnacji dla nowych funkcji dla swoich użytkowników.The AppContext class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. Tworzy luźno rozłączoną umowę między składnikami w celu przekazywania żądania rezygnacji.It establishes a loosely-coupled contract between components in order to communicate an opt-out request. Ta funkcja jest zwykle ważna w przypadku zmiany istniejącej funkcji.This capability is typically important when a change is made to existing functionality. Z drugiej strony istnieje już niejawny wybór dla nowych funkcji.Conversely, there is already an implicit opt-in for new functionality.

AppContext dla deweloperów bibliotekiAppContext for library developers

Biblioteki używają klasy AppContext do definiowania i uwidaczniania przełączników zgodności, podczas gdy użytkownicy biblioteki mogą ustawiać te przełączniki na wpływ na zachowanie biblioteki.Libraries use the AppContext class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. Domyślnie biblioteki udostępniają nowe funkcje i zmieniają je (to oznacza, że zapewniają poprzednie funkcje), jeśli przełącznik jest ustawiony.By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. Dzięki temu biblioteki mogą udostępniać nowe zachowanie dla istniejącego interfejsu API, a jednocześnie obsługiwać wywołujących, którzy zależą od poprzedniego zachowania.This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior.

Definiowanie nazwy przełącznikaDefining the switch name

Najbardziej typowym sposobem zezwalania klientom biblioteki na rezygnację z zmiany zachowania jest zdefiniowanie nazwanego przełącznika.The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. Jego element value to para nazwa/wartość, która składa się z nazwy przełącznika i jego wartości Boolean.Its value element is a name/value pair that consists of the name of a switch and its Boolean value. Domyślnie przełącznik jest zawsze niejawnie false, który zapewnia nowe zachowanie (i sprawia, że nowe zachowanie jest domyślnie włączone).By default, the switch is always implicitly false, which provides the new behavior (and makes the new behavior opt-in by default). Ustawienie przełącznika na true włącza go, co zapewnia starsze zachowanie.Setting the switch to true enables it, which provides the legacy behavior. Jawne ustawienie przełącznika do false również udostępnia nowe zachowanie.Explicitly setting the switch to false also provides the new behavior.

Korzystne jest użycie spójnego formatu nazw przełączników, ponieważ są one formalnym kontraktem udostępnianym przez bibliotekę.It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. Poniżej przedstawiono dwa oczywiste formaty.The following are two obvious formats.

  • Przełącznik. przestrzeń nazw. przełączniknameSwitch.namespace.switchname

  • Przełącznik. Biblioteka. przełączniknameSwitch.library.switchname

Po zdefiniowaniu i udokumentowaniu przełącznika obiekty wywołujące mogą używać go przy użyciu rejestru przez dodanie elementu <AppContextSwitchOverrides > do pliku konfiguracji aplikacji lub przez wywołanie metody AppContext.SetSwitch(String, Boolean).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. Aby uzyskać więcej informacji na temat sposobu używania metod wywołujących i ustawiania wartości AppContext przełączników konfiguracji, zobacz sekcję 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.

Gdy środowisko uruchomieniowe języka wspólnego uruchamia aplikację, automatycznie odczytuje ustawienia zgodności rejestru i ładuje plik konfiguracyjny aplikacji w celu wypełnienia wystąpienia AppContext aplikacji.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. Ponieważ wystąpienie AppContext jest wypełniane programowo przez obiekt wywołujący lub przez środowisko uruchomieniowe, nie trzeba podejmować żadnych działań, takich jak wywołanie metody SetSwitch, aby skonfigurować wystąpienie AppContext.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.

Sprawdzanie ustawieniaChecking the setting

Następnie można sprawdzić, czy konsument zadeklaruje wartość przełącznika i odpowiednio działa, wywołując metodę AppContext.TryGetSwitch.You can then check if a consumer has declared the value of the switch and act appropriately by calling the AppContext.TryGetSwitch method. Metoda zwraca true, jeśli zostanie znaleziony argument switchName i gdy metoda zwraca, jego argument isEnabled wskazuje wartość przełącznika.The method returns true if the switchName argument is found, and when the method returns, its isEnabled argument indicates the value of the switch. W przeciwnym razie metoda zwraca false.Otherwise, the method returns false.

PrzykładAn example

Poniższy przykład ilustruje użycie klasy AppContext, aby umożliwić klientowi wybranie oryginalnego zachowania metody biblioteki.The following example illustrates the use of the AppContext class to allow the customer to choose the original behavior of a library method. Poniżej znajduje się wersja 1,0 biblioteki o nazwie StringLibrary.The following is version 1.0 of a library named StringLibrary. Definiuje metodę SubstringStartsAt, która wykonuje porównanie porządkowe, aby określić początkowy indeks podciągu w większym ciągu.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

Poniższy przykład używa biblioteki, aby znaleźć początkowy indeks podciągu "archæ" w "archaeologist".The following example then uses the library to find the starting index of the substring "archæ" in "The archaeologist". Ponieważ metoda wykonuje porównanie porządkowe, nie można odnaleźć podciągu.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'

W wersji 2 biblioteki program zmienia jednak metodę SubstringStartsAt, aby używać porównania z uwzględnieniem kultury.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

Gdy aplikacja jest ponownie kompilowana do uruchamiania w nowej wersji biblioteki, teraz raportuje, że w indeksie 4 w "archaeologist" znaleziono podciąg "archæ".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

Ta zmiana może uniemożliwiać przerwanie działania aplikacji, które są zależne od oryginalnego zachowania przez zdefiniowanie przełącznika <AppContextSwitchOverrides > .This change can be prevented from breaking the applications that depend on the original behavior by defining an <AppContextSwitchOverrides> switch. W takim przypadku przełącznik ma nazwę StringLibrary.DoNotUseCultureSensitiveComparison.In this case, the switch is named StringLibrary.DoNotUseCultureSensitiveComparison. Wartość domyślna, false, wskazuje, że biblioteka powinna wykonać jego wersję 2,0 porównanie z uwzględnieniem kultury.Its default value, false, indicates that the library should perform its version 2.0 culture-sensitive comparison. true wskazuje, że biblioteka powinna wykonywać w wersji 1,0 Porównanie porządkowe.true indicates that the library should perform its version 1.0 ordinal comparison. Niewielka modyfikacja poprzedniego kodu umożliwia odbiorcy biblioteki ustawienie przełącznika w celu określenia rodzaju porównania wykonywanego przez metodę.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

Jeśli aplikacja może następnie użyć następującego pliku konfiguracji do przywrócenia zachowania w wersji 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>

Gdy aplikacja jest uruchomiona z obecnym plikiem konfiguracji, generuje następujące dane wyjściowe:When the application is run with the configuration file present, it produces the following output:

'archæ' not found in 'The archaeologist'

AppContext dla odbiorców bibliotekiAppContext for library consumers

Jeśli jesteś odbiorcą biblioteki, Klasa AppContext umożliwia korzystanie z mechanizmu wycofania biblioteki lub biblioteki dla nowych funkcji.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. Poszczególne metody wywoływanej biblioteki klas definiują określone przełączniki, które włączają lub wyłączają nowe zachowanie.Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. Wartość przełącznika jest wartością logiczną.The value of the switch is a Boolean. Jeśli jest false, co jest zwykle wartością domyślną, nowe zachowanie jest włączone. Jeśli jest true, nowe zachowanie jest wyłączone, a element członkowski zachowuje się tak jak wcześniej.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.

Wartość przełącznika można ustawić na jeden z czterech sposobów:You can set the value of a switch in one of four ways:

  • Wywołując metodę AppContext.SetSwitch(String, Boolean) w kodzie.By calling the AppContext.SetSwitch(String, Boolean) method in your code. Argument switchName definiuje nazwę przełącznika, a właściwość isEnabled definiuje wartość przełącznika.The switchName argument defines the switch name, and the isEnabled property defines the value of the switch. Ponieważ AppContext jest klasą statyczną, jest ona dostępna na poziomie domeny dla aplikacji.Because AppContext is a static class, it is available on a per-application domain basis.

    Wywołanie AppContext.SetSwitch(String, Boolean) ma zakres aplikacji; oznacza to, że dotyczy tylko aplikacji.Calling the AppContext.SetSwitch(String, Boolean) has application scope; that is, it affects only the application.

  • Dodanie elementu <AppContextSwitchOverrides> do sekcji <runtime > pliku App. config.By adding an <AppContextSwitchOverrides> element to the <runtime> section of your app.config file. Przełącznik ma jeden atrybut, value, którego wartość jest ciągiem, który reprezentuje parę klucz/wartość zawierającą zarówno nazwę przełącznika, jak i jego wartość.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.

    Aby zdefiniować wiele przełączników, należy oddzielić pary klucz/wartość poszczególnych przełączników w atrybucie value elementu <AppContextSwitchOverrides > z średnikiem.To define multiple switches, separate each switch's key/value pair in the <AppContextSwitchOverrides> element's value attribute with a semicolon. W takim przypadku element <AppContextSwitchOverrides> ma następujący format:In that case, the <AppContextSwitchOverrides> element has the following format:

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

    Użycie elementu <AppContextSwitchOverrides> do zdefiniowania ustawienia konfiguracji ma zakres aplikacji; oznacza to, że dotyczy tylko aplikacji.Using the <AppContextSwitchOverrides> element to define a configuration setting has application scope; that is, it affects only the application.

    Uwaga

    Aby uzyskać informacje na temat przełączników zdefiniowanych przez .NET Framework, zobacz <AppContextSwitchOverrides > elementu.For information on the switches defined by the .NET Framework, see the <AppContextSwitchOverrides> element.

  • Przez dodanie wartości ciągu, której nazwa to nazwa przełącznika do klucza HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext w rejestrze.By adding a string value whose name is the name of the switch to the HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext key in the registry. Wartość musi być reprezentacją ciągu Boolean, który może być analizowany przez metodę Boolean.Parse; oznacza to, że musi mieć wartość "true", "true", "false" lub "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". Jeśli środowisko uruchomieniowe napotka inną wartość, ignoruje przełącznik.If the runtime encounters any other value, it ignores the switch.

    Użycie rejestru do zdefiniowania przełącznika AppContext ma zakres maszyn; oznacza to, że ma to wpływ na każdą aplikację uruchomioną na komputerze.Using the registry to define an AppContext switch has machine scope; that is, it affects every application running on the machine.

  • W przypadku aplikacji ASP.NET Dodaj <dodaj > do sekcji <> AppSettings w pliku Web. config.For ASP.NET applications, you add an <Add> element to the <appSettings> section of the web.config file. Na przykład:For example:

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

Jeśli ustawisz ten sam przełącznik w więcej niż jeden sposób, kolejność określania ustawień zastąpień innych:If you set the same switch in more than one way, the order of precedence for determining which setting overrides the others is:

  1. Ustawienie programowe.The programmatic setting.

  2. Ustawienie w pliku konfiguracyjnym aplikacji lub w pliku Web. config.The setting in the app config file or the web.config file.

  3. Ustawienie rejestru.The registry setting.

Poniżej przedstawiono prostą aplikację, która przekazuje identyfikator URI pliku do metody Path.GetDirectoryName.The following is a simple application that passes a file URI to the Path.GetDirectoryName method. Gdy jest uruchamiany w .NET Framework 4,6, zgłasza ArgumentException, ponieważ file:// nie jest już prawidłową częścią ścieżki pliku.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()

Aby przywrócić poprzednie zachowanie metody i zapobiec wyjątku, można dodać Switch.System.IO.UseLegacyPathHandling Przełącz do pliku konfiguracji aplikacji na przykład: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>

Zobacz takżeSee also

Przełącznik AppContextAppContext switch

Właściwości

BaseDirectory

Pobiera nazwę ścieżki katalogu podstawowego używanego przez program rozpoznawania zestawu do sondowania dla zestawów.Gets the pathname of the base directory that the assembly resolver uses to probe for assemblies.

TargetFrameworkName

Pobiera nazwę wersji platformy wskazywanej przez bieżącą aplikację.Gets the name of the framework version targeted by the current application.

Metody

GetData(String)

Zwraca wartość nazwanego elementu danych przypisanego do domeny bieżącej aplikacji.Returns the value of the named data element assigned to the current application domain.

SetSwitch(String, Boolean)

Ustawia wartość przełącznika.Sets the value of a switch.

TryGetSwitch(String, Boolean)

Próbuje pobrać wartość przełącznika.Tries to get the value of a switch.

Dotyczy

Zobacz też