AppContext Sınıf

Tanım

Bir uygulamanın bağlamı hakkında veri ayarlama ve alma için Üyeler sağlar.Provides members for setting and retrieving data about an application's context.

public ref class AppContext abstract sealed
public static class AppContext
type AppContext = class
Public Class AppContext
Devralma
AppContext

Açıklamalar

AppContextSınıfı, kitaplık yazıcılarının kullanıcıları için yeni işlevler için Tekdüzen bir geri alma mekanizması sağlamasına olanak sağlar.The AppContext class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. Bir kapatma isteğini iletmek için bileşenler arasında gevşek olarak bağlanmış bir sözleşme oluşturur.It establishes a loosely-coupled contract between components in order to communicate an opt-out request. Bu özellik, genellikle mevcut işlevlere bir değişiklik yapıldığında önemlidir.This capability is typically important when a change is made to existing functionality. Buna karşılık, yeni işlevsellik için zaten örtük bir katılım vardır.Conversely, there is already an implicit opt-in for new functionality.

Kitaplık geliştiricileri için AppContextAppContext for library developers

Kitaplıklar, AppContext Uyumluluk anahtarlarını tanımlamak ve kullanıma sunmak için sınıfını kullanır, ancak kitaplık kullanıcıları bu anahtarları kitaplık davranışını etkileyecek şekilde ayarlayabilirler.Libraries use the AppContext class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. Varsayılan olarak, kitaplıklar yeni işlevselliği sağlar ve yalnızca, anahtar ayarlanmışsa (yani, önceki işlevleri sağlar) değiştirir.By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. Bu, kitaplıkların, önceki davranışa bağlı olan çağıranları desteklemeye devam ederken var olan bir API için yeni davranış sağlamasına izin verir.This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior.

Anahtar adını tanımlayınDefine the switch name

Kitaplığınızın tüketicilerinin bir davranış değişikliğini devre dışı bırakmak için en yaygın yol, adlandırılmış bir anahtar tanımlamaktır.The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. valueÖğesi, bir anahtarın adını ve değerini içeren bir ad/değer çiftinden oluşur Boolean .Its value element is a name/value pair that consists of the name of a switch and its Boolean value. Varsayılan olarak, anahtar her zaman örtük olarak belirlenir false , bu da yeni davranışı sağlar (ve yeni davranışı varsayılan olarak kabul yapar).By default, the switch is always implicitly false, which provides the new behavior (and makes the new behavior opt-in by default). Anahtarı, true eski davranışı sağlayan, izin vermek için ayarlama.Setting the switch to true enables it, which provides the legacy behavior. Anahtarı açıkça ayarlamak false yeni davranışı da sağlar.Explicitly setting the switch to false also provides the new behavior.

Bir kitaplık tarafından kullanıma sunulan resmi bir sözleşme olduklarından, anahtar adları için tutarlı bir biçim kullanmak faydalıdır.It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. Aşağıda iki belirgin biçim verilmiştir.The following are two obvious formats.

  • Anahtar. ad alanı. SwitchNameSwitch.namespace.switchname

  • Anahtar. kitaplığı. SwitchNameSwitch.library.switchname

Anahtarı tanımladıktan ve belgeledikten sonra, arayanlar onu kayıt defteri kullanarak, <AppContextSwitchOverrides> uygulama yapılandırma dosyasına bir öğe ekleyerek veya yöntemi programlı bir şekilde çağırarak kullanabilir AppContext.SetSwitch(String, Boolean) .Once you define and document the switch, callers can use it by using the registry, by adding an <AppContextSwitchOverrides> element to their application configuration file, or by calling the AppContext.SetSwitch(String, Boolean) method programmatically. Çağıranların kullanımı ve yapılandırma anahtarlarının değerini ayarlama hakkında daha fazla bilgi için bkz. kitaplık tüketicileri Için AppContext bölümü AppContext .See the AppContext for library consumers section for more information about how callers use and set the value of AppContext configuration switches.

Ortak dil çalışma zamanı bir uygulama çalıştırdığında, kayıt defterinin uyumluluk ayarlarını otomatik olarak okur ve uygulamanın örneğini doldurmak için uygulama yapılandırma dosyasını yükler AppContext .When the common language runtime runs an application, it automatically reads the registry's compatibility settings and loads the application configuration file in order to populate the application's AppContext instance. Örnek, AppContext çağıran tarafından veya çalışma zamanı tarafından programlı olarak doldurulduğundan, SetSwitch örneği yapılandırmak için yöntemini çağırma gibi herhangi bir işlem yapmanız gerekmez AppContext .Because the AppContext instance is populated either programmatically by the caller or by the runtime, you do not have to take any action, such as calling the SetSwitch method, to configure the AppContext instance.

Ayarı denetleyinCheck the setting

Daha sonra, bir tüketicinin anahtarın değerini bildirdiğine ve yöntemini çağırarak uygun şekilde hareket edip ettiği kontrol edebilirsiniz AppContext.TryGetSwitch .You can then check if a consumer has declared the value of the switch and act appropriately by calling the AppContext.TryGetSwitch method. Yöntemi, true switchName bağımsız değişkeni bulunursa ve yöntemi döndürüldüğünde, isEnabled bağımsız değişkeni anahtarın değerini gösterir.The method returns true if the switchName argument is found, and when the method returns, its isEnabled argument indicates the value of the switch. Aksi takdirde, yöntemi döndürür false .Otherwise, the method returns false.

ÖrnekAn example

Aşağıdaki örnek, AppContext müşterinin bir kitaplık yönteminin orijinal davranışını seçmesine izin vermek için sınıfının kullanımını gösterir.The following example illustrates the use of the AppContext class to allow the customer to choose the original behavior of a library method. Aşağıdaki, adlı bir kitaplığın sürüm 1,0 ' dir StringLibrary .The following is version 1.0 of a library named StringLibrary. SubstringStartsAtDaha büyük bir dizedeki alt dizenin başlangıç dizinini belirleyen bir sıralı karşılaştırma gerçekleştiren bir yöntemi tanımlar.It defines a SubstringStartsAt method that performs an ordinal comparison to determine the starting index of a substring within a larger string.

using System;
using System.Reflection;

[assembly: AssemblyVersion("1.0.0.0")]

public static class StringLibrary
{
   public static int SubstringStartsAt(String fullString, String substr)
   {
      return 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

Aşağıdaki örnek, "archæ" alt dizenin başlangıç dizinini "archaeologist" içinde bulmak için kitaplığı kullanır.The following example then uses the library to find the starting index of the substring "archæ" in "The archaeologist". Yöntem bir sıralı karşılaştırma gerçekleştirdiğinden, alt dize bulunamıyor.Because the method performs an ordinal comparison, the substring cannot be found.

using System;

public class Example
{
   public static void Main()
   {
      String value = "The archaeologist";
      String substring = "archæ";
      int position = StringLibrary.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'
Public Module Example
   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'

Bununla birlikte, kitaplığın sürüm 2 ' yi SubstringStartsAt kültüre duyarlı karşılaştırma kullanacak şekilde değiştirir.Version 2 of the library, however, changes the SubstringStartsAt method to use culture-sensitive comparison.

using System;
using System.Reflection;

[assembly: AssemblyVersion("2.0.0.0")]

public static class StringLibrary
{
   public static int SubstringStartsAt(String fullString, String substr)
   {
      return 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

Uygulama, kitaplığın yeni sürümüne karşı çalışmak üzere yeniden derlenmeye hazır olduğunda, artık "archæ" alt dizesini "The archaeologist" içindeki dizin 4 ' te bulunduğunu bildiriyor.When the app is recompiled to run against the new version of the library, it now reports that the substring "archæ" is found at index 4 in "The archaeologist".

using System;

public class Example
{
   public static void Main()
   {
      String value = "The archaeologist";
      String substring = "archæ";
      int position = StringLibrary.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
Public Module Example
   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

Bu değişikliğin, bir anahtar tanımlayarak özgün davranışa bağlı olan uygulamaları bozmasından engellenebilir <AppContextSwitchOverrides> .This change can be prevented from breaking the applications that depend on the original behavior by defining an <AppContextSwitchOverrides> switch. Bu durumda, anahtar olarak adlandırılır StringLibrary.DoNotUseCultureSensitiveComparison .In this case, the switch is named StringLibrary.DoNotUseCultureSensitiveComparison. Varsayılan değeri, false kitaplığın sürüm 2,0 kültüre duyarlı karşılaştırmayı gerçekleştirmesi gerektiğini gösterir.Its default value, false, indicates that the library should perform its version 2.0 culture-sensitive comparison. true Kitaplığın sürüm 1,0 sıra karşılaştırmayı gerçekleştirmesi gerektiğini gösterir.true indicates that the library should perform its version 1.0 ordinal comparison. Önceki kodun küçük bir değişikliği, kitaplık tüketicisinin, yöntemin gerçekleştirdiği karşılaştırma türünü belirleyecek anahtarı ayarlamasına olanak tanır.A slight modification of the previous code allows the library consumer to set the switch to determine the kind of comparison the method performs.

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);
   }
}
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

Uygulama daha sonra sürüm 1,0 davranışını geri yüklemek için aşağıdaki yapılandırma dosyasını kullanabilir.If application can then use the following configuration file to restore the version 1.0 behavior.

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

Uygulama yapılandırma dosyası ile çalıştırıldığında aşağıdaki çıktıyı üretir:When the application is run with the configuration file present, it produces the following output:

'archæ' not found in 'The archaeologist'

Kitaplık tüketicileri için AppContextAppContext for library consumers

Bir kitaplığın tüketicisidir, AppContext sınıfı yeni işlevsellik için bir kitaplık veya kitaplık yönteminin geri çevirme mekanizmasından yararlanmanıza olanak sağlar.If you are the consumer of a library, the AppContext class allows you to take advantage of a library or library method's opt-out mechanism for new functionality. Çağıran sınıf kitaplığının bağımsız yöntemleri, yeni bir davranışı etkinleştiren veya devre dışı bırakan belirli anahtarları tanımlar.Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. Anahtarın değeri bir Boole değeridir.The value of the switch is a Boolean. Bu, false genellikle varsayılan değer olan ise, yeni davranış etkindir; Eğer ise true , yeni davranış devre dışıdır ve üye daha önce olduğu gibi davranır.If it is false, which is typically the default value, the new behavior is enabled; if it is true, the new behavior is disabled, and the member behaves as it did previously.

Anahtar değerini dört şekilde ayarlayabilirsiniz:You can set the value of a switch in one of four ways:

  • AppContext.SetSwitch(String, Boolean)Kodunuzda yöntemini çağırarak.By calling the AppContext.SetSwitch(String, Boolean) method in your code. switchNameBağımsız değişkeni, anahtar adını tanımlar ve isEnabled özelliği anahtarın değerini tanımlar.The switchName argument defines the switch name, and the isEnabled property defines the value of the switch. AppContext, Bir statik sınıf olduğundan, uygulama başına etki alanı temelinde kullanılabilir.Because AppContext is a static class, it is available on a per-application domain basis.

    AppContext.SetSwitch(String, Boolean)Uygulamasının uygulama kapsamı ile çağrılması; yani yalnızca uygulamayı etkiler.Calling the AppContext.SetSwitch(String, Boolean) has application scope; that is, it affects only the application.

  • <AppContextSwitchOverrides>app.config dosyanızın bölümüne bir öğe ekleyerek <runtime> .By adding an <AppContextSwitchOverrides> element to the <runtime> section of your app.config file. Anahtar, value değeri hem anahtar adı hem de değeri içeren bir anahtar/değer çiftini temsil eden bir dize olan tek bir özniteliğe sahiptir.The switch has a single attribute, value, whose value is a string that represents a key/value pair containing both the switch name and its value.

    Birden çok anahtar tanımlamak için, öğenin özniteliğinde her bir anahtarın anahtar/değer çiftini <AppContextSwitchOverrides> value noktalı virgülle ayırın.To define multiple switches, separate each switch's key/value pair in the <AppContextSwitchOverrides> element's value attribute with a semicolon. Bu durumda, <AppContextSwitchOverrides> öğesi aşağıdaki biçimdedir:In that case, the <AppContextSwitchOverrides> element has the following format:

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

    <AppContextSwitchOverrides>Bir yapılandırma ayarı tanımlamak için öğesini kullanmak uygulama kapsamına sahiptir; diğer bir deyişle, yalnızca uygulamayı etkiler.Using the <AppContextSwitchOverrides> element to define a configuration setting has application scope; that is, it affects only the application.

    Not

    .NET Framework tarafından tanımlanan anahtarlar hakkında daha fazla bilgi için, bkz. <AppContextSwitchOverrides> öğesi.For information on the switches defined by the .NET Framework, see the <AppContextSwitchOverrides> element.

  • Kayıt defterine bir girdi eklenerek.By adding an entry to the registry. Hklm\software\microsoft . Netframework\appcontext alt anahtarına yeni bir dize değeri ekleyin.Add a new string value to the HKLM\SOFTWARE\Microsoft.NETFramework\AppContext subkey. Girdinin adını anahtarın adı olarak ayarlayın.Set the name of the entry to the name of the switch. Değerini şu seçeneklerden birine ayarlayın: True , true , False veya false .Set its value to one of the following options: True, true, False, or false. Çalışma zamanı başka bir değerle karşılaşırsa, anahtarı yoksayar.If the runtime encounters any other value, it ignores the switch.

    64 bitlik bir işletim sisteminde, Hklm\software\wow6432node\microsoft . Netframework\appcontext alt anahtarına aynı girişi de eklemeniz gerekir.On a 64-bit operating system, you must also add the same entry to the HKLM\SOFTWARE\Wow6432Node\Microsoft.NETFramework\AppContext subkey.

    Bir anahtarı tanımlamak için kayıt defterinin kullanılması AppContext makine kapsamına sahiptir; diğer bir deyişle, makinede çalışan her uygulamayı etkiler.Using the registry to define an AppContext switch has machine scope; that is, it affects every application running on the machine.

  • ASP.NET uygulamaları için <Add> <appSettings> web.config dosyanın bölümüne bir öğesi eklersiniz.For ASP.NET applications, you add an <Add> element to the <appSettings> section of the web.config file. Örnek:For example:

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

Aynı anahtarı birden çok şekilde ayarlarsanız, diğerlerini geçersiz kılan ayarı belirlemek için öncelik sırası şunlardır:If you set the same switch in more than one way, the order of precedence for determining which setting overrides the others is:

  1. Programlı ayar.The programmatic setting.

  2. Uygulama yapılandırma dosyasındaki ayar veya web.config dosyası.The setting in the app config file or the web.config file.

  3. Kayıt defteri ayarı.The registry setting.

Bir dosya URI 'sini yöntemine geçiren basit bir uygulama aşağıda verilmiştir Path.GetDirectoryName .The following is a simple application that passes a file URI to the Path.GetDirectoryName method. .NET Framework 4,6 altında çalıştırıldığında, bir ArgumentException file:// dosya yolunun artık geçerli bir parçası olmadığı için bir oluşturur.When run under the .NET Framework 4.6, it throws an ArgumentException because file:// is no longer a valid part of a file path.

using System;
using System.IO;
using System.Runtime.Versioning;

[assembly:TargetFramework(".NETFramework,Version=v4.6.2")]

public class Example
{
   public static void Main()
   {
      Console.WriteLine(Path.GetDirectoryName("file://c/temp/dirlist.txt"));
   }
}
// The example displays the following output:
//    Unhandled Exception: System.ArgumentException: The path is not of a legal form.
//       at System.IO.Path.NewNormalizePathLimitedChecks(String path, Int32 maxPathLength, Boolean expandShortPaths)
//       at System.IO.Path.NormalizePath(String path, Boolean fullCheck, Int32 maxPathLength, Boolean expandShortPaths)
//       at System.IO.Path.InternalGetDirectoryName(String path)
//       at Example.Main()
Imports System.IO
Imports System.Runtime.Versioning

<assembly:TargetFramework(".NETFramework,Version=v4.6.2")>

Module Example
   Public Sub Main()
      Console.WriteLine(Path.GetDirectoryName("file://c/temp/dirlist.txt")) 
   End Sub
End Module
' The example displays the following output:
'    Unhandled Exception: System.ArgumentException: The path is not of a legal form.
'       at System.IO.Path.NewNormalizePathLimitedChecks(String path, Int32 maxPathLength, Boolean expandShortPaths)
'       at System.IO.Path.NormalizePath(String path, Boolean fullCheck, Int32 maxPathLength, Boolean expandShortPaths)
'       at System.IO.Path.InternalGetDirectoryName(String path)
'       at Example.Main()

Yöntemin önceki davranışını geri yüklemek ve özel durumu engellemek için, Switch.System.IO.UseLegacyPathHandling anahtarı uygulama yapılandırma dosyasına ekleyebilirsiniz:To restore the method's previous behavior and prevent the exception, you can add the Switch.System.IO.UseLegacyPathHandling switch to the application configuration file for the example:

<configuration>
    <runtime>
        <AppContextSwitchOverrides value="Switch.System.IO.UseLegacyPathHandling=true" />
    </runtime>
</configuration>

Ayrıca bkz.See also

AppContext anahtarıAppContext switch

Özellikler

BaseDirectory

Derleme Çözümleyicisinin derlemeleri araştırmada kullandığı temel dizinin dosya yolunu alır.Gets the file path of the base directory that the assembly resolver uses to probe for assemblies.

TargetFrameworkName

Geçerli uygulamanın hedeflediği Çerçeve sürümünün adını alır.Gets the name of the framework version targeted by the current application.

Yöntemler

GetData(String)

Geçerli uygulama etki alanına atanan adlandırılmış veri öğesinin değerini döndürür.Returns the value of the named data element assigned to the current application domain.

SetSwitch(String, Boolean)

Bir anahtarın değerini ayarlar.Sets the value of a switch.

TryGetSwitch(String, Boolean)

Bir anahtarın değerini almaya çalışır.Tries to get the value of a switch.

Şunlara uygulanır