AppContext AppContext AppContext AppContext Class

Definice

Poskytuje členy pro nastavení a načítání dat o kontextu aplikace.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
Dědičnost
AppContextAppContextAppContextAppContext

Poznámky

AppContext Třída umožňuje autorům knihovny poskytovat jednotné odhlášení mechanismus pro nové funkce pro své uživatele.The AppContext class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. Určuje kontrakt volně spárované mezi součástmi, chcete-li komunikovat požadavek výslovného nesouhlasu s.It establishes a loosely-coupled contract between components in order to communicate an opt-out request. Tato funkce je obvykle důležité při změně stávajících funkcí.This capability is typically important when a change is made to existing functionality. Naopak již existuje implicitní vyjádřit výslovný souhlas pro nové funkce.Conversely, there is already an implicit opt-in for new functionality.

AppContext pro vývojáře knihovnyAppContext for library developers

Použití knihovny AppContext třídy a definovat tak a zpřístupnit kompatibility přepínače, zatímco uživatelé knihovny můžete nastavit tyto přepínače ovlivnit chování knihovny.Libraries use the AppContext class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. Ve výchozím nastavení, knihovny přinášejí nové funkce a upravují pouze (to znamená, poskytují funkce pro předchozí) Pokud přepínač nastavený.By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. To umožňuje knihoven a přitom dál podporovat volajícím, které závisí na předchozím chování poskytují nové chování pro existující rozhraní API.This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior.

Definuje název přepínačeDefining the switch name

Nejběžnější způsob, aby spotřebitelé knihovny můžete kdykoliv zrušit změnu v chování je definovat pojmenované přepínače.The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. Jeho value element je dvojice název/hodnota, která se skládá z názvu přepínače a jeho Boolean hodnotu.Its value element is a name/value pair that consists of the name of a switch and its Boolean value. Ve výchozím nastavení, přepínač je vždy implicitně false, který poskytuje nové chování (a díky novému chování vyjádřit výslovný souhlas ve výchozím nastavení).By default, the switch is always implicitly false, which provides the new behavior (and makes the new behavior opt-in by default). Nastavíte přepínač na true umožní, který obsahuje starší verzi chování.Setting the switch to true enables it, which provides the legacy behavior. Explicitním nastavením přepínač na false také poskytuje nové chování.Explicitly setting the switch to false also provides the new behavior.

Je vhodné použít konzistentní formát přepínače názvy, protože jsou formální smlouvu vystavené knihovny.It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. Tady jsou dvě zřejmé formátů.The following are two obvious formats.

  • Přepínač. obor názvů.switchNameSwitch.namespace.switchname

  • Přepínač. Knihovna.switchNameSwitch.library.switchname

Po definování a zdokumentujte přepínač, volající ji můžete použít pomocí registru tak, že přidáte <AppContextSwitchOverrides > prvek k jejich konfigurační soubor aplikace nebo zavoláním AppContext.SetSwitch(String, Boolean) Metoda prostřednictvím kódu programu.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. Najdete v článku AppContext spotřebitelé knihovny části Další informace o použití a nastavte hodnotu volající AppContext konfigurace přepínače.See the AppContext for library consumers section for more information about how callers use and set the value of AppContext configuration switches.

Při spuštění aplikace modul common language runtime automaticky načte nastavení kompatibility v registru a načte konfigurační soubor aplikace, aby bylo možné naplnit aplikace 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. Protože AppContext instance je naplněny programově volajícím nebo modulem runtime, není nutné provádět žádnou akci, jako je například volání SetSwitch metoda konfigurace 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.

Kontrola nastaveníChecking the setting

Potom můžete zkontrolovat, pokud je příjemce deklarovaný hodnotu přepínače a odpovídajícím způsobem volala act AppContext.TryGetSwitch metody.You can then check if a consumer has declared the value of the switch and act appropriately by calling the AppContext.TryGetSwitch method. Metoda vrátí true Pokud switchName nalezen argument, a pokud metoda vrátí, jeho isEnabled argument určuje hodnotu přepínače.The method returns true if the switchName argument is found, and when the method returns, its isEnabled argument indicates the value of the switch. V opačném případě vrátí metoda false.Otherwise, the method returns false.

PříkladAn example

Následující příklad ukazuje použití AppContext třídu, která umožňuje zákazníkům zvolit původní chování metody knihovny.The following example illustrates the use of the AppContext class to allow the customer to choose the original behavior of a library method. Toto je verze 1.0 knihovnu s názvem StringLibrary.The following is version 1.0 of a library named StringLibrary. Definuje SubstringStartsAt metodu, která provádí řadové porovnání k určení počáteční index podřetězce ve větším řetězci.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

Následující příklad použije knihovny najít počáteční index podřetězec "archæ" v "archaeologist".The following example then uses the library to find the starting index of the substring "archæ" in "The archaeologist". Protože metoda provádí řadové porovnání, podřetězec nebyl nalezen.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'

Verze 2 knihovny, ale změní SubstringStartsAt metodu použít porovnání zohledňující jazykovou verzi.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

Při nové kompilaci aplikace ke spouštění na novou verzi knihovny nyní oznámí, že podřetězec "archæ" se nachází na indexu 4 v "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

Tato změna je možné zabránit dopadem na dřívější kód aplikace, které závisí na původním chování tak, že definujete <AppContextSwitchOverrides > přepnout.This change can be prevented from breaking the applications that depend on the original behavior by defining an <AppContextSwitchOverrides> switch. V takovém případě je přepínač s názvem StringLibrary.DoNotUseCultureSensitiveComparison.In this case, the switch is named StringLibrary.DoNotUseCultureSensitiveComparison. Výchozí hodnota, false, označuje, že knihovny by měl provést porovnání citlivé na jazykovou verzi jeho verze 2.0.Its default value, false, indicates that the library should perform its version 2.0 culture-sensitive comparison. true Označuje, že by měl knihovny jeho verze 1.0 ordinálního porovnání.true indicates that the library should perform its version 1.0 ordinal comparison. Drobné změny předchozího kódu umožňuje příjemci knihovny nastavení přepínače určit druh metoda provádí porovnání.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

Pokud aplikace pak můžete použít následující konfigurační soubor k obnovení chování verze 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>

Při spuštění aplikace se nachází konfigurační soubor, vytvoří následující výstup:When the application is run with the configuration file present, it produces the following output:

'archæ' not found in 'The archaeologist'

AppContext spotřebitelé knihovnyAppContext for library consumers

Pokud jsou příjemci knihovny, AppContext třída umožňuje využít knihovny nebo knihovny metoda mechanismus pro nové funkce.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. Jednotlivé metody knihovny tříd, který voláte definovat konkrétní přepínače, které povolí nebo zakáže nové chování.Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. Hodnota přepínače, který je logická hodnota.The value of the switch is a Boolean. Pokud je false, což je obvykle výchozí hodnotu, nové chování je povolené; Pokud je truenové chování zakázáno a člen se chová stejně jako dříve.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.

Můžete nastavit hodnotu přepínače v jedné ze čtyř způsobů:You can set the value of a switch in one of four ways:

  • Při volání AppContext.SetSwitch(String, Boolean) metodě v kódu.By calling the AppContext.SetSwitch(String, Boolean) method in your code. switchName Definuje argument název přepínače a isEnabled hodnota přepínače, který definuje vlastnost.The switchName argument defines the switch name, and the isEnabled property defines the value of the switch. Protože AppContext je statická třída, je k dispozici na základě domény na aplikaci.Because AppContext is a static class, it is available on a per-application domain basis.

    Volání AppContext.SetSwitch(String, Boolean) má oboru aplikace; to znamená, ovlivní pouze aplikace.Calling the AppContext.SetSwitch(String, Boolean) has application scope; that is, it affects only the application.

  • Tak, že přidáte <AppContextSwitchOverrides> elementu <runtime > části souboru app.config.By adding an <AppContextSwitchOverrides> element to the <runtime> section of your app.config file. Přepínač obsahuje atribut jednu value, jehož hodnota je řetězec, který reprezentuje dvojici klíč/hodnota, který obsahuje název přepínače a její hodnotu.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.

    Chcete-li definovat více přepínačů, oddělte každý přepínač dvojice klíč/hodnota v <AppContextSwitchOverrides > elementu value atribut oddělte středníkem.To define multiple switches, separate each switch's key/value pair in the <AppContextSwitchOverrides> element's value attribute with a semicolon. V takovém případě <AppContextSwitchOverrides> element má následující formát:In that case, the <AppContextSwitchOverrides> element has the following format:

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

    Použití <AppContextSwitchOverrides> prvek, který chcete definovat nastavení konfigurace s rozsahem aplikace; to znamená, ovlivní pouze aplikace.Using the <AppContextSwitchOverrides> element to define a configuration setting has application scope; that is, it affects only the application.

    Poznámka

    Informace o přepínačích definována v rámci rozhraní .NET najdete v tématu <AppContextSwitchOverrides > element.For information on the switches defined by the .NET Framework, see the <AppContextSwitchOverrides> element.

  • Přidejte hodnotu řetězce, jehož název je název přepínače na HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext klíče v registru.By adding a string value whose name is the name of the switch to the HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext key in the registry. Její hodnota musí být řetězcové vyjádření Boolean , který může být analyzován metodou Boolean.Parse metoda; to znamená, musí být "True", "PRAVDA", "False" nebo "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". Pokud modul runtime, zaznamená jakoukoli jinou hodnotu, ignoruje přepínač.If the runtime encounters any other value, it ignores the switch.

    Definování pomocí registru AppContext přepínače má v oboru počítače; to znamená, ovlivní všechny aplikace spuštěné na počítači.Using the registry to define an AppContext switch has machine scope; that is, it affects every application running on the machine.

  • Pro aplikace ASP.NET, přidáte <Přidat > elementu <appSettings > část souboru web.config.For ASP.NET applications, you add an <Add> element to the <appSettings> section of the web.config file. Příklad:For example:

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

Pokud nastavíte stejnému přepínači více než jedním způsobem, je pořadí priorit pro určení nastavení, které přepíše ostatní:If you set the same switch in more than one way, the order of precedence for determining which setting overrides the others is:

  1. Programové nastavení.The programmatic setting.

  2. Nastavení v konfiguračním souboru aplikace nebo souboru web.config.The setting in the app config file or the web.config file.

  3. Nastavení registru.The registry setting.

Tady je jednoduchou aplikaci, která předá soubor identifikátoru URI k Path.GetDirectoryName metoda.The following is a simple application that passes a file URI to the Path.GetDirectoryName method. Při spuštění v rozhraní .NET Framework 4.6 se vyvolá ArgumentException protože file:// již není platný část cesty k souboru.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()

Chcete-li obnovit předchozí chování metody a zabránit výjimky, můžete přidat Switch.System.IO.UseLegacyPathHandling přepnout do konfiguračního souboru aplikace, například: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>

Viz také:See also

Přepínač AppContextAppContext switch

Vlastnosti

BaseDirectory BaseDirectory BaseDirectory BaseDirectory

Získá cestu ze základního adresáře, který používá překladač sestavení pro sběr dat pro sestavení.Gets the pathname of the base directory that the assembly resolver uses to probe for assemblies.

TargetFrameworkName TargetFrameworkName TargetFrameworkName TargetFrameworkName

Získá název verze rozhraní framework cílem aktuální aplikace.Gets the name of the framework version targeted by the current application.

Metody

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

Vrátí hodnotu s názvem datový element přiřazené do aktuální domény aplikace.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)

Nastaví hodnotu přepínače.Sets the value of a switch.

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

Pokusí se získat hodnotu přepínače.Tries to get the value of a switch.

Platí pro

Viz také