AppContext Třída

Definice

public ref class AppContext abstract sealed

public static class AppContext

type AppContext = class

Public Class AppContext

Dědičnost

Object

AppContext

Poznámky

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.

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.

Example

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

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.

Pro ASP.NET Core aplikace nastavíte přepínač přidáním elementu <Add> do oddílu <appSettings> 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:

1. Programové nastavení.
2. Nastavení v souboru web.config (pro aplikace ASP.NET Core).