Bagikan melalui

Kelas System.AppContext

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 persetujuan implisit untuk fungsionalitas baru.

AppContext untuk pengembang pustaka

Pustaka menggunakan kelas AppContext untuk menentukan dan mengekspos sakelar kompatibilitas, sementara pengguna pustaka dapat menyetel sakelar tersebut untuk memodifikasi perilaku pustaka. Secara bawaan, 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 beroperasi secara implisit false, yang memberikan perilaku baru (dan membuat perilaku baru ini aktif secara default). Mengatur saklar ke true mengaktifkan fungsi tersebut, yang menyediakan fungsi warisan. Dengan mengatur pengalih ke false secara eksplisit, perilaku baru juga akan disediakan.

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

  • Ganti. namespace. switchname
  • Beralih.pustaka.namasakelar

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

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

Periksa pengaturan

Anda dapat memeriksa apakah pengguna telah menyatakan nilai sakelar dan bertindak dengan tepat dengan memanggil metode AppContext.TryGetSwitch. Metode mengembalikan true jika argumen switchName ditemukan, dan argumen 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æ" dalam "The archaeologist". 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($"'{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'

Namun, pustaka versi 2.0 mengubah metode SubstringStartsAt untuk menggunakan perbandingan yang mempertimbangkan 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 dikompilasi ulang untuk dijalankan dengan versi baru pustaka, sekarang melaporkan bahwa substring "archæ" ditemukan di indeks 4 di "sang 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($"'{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

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 versi 2.0 yang sensitif terhadap budaya. true menunjukkan bahwa pustaka harus melakukan perbandingan ordinal versi 1.0. Sedikit modifikasi kode sebelumnya memungkinkan pengguna pustaka untuk mengatur sakelar guna menentukan jenis perbandingan yang dilakukan oleh metode tersebut.

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 pengguna pustaka, kelas AppContext memungkinkan Anda untuk memanfaatkan mekanisme pilihan keluar dari pustaka atau metode pustaka untuk fungsionalitas baru. Metode-metode individu dalam perpustakaan kelas yang Anda panggil menentukan sakelar khusus yang mengaktifkan atau menonaktifkan perilaku baru. Nilai sakelar adalah tipe 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 metode AppContext.SetSwitch(String, Boolean) 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 lingkup aplikasi; dengan kata lain, hal ini hanya memengaruhi aplikasi tersebut.

Aplikasi .NET Framework memiliki cara tambahan untuk mengatur nilai pengalih.

  • 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 dalam <AppContextSwitchOverrides> atribut elemen value 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.

    Nota

    Untuk informasi tentang sakelar yang ditentukan oleh .NET Framework, lihat <AppContextSwitchOverrides> elemen.

  • Dengan menambahkan entri ke registri. Tambahkan nilai string baru ke subkunci HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext. Atur nama entri dengan nama sakelar. Atur nilainya ke salah satu opsi berikut: True, , trueFalse, atau false. Jika runtime menemukan nilai lain, runtime akan mengabaikan peralihan.

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

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

Untuk aplikasi ASP.NET dan ASP.NET Core, Anda mengatur sakelar dengan menambahkan elemen <Add> ke bagian <appSettings> file web.config. Contohnya:

<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 mengungguli yang lain adalah:

  1. Pengaturan secara programmatik.
  2. Pengaturan dalam file app.config (untuk aplikasi .NET Framework) atau file web.config (untuk aplikasi ASP.NET Core).
  3. Pengaturan registri (hanya untuk aplikasi .NET Framework).

Lihat juga

  • Last updated on