System.AppContext-klass

Den här artikeln innehåller ytterligare kommentarer till referensdokumentationen för det här API:et.

Klassen AppContext gör det möjligt för biblioteksförfattare att tillhandahålla en enhetlig opt-out-mekanism för nya funktioner för sina användare. Det upprättar ett löst kopplat kontrakt mellan komponenter för att kommunicera en begäran om avbeställning. Den här funktionen är vanligtvis viktig när en ändring görs i befintliga funktioner. Omvänt finns det redan en implicit opt-in för nya funktioner.

AppContext för biblioteksutvecklare

Bibliotek använder AppContext klassen för att definiera och exponera kompatibilitetsväxlar, medan biblioteksanvändare kan ange att dessa växlar ska påverka biblioteksbeteendet. Som standardinställning tillhandahåller biblioteken de nya funktionerna, och de ändrar den bara (det vill säga, de tillhandahåller den tidigare funktionen) om en inställning är aktiverad. Detta gör det möjligt för bibliotek att tillhandahålla nytt beteende för ett befintligt API samtidigt som de fortsätter att stödja anropare som är beroende av det tidigare beteendet.

Definiera växelnamnet

Det vanligaste sättet att tillåta användare av biblioteket att välja bort en ändring av beteendet är att definiera en namngiven växel. Dess value element är ett namn/värde-par som består av namnet på en växel och dess Boolean värde. Som standard är växeln alltid implicit , vilket ger det nya beteendet false(och gör det nya beteendet att välja som standard). Om du ställer in växeln på true aktiveras den, vilket ger det äldre beteendet. Om du uttryckligen anger växeln till false får du också det nya beteendet.

Det är fördelaktigt att använda ett konsekvent format för bytesnamn, eftersom de är ett formellt kontrakt som exponeras av ett bibliotek. Följande är två uppenbara format:

• Switch.namnområde.switchnamn
• Växla.bibliotek.switchname

När du definierar och dokumenterar brytaren kan anropare använda den genom att programmatiskt kalla på metoden AppContext.SetSwitch(String, Boolean). .NET Framework-appar kan också använda växeln genom att lägga till ett <AppContextSwitchOverrides-element> i programkonfigurationsfilen eller med hjälp av registret. Mer information om hur anropare använder och anger värdet AppContext för konfigurationsväxlar finns i avsnittet AppContext för bibliotekskonsumenter .

I .NET Framework, när den vanliga språkkörningen kör ett program, läser den automatiskt registrets kompatibilitetsinställningar och läser in programkonfigurationsfilen för att fylla i programmets AppContext instans. Eftersom instansen AppContext fylls i antingen programmatiskt av anroparen eller av körningen behöver .NET Framework-appar inte vidta några åtgärder, till exempel att anropa SetSwitch metoden, för att konfigurera instansen AppContext .

Kontrollera inställningen

Du kan kontrollera om en konsument har deklarerat värdet för omkopplaren och agera därefter genom att anropa metoden AppContext.TryGetSwitch. Metoden returnerar true om switchName argumentet hittas och dess isEnabled argument anger värdet för växeln. Annars returnerar falsemetoden .

Exempel

I följande exempel visas hur klassen används AppContext för att kunden ska kunna välja det ursprungliga beteendet för en biblioteksmetod. Följande är version 1.0 av ett bibliotek med namnet StringLibrary. Den definierar en SubstringStartsAt metod som utför en ordningstalsjämförelse för att fastställa startindexet för en delsträng i en större sträng.

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

I följande exempel används sedan biblioteket för att hitta startindexet för understrängen "archæ" i "Arkeologen". Eftersom metoden utför en ordningsjämförelse går det inte att hitta delsträngen.

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'

Version 2.0 av biblioteket ändrar dock metoden så att den SubstringStartsAt använder kulturkänslig jämförelse.

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

När appen omkompileras för att köras mot den nya versionen av biblioteket rapporterar den nu att delsträngen "archæ" finns på index 4 i "Arkeologen".

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

Den här ändringen kan förhindras från att bryta de program som är beroende av det ursprungliga beteendet genom att definiera en växel. I det här fallet heter StringLibrary.DoNotUseCultureSensitiveComparisonväxeln . Dess standardvärde, false, anger att biblioteket ska utföra sin kulturkänsliga jämförelse version 2.0. true anger att biblioteket ska utföra sin ordinalsjämförelse i version 1.0. En liten ändring av den tidigare koden gör att bibliotekskonsumenten kan ange växeln för att fastställa vilken typ av jämförelse metoden utför.

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

Ett .NET Framework-program kan sedan använda följande konfigurationsfil för att återställa version 1.0-beteendet.

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

När programmet körs med konfigurationsfilen som finns genererar det följande utdata:

'archæ' not found in 'The archaeologist'

AppContext för bibliotekskonsumenter

Om du är konsument av ett bibliotek, låter AppContext-klassen dig dra nytta av ett biblioteks eller en biblioteksmetods opt-out-mekanism för ny funktionalitet. Enskilda metoder i klassbiblioteket som du anropar definierar specifika växlar som aktiverar eller inaktiverar ett nytt beteende. Värdet för växeln är booleskt. Om det är false, vilket vanligtvis är standardvärdet, är det nya beteendet aktiverat. Om det är truedet inaktiveras det nya beteendet och medlemmen beter sig som tidigare.

Du kan ange värdet för en växel genom att anropa AppContext.SetSwitch(String, Boolean) metoden i koden. Argumentet switchName definierar växelnamnet och isEnabled egenskapen definierar värdet för växeln. Eftersom AppContext är en statisk klass är den tillgänglig per programdomän. Att anropa AppContext.SetSwitch(String, Boolean) har applikationsomfång, det vill säga att det endast påverkar applikationen.

.NET Framework-appar har ytterligare sätt att ange värdet för en växel:

• Genom att lägga till ett <AppContextSwitchOverrides> element i <körtidsavsnittet> i app.config-filen. Växeln har ett enda attribut, value, vars värde är en sträng som representerar ett nyckel/värde-par som innehåller både växelnamnet och dess värde.

  För att definiera flera växlar separerar du varje växels nyckel/värde-par i attributet < i elementet > med ett semikolon. I så fall har elementet <AppContextSwitchOverrides> följande format:

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

  Att använda -elementet <AppContextSwitchOverrides> för att definiera en konfigurationsinställning har programomfattning, det vill sägs att det endast påverkar programmet.

  Anmärkning

  Information om de växlar som definierats av .NET Framework finns i <Elementet AppContextSwitchOverrides>.

• Genom att lägga till en post i registret. Lägg till ett nytt strängvärde i HKLM\SOFTWARE\Microsoft\. NETFramework\AppContext-undernyckel . Ange namnet på posten till namnet på växeln. Ange värdet till något av följande alternativ: True, true, False, eller false. Om körningen av programmet påträffar något annat värde ignoreras switch-satsen.

  På ett 64-bitars operativsystem måste du också lägga till samma post i HKLM\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\AppContext-undernyckel.

  Att använda registret för att definiera en AppContext växel har datoromfång. Det påverkar alltså alla program som körs på datorn.

För ASP.NET- och ASP.NET Core-program anger du en växel genom att lägga till ett <Lägg till-element> i <avsnittet appInställningar> i web.config-filen. Till exempel:

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

Om du ställer in samma växel på mer än ett sätt är prioritetsordningen för att avgöra vilken inställning som åsidosätter de andra:

1. Den programmatiska inställningen.
2. Inställningen i app.config -filen (för .NET Framework-appar) eller web.config -filen (för ASP.NET Core-appar).
3. Registerinställningen (endast för .NET Framework-appar).

Se även

• AppContext-växel