System.AppContext – třída

Tento článek obsahuje doplňující poznámky k referenční dokumentaci pro toto rozhraní API.

Třída AppContext umožňuje autorům knihoven poskytovat jednotný mechanismus odhlášení pro nové funkce pro své uživatele. Vytvoří volně propojený kontrakt mezi součástmi za účelem sdělení žádosti o odhlášení. Tato funkce je obvykle důležitá, když dojde ke změně stávajících funkcí. Naopak pro nové funkce už existuje implicitní výslovný souhlas.

AppContext pro vývojáře knihoven

Knihovny používají třídu AppContext k definování a zveřejnění přepínačů kompatibility, zatímco uživatelé knihovny mohou tyto přepínače nastavit tak, aby ovlivnily chování knihovny. Ve výchozím nastavení poskytují knihovny nové funkce a mění je pouze (tj. poskytují předchozí funkce), pokud je přepínač nastavený. To umožňuje knihovnám poskytovat nové chování existujícího rozhraní API a zároveň nadále podporovat volající, kteří závisejí na předchozím chování.

Definování názvu přepínače

Nejběžnějším způsobem, jak uživatelům vaší knihovny umožnit vyjádřit výslovný nesouhlas se změnou chování, je definovat pojmenovaný přepínač. Jeho prvek value je dvojice názvu a hodnoty, která se skládá z názvu přepínače a jeho hodnoty Boolean. Ve výchozím nastavení je přepínač vždy false, což poskytuje nové chování (a nové chování je ve výchozím nastavení dostupné). Nastavením přepínače na true ho povolíte, což poskytuje původní chování. Explicitní nastavení přepínače na false také poskytuje nové chování.

Pro názvy přepínačů je výhodné používat konzistentní formát, protože jde o formální kontrakt vystavený knihovnou. Toto jsou dva běžné formáty:

• přepínač.obor názvů.název přepínače
• přepínač.knihovna.název přepínače

Jakmile přepínač definujete a dokumentujete, můžou ho volající používat voláním metody AppContext.SetSwitch(String, Boolean) prostřednictvím kódu programu. Aplikace rozhraní .NET Framework mohou také použít přepínač přidáním elementu <AppContextSwitchOverrides> do konfiguračního souboru aplikace nebo pomocí registru. Další informace o tom, jak volající používají a nastavují hodnotu konfiguračních přepínačů AppContext, najdete v sekci AppContext pro uživatele knihovny.

Když v rozhraní .NET Framework spustí modul clr (Common Language Runtime) aplikaci, automaticky přečte nastavení kompatibility registru a načte konfigurační soubor aplikace, který naplní instanci AppContext aplikace. Vzhledem k tomu, že instance AppContext je naplněna buď programově volajícím, nebo během běhu programu, aplikace rozhraní .NET Framework nemusí provádět žádnou akci, jako je volání metody SetSwitch, aby konfigurovaly instanci AppContext.

Kontrola nastavení

Můžete zkontrolovat, jestli spotřebitel určil hodnotu přepínače, a jednat podle toho tím, že zavoláte metodu AppContext.TryGetSwitch. Metoda vrátí true pokud je nalezen argument switchName a jeho isEnabled argument označuje hodnotu přepínače. V opačném případě metoda vrátí false.

Příklad

Následující příklad ukazuje použití třídy AppContext, aby zákazník mohl zvolit původní chování metody knihovny. Následuje verze 1.0 knihovny s názvem StringLibrary. Definuje SubstringStartsAt metodu, která provádí řadové porovnání a určuje počáteční index podřetězce v rámci většího řetězce.

using System;
using System.Reflection;

[assembly: AssemblyVersion("1.0.0.0")]

public static class StringLibrary1
{
    public static int SubstringStartsAt(string fullString, string substr)
    {
        return fullString.IndexOf(substr, StringComparison.Ordinal);
    }
}

open System
open System.Reflection

[<assembly: AssemblyVersion("1.0.0.0")>]
do ()

module StringLibrary =
    let substringStartsAt (fullString: string) (substr: string) =
        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 pak použije knihovnu k nalezení počátečního indexu podřetězce "archæ" v "Archeologovi". Vzhledem k tomu, že metoda provádí řadové porovnání, nelze nalézt podřetězence.

using System;

public class Example1
{
    public static void Main()
    {
        string value = "The archaeologist";
        string substring = "archæ";
        int position = StringLibrary1.SubstringStartsAt(value, substring);
        if (position >= 0)
            Console.WriteLine($"'{substring}' found in '{value}' starting at position {position}");
        else
            Console.WriteLine($"'{substring}' not found in '{value}'");
    }
}
// The example displays the following output:
//       'archæ' not found in 'The archaeologist'

let value = "The archaeologist"
let substring = "archæ"

let position =
    StringLibrary.substringStartsAt value substring

if position >= 0 then
    printfn $"'{substring}' found in '{value}' starting at position {position}"
else
    printfn $"'{substring}' not found in '{value}'"

// The example displays the following output:
//       'archæ' not found in 'The archaeologist'

Public Module Example4
    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.0 knihovny však změní metodu SubstringStartsAt tak, aby používala porovnání citlivé na kulturní prostředí.

using System;
using System.Reflection;

[assembly: AssemblyVersion("2.0.0.0")]

public static class StringLibrary2
{
    public static int SubstringStartsAt(string fullString, string substr)
    {
        return fullString.IndexOf(substr, StringComparison.CurrentCulture);
    }
}

open System
open System.Reflection

[<assembly: AssemblyVersion("2.0.0.0")>]
do ()

module StringLibrary =
    let substringStartsAt (fullString: string) (substr: string) =
        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

Když je aplikace znovu kompilována tak, aby běžela na nové verzi knihovny, nyní hlásí, že podřetězec "archæ" je nalezen v indexu 4 v části "The archaeologist".

using System;

public class Example2
{
    public static void Main()
    {
        string value = "The archaeologist";
        string substring = "archæ";
        int position = StringLibrary2.SubstringStartsAt(value, substring);
        if (position >= 0)
            Console.WriteLine($"'{substring}' found in '{value}' starting at position {position}");
        else
            Console.WriteLine($"'{substring}' not found in '{value}'");
    }
}
// The example displays the following output:
//       'archæ' found in 'The archaeologist' starting at position 4

let value = "The archaeologist"
let substring = "archæ"

let position =
    StringLibrary.substringStartsAt value substring

if position >= 0 then
    printfn $"'{substring}' found in '{value}' starting at position {position}"
else
    printfn $"'{substring}' not found in '{value}'"

// The example displays the following output:
//       'archæ' found in 'The archaeologist' starting at position 4

Public Module Example6
    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

Změně, která by mohla narušit fungování aplikací závislých na původním chování, lze zabránit definováním spínače. V tomto případě se přepínač jmenuje StringLibrary.DoNotUseCultureSensitiveComparison. Výchozí hodnota falseoznačuje, že knihovna by měla provádět kulturně citlivé porovnání ve verzi 2.0. true označuje, že knihovna by měla provádět porovnání verzí dle pořadí 1.0. Mírná úprava předchozího kódu umožňuje příjemci knihovny nastavit přepínač k určení druhu porovnání, které metoda provádí.

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);
   }
}

open System
open System.Reflection

[<assembly: AssemblyVersion("2.0.0.0")>]
do ()

AppContext.SetSwitch("StringLibrary.DoNotUseCultureSensitiveComparison",true)

module StringLibrary =
    let substringStartsAt (fullString: string) (substr: string) =
        match AppContext.TryGetSwitch "StringLibrary.DoNotUseCultureSensitiveComparison" with 
        | true, true -> fullString.IndexOf(substr, StringComparison.Ordinal)
        | _ -> 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

Aplikace rozhraní .NET Framework pak může k obnovení chování verze 1.0 použít následující konfigurační soubor.

<configuration>
   <runtime>
      <AppContextSwitchOverrides value="StringLibrary.DoNotUseCultureSensitiveComparison=true" />
   </runtime>
</configuration>

Při spuštění aplikace s konfiguračním souborem, který je k dispozici, vytvoří následující výstup:

'archæ' not found in 'The archaeologist'

AppContext pro uživatele knihovny

Pokud jste uživatel knihovny, třída AppContext vám umožňuje využívat mechanismus vypnutí knihovny nebo knihovní metody pro nové funkčnosti. Jednotlivé metody knihovny tříd, kterou voláte, definují konkrétní přepínače, které umožňují nebo zakazují nové chování. Hodnota přepínače je logická hodnota. Pokud je false, což je obvykle výchozí hodnota, je nové chování povoleno; pokud je true, nové chování je zakázané a člen se chová stejně jako předtím.

Hodnotu přepínače můžete nastavit voláním metody AppContext.SetSwitch(String, Boolean) v kódu. Argument switchName definuje název přepínače a vlastnost isEnabled definuje hodnotu přepínače. Vzhledem k tomu, že AppContext je statická třída, je k dispozici v doméně pro jednotlivé aplikace. Volání AppContext.SetSwitch(String, Boolean) má obor působnosti aplikace; to znamená, že ovlivňuje pouze aplikaci.

Aplikace .NET Framework mají další způsoby nastavení hodnoty přepínače:

• Přidáním elementu <AppContextSwitchOverrides> do oddílu <runtime> v souboru app.config. Přepínač má jeden atribut, value, jehož hodnota je řetězec, který představuje dvojici klíč/hodnota obsahující název přepínače i jeho hodnotu.

  Pokud chcete definovat více přepínačů, oddělte dvojici klíč/hodnota každého přepínače v atributu <AppContextSwitchOverrides> elementu value středníkem. V takovém případě má prvek <AppContextSwitchOverrides> následující formát:

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

  Použití elementu <AppContextSwitchOverrides> k definování nastavení konfigurace má obor aplikace; to znamená, že ovlivňuje pouze aplikaci.

  Poznámka:

  Informace o přepínačích definovaných rozhraním .NET Framework naleznete v elementu<AppContextSwitchOverrides>.

• Přidáním položky do registru. Přidejte novou řetězcovou hodnotu do HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext podklíč. Nastavte název položky na název přepínače. Nastavte jeho hodnotu na jednu z následujících možností: True, true, Falsenebo false. Pokud modul runtime narazí na jakoukoli jinou hodnotu, přepínač ignoruje.

  V 64bitovém operačním systému musíte také přidat stejnou položku do HKLM\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\AppContext podklíč.

  Použití registru k definování přepínače AppContext má obor počítače; to znamená, že ovlivňuje každou aplikaci spuštěnou na počítači.

U aplikací ASP.NET a ASP.NET Core nastavíte přepínač přidáním <Add> prvku do <appSettings> části souboru web.config. Například:

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

Pokud nastavíte stejný přepínač více než jedním způsobem, pořadí priorit pro určení, které nastavení přepíše ostatní, je:

1. Programové nastavení.
2. Nastavení v souboru app.config (pro aplikace .NET Framework) nebo web.config (pro aplikace ASP.NET Core).
3. Nastavení registru (pouze pro aplikace rozhraní .NET Framework)

Viz také

• přepínače AppContext