Kelas System.AppContext

Artikel
01/08/2024

Artikel ini menyediakan keterangan tambahan untuk dokumentasi referensi untuk API ini.

Kelas ini AppContext memungkinkan penulis pustaka untuk menyediakan mekanisme penolakan seragam untuk fungsionalitas baru bagi pengguna mereka. Ini menetapkan kontrak yang digabungkan secara longgar antara komponen untuk mengkomunikasikan permintaan penolakan. Kemampuan ini biasanya penting ketika perubahan dilakukan pada fungsionalitas yang ada. Sebaliknya, sudah ada keikutsertaan implisit untuk fungsionalitas baru.

AppContext untuk pengembang pustaka

Pustaka menggunakan AppContext kelas untuk menentukan dan mengekspos sakelar kompatibilitas, sementara pengguna pustaka dapat mengatur sakelar tersebut untuk memengaruhi perilaku pustaka. Secara default, pustaka menyediakan fungsionalitas baru, dan mereka hanya mengubahnya (yaitu, mereka menyediakan fungsionalitas sebelumnya) jika sakelar diatur. Ini memungkinkan pustaka untuk memberikan perilaku baru untuk API yang ada sambil terus mendukung penelepon yang bergantung pada perilaku sebelumnya.

Tentukan nama sakelar

Cara paling umum untuk memungkinkan konsumen pustaka Anda menolak perubahan perilaku adalah dengan menentukan sakelar bernama. Elemennya value adalah pasangan nama/nilai yang terdiri dari nama sakelar dan nilainya Boolean . Secara default, sakelar selalu secara falseimplisit , yang menyediakan perilaku baru (dan membuat perilaku baru ikut serta secara default). Mengatur tombol untuk true mengaktifkannya, yang menyediakan perilaku warisan. Secara eksplisit mengatur sakelar untuk false juga menyediakan perilaku baru.

Ini bermanfaat untuk menggunakan format yang konsisten untuk nama switch, karena mereka adalah kontrak formal yang diekspos oleh pustaka. Berikut ini adalah dua format yang jelas:

Switch.namespace.switchname
Switch.library.switchname

Setelah Anda menentukan dan mendokumenkan sakelar, penelepon dapat menggunakannya dengan memanggil AppContext.SetSwitch(String, Boolean) metode secara terprogram. Aplikasi .NET Framework juga dapat menggunakan sakelar dengan menambahkan <elemen AppContextSwitchOverrides> ke file konfigurasi aplikasi mereka atau dengan menggunakan registri. Untuk informasi selengkapnya tentang cara penelepon menggunakan dan mengatur nilai AppContext sakelar konfigurasi, lihat bagian AppContext untuk konsumen pustaka.

Di .NET Framework, ketika runtime bahasa umum menjalankan aplikasi, runtime bahasa umum secara otomatis membaca pengaturan kompatibilitas registri dan memuat file konfigurasi aplikasi untuk mengisi instans aplikasi AppContext . AppContext Karena instans diisi baik secara terprogram oleh pemanggil atau oleh runtime, aplikasi .NET Framework tidak perlu mengambil tindakan apa pun, seperti memanggil SetSwitch metode , untuk mengonfigurasi AppContext instans.

Periksa pengaturan

Anda dapat memeriksa apakah konsumen telah menyatakan nilai sakelar dan bertindak dengan tepat dengan memanggil AppContext.TryGetSwitch metode . Metode mengembalikan true jika switchName argumen ditemukan, dan argumennya isEnabled menunjukkan nilai sakelar. Jika tidak, metode mengembalikan false.

Contoh

Contoh berikut mengilustrasikan penggunaan AppContext kelas untuk memungkinkan pelanggan memilih perilaku asli metode pustaka. Berikut ini adalah versi 1.0 dari pustaka bernama StringLibrary. Ini mendefinisikan SubstringStartsAt metode yang melakukan perbandingan ordinal untuk menentukan indeks awal substring dalam string yang lebih besar.

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

Contoh berikut kemudian menggunakan pustaka untuk menemukan indeks awal substring "archæ" di "Arkeolog". Karena metode melakukan perbandingan ordinal, substring tidak dapat ditemukan.

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'

Namun, pustaka versi 2.0 mengubah SubstringStartsAt metode untuk menggunakan perbandingan yang sensitif terhadap budaya.

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

Ketika aplikasi dikompresi ulang untuk dijalankan terhadap versi baru pustaka, sekarang melaporkan bahwa substring "archæ" ditemukan di indeks 4 di "Arkeolog".

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

Perubahan ini dapat dicegah merusak aplikasi yang bergantung pada perilaku asli dengan menentukan sakelar. Dalam hal ini, sakelar diberi nama StringLibrary.DoNotUseCultureSensitiveComparison. Nilai defaultnya, false, menunjukkan bahwa pustaka harus melakukan perbandingan sensitif budaya versi 2.0. true menunjukkan bahwa pustaka harus melakukan perbandingan ordinal versi 1.0. Sedikit modifikasi kode sebelumnya memungkinkan konsumen pustaka untuk mengatur sakelar untuk menentukan jenis perbandingan yang dilakukan metode.

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

Aplikasi .NET Framework kemudian dapat menggunakan file konfigurasi berikut untuk memulihkan perilaku versi 1.0.

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

Ketika aplikasi dijalankan dengan file konfigurasi yang ada, aplikasi menghasilkan output berikut:

'archæ' not found in 'The archaeologist'

AppContext untuk konsumen pustaka

Jika Anda adalah konsumen pustaka, kelas memungkinkan AppContext Anda memanfaatkan mekanisme penolakan pustaka atau metode pustaka untuk fungsionalitas baru. Metode individual pustaka kelas yang Anda panggil menentukan sakelar tertentu yang mengaktifkan atau menonaktifkan perilaku baru. Nilai sakelar adalah Boolean. Jika adalah false, yang biasanya merupakan nilai default, perilaku baru diaktifkan; jika itu adalah true, perilaku baru dinonaktifkan, dan anggota berulah seperti sebelumnya.

Anda dapat mengatur nilai sakelar dengan memanggil AppContext.SetSwitch(String, Boolean) metode dalam kode Anda. Argumen switchName menentukan nama sakelar, dan isEnabled properti menentukan nilai sakelar. Karena AppContext merupakan kelas statis, kelas ini tersedia berdasarkan domain per aplikasi. Memanggil AppContext.SetSwitch(String, Boolean) memiliki cakupan aplikasi; artinya, hanya memengaruhi aplikasi.

Aplikasi .NET Framework memiliki cara tambahan untuk mengatur nilai sakelar:

Dengan menambahkan <AppContextSwitchOverrides> elemen ke bagian <runtime> file app.config. Sakelar memiliki atribut tunggal, value, yang nilainya adalah string yang mewakili pasangan kunci/nilai yang berisi nama sakelar dan nilainya.

Untuk menentukan beberapa sakelar, pisahkan pasangan kunci/nilai setiap sakelar di <atribut elemen value AppContextSwitchOverrides> dengan titik koma. Dalam hal ini, <AppContextSwitchOverrides> elemen memiliki format berikut:
```
<AppContextSwitchOverrides value="switchName1=value1;switchName2=value2" />
```
<AppContextSwitchOverrides> Menggunakan elemen untuk menentukan pengaturan konfigurasi memiliki cakupan aplikasi; artinya, hanya memengaruhi aplikasi.

Catatan

Untuk informasi tentang sakelar yang ditentukan oleh .NET Framework, lihat <elemen AppContextSwitchOverrides>.
Dengan menambahkan entri ke registri. Tambahkan nilai string baru ke HKLM\SOFTWARE\Microsoft\. SUBKUN NETFramework\AppContext . Atur nama entri ke nama sakelar. Atur nilainya ke salah satu opsi berikut: True, , Falsetrue, atau false. Jika runtime menemukan nilai lain, runtime akan mengabaikan pengalihan.

Pada sistem operasi 64-bit, Anda juga harus menambahkan entri yang sama ke HKLM\SOFTWARE\Wow6432Node\Microsoft\. SUBKUN NETFramework\AppContext .

Menggunakan registri untuk menentukan AppContext sakelar memiliki cakupan mesin; artinya, itu mempengaruhi setiap aplikasi yang berjalan di komputer.

Untuk aplikasi ASP.NET dan ASP.NET Core, Anda mengatur sakelar dengan menambahkan <> tambahkan elemen ke< aplikasi Pengaturan> bagian file web.config. Misalnya:

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

Jika Anda mengatur sakelar yang sama dengan lebih dari satu cara, urutan prioritas untuk menentukan pengaturan mana yang mengambil alih yang lain adalah:

Pengaturan terprogram.
Pengaturan dalam file app.config (untuk aplikasi .NET Framework) atau file web.config (untuk aplikasi ASP.NET Core).
Pengaturan registri (hanya untuk aplikasi .NET Framework).

Bagikan melalui

Kelas System.AppContext

AppContext untuk pengembang pustaka

Tentukan nama sakelar

Periksa pengaturan

Contoh

AppContext untuk konsumen pustaka

Baca juga

Saran dan Komentar

Sumber Daya Tambahan: