System.AppContext – třída

Článek
01/08/2024

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 jejich 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í AppContext třídu 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 value element je pár name/value, který se skládá z názvu přepínače a jeho Boolean hodnoty. Ve výchozím nastavení je přepínač vždy implicitně false, který poskytuje nové chování (a ve výchozím nastavení se nové chování přihlásí). Nastavením přepínače true ho povolíte, což poskytuje starší chování. Explicitní nastavení přepínače také false 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řepněte.obor názvů.switchname
Přepněte.knihovna.switchname

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

V rozhraní .NET Framework při spuštění modulu CLR (Common Language Runtime) aplikace automaticky přečte nastavení kompatibility registru a načte konfigurační soubor aplikace, který naplní instanci aplikace AppContext . AppContext Vzhledem k tomu, že je instance naplněna volajícím prostřednictvím kódu programu nebo modulem runtime, nemusí aplikace rozhraní .NET Framework provádět žádnou akci, jako je volání SetSwitch metody, ke konfiguraci AppContext instance.

Kontrola nastavení

Můžete zkontrolovat, jestli příjemce deklaroval hodnotu přepínače, a správně jednat voláním AppContext.TryGetSwitch metody. Metoda vrátí true , pokud switchName je argument nalezen 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í AppContext třídy, která zákazníkovi umožní zvolit původní chování metody knihovny. Následuje verze 1.0 knihovny s názvem StringLibrary. Definuje metodu SubstringStartsAt , 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ězdí "archæ" v "Archeologista". 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("'{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'

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 jazykovou verzi.

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ězeč "archæ" je nalezen v indexu 4 v části "Archeologista".

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("'{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

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

Této změně lze zabránit v porušení aplikací, které závisí na původním chování definováním přepínače. V tomto případě je přepínač pojmenován StringLibrary.DoNotUseCultureSensitiveComparison. Výchozí hodnota označuje, falseže knihovna by měla provádět porovnání s jazykovou verzí 2.0. true označuje, že knihovna by měla provést porovnání verze 1.0 řadového porovnání. 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 příjemcem knihovny, AppContext třída umožňuje využít mechanismus odhlášení knihovny nebo metody knihovny pro nové funkce. 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 falseto , což je obvykle výchozí hodnota, nové chování je povoleno; pokud je true, nové chování je zakázáno a člen se chová stejně jako předtím.

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

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

<AppContextSwitchOverrides> Přidáním elementu< do části modulu runtime> souboru app.config. Přepínač má jeden atribut, valuejehož 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 <elementu value AppContextSwitchOverrides> středníkem. V takovém případě <AppContextSwitchOverrides> má element 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 tématu <AppContextSwitchOverrides> element.
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, False, nebo 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í AppContext přepínače 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 elementu <Add> do <aplikace Nastavení> oddílu souboru web.config. Pří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:

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

Viz také

Přepínač AppContext