AppContext AppContext AppContext AppContext Class

Определение

Предоставляет члены для задания и получения данных о контексте приложения.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
Наследование
AppContextAppContextAppContextAppContext

Комментарии

AppContext Класс позволяет авторам библиотек предоставлять согласованный механизм явного отказа для новых функциональных возможностей для своих пользователей.The AppContext class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. Он устанавливает слабо связанный контракт между компонентами для передачи запроса на явный отказ.It establishes a loosely-coupled contract between components in order to communicate an opt-out request. Эта возможность обычно важна при внесении изменений в существующие функции.This capability is typically important when a change is made to existing functionality. В свою очередь, режим неявного согласия для новых функциональных возможностей уже существует.Conversely, there is already an implicit opt-in for new functionality.

AppContext разработчикам библиотекAppContext for library developers

Библиотеки используют AppContext переключится на класс для определения и предоставления совместимости, время пользователи библиотеки могут задавать эти параметры для влияния на поведение библиотек.Libraries use the AppContext class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. По умолчанию библиотеки предоставляют новые функции и изменяют их (то есть предоставляют прежние функции) только в том случае, если установлен параметр.By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. Это позволяет библиотекам предоставлять новое поведение для существующих API, продолжая поддерживать вызывающим объектам, которые зависят от прежнего поведения.This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior.

Определение имени параметраDefining the switch name

Наиболее распространенный способ разрешить потребители библиотеки отказаться от изменение поведения является определение именованного переключателя.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 элемент является парой имя/значение, состоящее из имени параметра и его Boolean значение.Its value element is a name/value pair that consists of the name of a switch and its Boolean value. По умолчанию параметр всегда является неявно false, которое определяет новое поведение (и определяет новое поведение согласиться по умолчанию).By default, the switch is always implicitly false, which provides the new behavior (and makes the new behavior opt-in by default). Установив переключатель в true позволяет, которая предоставляет устаревшее поведение.Setting the switch to true enables it, which provides the legacy behavior. Явно установив переключатель в false также определяет новое поведение.Explicitly setting the switch to false also provides the new behavior.

Это целесообразно использовать согласованный формат для имен параметров, так как они представляют собой формальный контракт, предоставляемый библиотекой.It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. Ниже приведены два очевидных формата:The following are two obvious formats.

  • параметр.пространство_имен имя_параметраSwitch.namespace.switchname

  • параметр.библиотека.имя_параметраSwitch.library.switchname

После определения и документировать переключателя, вызывающая сторона может использовать его с помощью реестра, добавив <AppContextSwitchOverrides > элемент их файл конфигурации приложения или путем вызова 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. См. в разделе AppContext для пользователей библиотеки Дополнительные сведения о способах вызывающим объектам использовать и установите для параметра AppContext параметры конфигурации.See the AppContext for library consumers section for more information about how callers use and set the value of AppContext configuration switches.

Когда среда CLR запускает приложение, он автоматически считывает параметры реестра в режиме совместимости и загружает файл конфигурации приложения для заполнения приложения 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. Так как AppContext экземпляр заполняется программным способом вызывающим или средой выполнения, не нужно предпринимать никаких действий, например, вызов SetSwitch метод, чтобы настроить 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.

Проверка параметраChecking the setting

Затем можно проверить, если объект-получатель объявило значение коммутатора и соответствующим образом путем вызова act 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. Этот метод возвращает true Если switchName аргумента найдено, и при возвращении метода, ее isEnabled аргумент указывает значение переключателя.The method returns true if the switchName argument is found, and when the method returns, its isEnabled argument indicates the value of the switch. В противном случае метод возвращает значение false.Otherwise, the method returns false.

ПримерAn example

Следующий пример иллюстрирует использование AppContext класс, позволяющий выбрать исходное поведение метода библиотеки клиент.The following example illustrates the use of the AppContext class to allow the customer to choose the original behavior of a library method. Ниже приведен версии 1.0 библиотеки с именем StringLibrary.The following is version 1.0 of a library named StringLibrary. Он определяет SubstringStartsAt метод, который выполняет порядковое сравнение для определения начальный индекс подстроки в строку большего размера.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

Затем в следующем примере используется библиотека найти начальный индекс подстроки «archæ» в «archaeologist».The following example then uses the library to find the starting index of the substring "archæ" in "The archaeologist". Так как этот метод выполняет порядковое сравнение, не найден подстрока.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'

Тем не менее, изменении версии 2 библиотеки, SubstringStartsAt метод, чтобы использовать сравнение с учетом языка и региональных параметров.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

При повторной компиляции приложения для работы с новой версией библиотеки, теперь сообщает, подстроку «archæ» найдено по индексу "4" в «archaeologist».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

Это изменение можно предотвратить работу приложений, зависящих от исходное поведение, определив <AppContextSwitchOverrides > переключения.This change can be prevented from breaking the applications that depend on the original behavior by defining an <AppContextSwitchOverrides> switch. В этом случае параметр с именем StringLibrary.DoNotUseCultureSensitiveComparison.In this case, the switch is named StringLibrary.DoNotUseCultureSensitiveComparison. Значение по умолчанию, false, указывает, что библиотеки должны выполнять его сравнение с учетом языка и региональных параметров версии 2.0.Its default value, false, indicates that the library should perform its version 2.0 culture-sensitive comparison. true Показывает, что библиотеки должны выполнять его сравнение по порядковому номеру версии 1.0.true indicates that the library should perform its version 1.0 ordinal comparison. Незначительное изменение предыдущего примера кода позволяет задать параметр, позволяющий определить используемый тип сравнения, которую выполняет метод потребителю библиотеки.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

Если приложение затем может использовать следующий файл конфигурации для восстановления поведения версии 1.0.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>

При запуске приложения с помощью файла конфигурации, которые присутствуют, он выводит следующие результаты:When the application is run with the configuration file present, it produces the following output:

'archæ' not found in 'The archaeologist'

AppContext для пользователей библиотекиAppContext for library consumers

Если вы являетесь потребитель библиотеки, AppContext класс позволяет воспользоваться преимуществами библиотеки или метод библиотеки механизм явного отказа для новых функциональных возможностей.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. Отдельные методы библиотеки классов, который вы вызываете определяют определенного переключатели для включения или отключения нового поведения.Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. Логическое значение переключателя.The value of the switch is a Boolean. Если это false, который обычно является значением по умолчанию, новое поведение включено; в случае true, новое поведение отключена, и член ведет себя по-другому.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.

Значение параметра можно задать одним из четырех способов:You can set the value of a switch in one of four ways:

  • Путем вызова AppContext.SetSwitch(String, Boolean) метод в коде.By calling the AppContext.SetSwitch(String, Boolean) method in your code. switchName Аргумент определяет имя коммутатора и isEnabled свойство определяет значение переключателя.The switchName argument defines the switch name, and the isEnabled property defines the value of the switch. Поскольку AppContext является статическим классом, он доступен на основе на уровне домена приложения.Because AppContext is a static class, it is available on a per-application domain basis.

    Вызов AppContext.SetSwitch(String, Boolean) имеет область приложения; то есть затрагивает только приложения.Calling the AppContext.SetSwitch(String, Boolean) has application scope; that is, it affects only the application.

  • Добавив <AppContextSwitchOverrides> элемент <среды выполнения > раздел файла app.config.By adding an <AppContextSwitchOverrides> element to the <runtime> section of your app.config file. Параметр имеет один атрибут, value, значение которого является строка, представляющая пару ключ/значение, содержащее имя параметра и его значение.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.

    Чтобы определить несколько коммутаторов, разделите пару ключ значение каждого переключателя в <AppContextSwitchOverrides > элемента value атрибут точкой с запятой.To define multiple switches, separate each switch's key/value pair in the <AppContextSwitchOverrides> element's value attribute with a semicolon. В этом случае <AppContextSwitchOverrides> элемент имеет следующий формат:In that case, the <AppContextSwitchOverrides> element has the following format:

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

    С помощью <AppContextSwitchOverrides> для определения параметра конфигурации имеет область приложения; то есть он влияет на только приложение.Using the <AppContextSwitchOverrides> element to define a configuration setting has application scope; that is, it affects only the application.

    Примечание

    Сведения о переключателях, определенные платформой .NET Framework, см. в разделе <AppContextSwitchOverrides > элемент.For information on the switches defined by the .NET Framework, see the <AppContextSwitchOverrides> element.

  • Добавив строковое значение, имя которого является имя переключателя для HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext разделом реестра.By adding a string value whose name is the name of the switch to the HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext key in the registry. Его значение должно быть строковым представлением Boolean , может быть проанализировано по Boolean.Parse метод, то есть он должен иметь значение «ИСТИНА», «true», «False» или «false».Its value must be the string representation of a Boolean that can be parsed by the Boolean.Parse method; that is, it must be "True", "true", "False", or "false". Если среда выполнения обнаруживает любое другое значение, он игнорирует ключ.If the runtime encounters any other value, it ignores the switch.

    С помощью реестра для определения AppContext коммутатора есть области компьютера; то есть он влияет на каждое приложение, работающее на компьютере.Using the registry to define an AppContext switch has machine scope; that is, it affects every application running on the machine.

  • Для приложений ASP.NET, добавить <Добавить > элемент <appSettings > раздел файла web.config.For ASP.NET applications, you add an <Add> element to the <appSettings> section of the web.config file. Например:For example:

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

Если вы задали тому же коммутатору в более чем одним способом, является порядок очередности для определения параметра, который переопределяет другие:If you set the same switch in more than one way, the order of precedence for determining which setting overrides the others is:

  1. Программный параметр.The programmatic setting.

  2. Параметр в файле конфигурации приложения или в файле web.config.The setting in the app config file or the web.config file.

  3. Параметр реестра.The registry setting.

Вот простое приложение, которое передает файл URI для Path.GetDirectoryName метод.The following is a simple application that passes a file URI to the Path.GetDirectoryName method. При выполнении в .NET Framework 4.6, он выдает ArgumentException поскольку file:// больше не является допустимой частью путь к файлу.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()

Чтобы восстановить прежнее поведение данного метода и избежать возникновения исключения, можно добавить Switch.System.IO.UseLegacyPathHandling переключитесь в файле конфигурации приложения, например: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>

См. такжеSee also

Переключатель AppContextAppContext switch

Свойства

BaseDirectory BaseDirectory BaseDirectory BaseDirectory

Возвращает путь к базовому каталогу, в котором сопоставитель сборок производит поиск.Gets the pathname of the base directory that the assembly resolver uses to probe for assemblies.

TargetFrameworkName TargetFrameworkName TargetFrameworkName TargetFrameworkName

Получает имя целевой версии платформы текущего приложения.Gets the name of the framework version targeted by the current application.

Методы

GetData(String) GetData(String) GetData(String) GetData(String)

Возвращает значение именованного элемента данных, назначенное текущему домену приложения.Returns the value of the named data element assigned to the current application domain.

SetSwitch(String, Boolean) SetSwitch(String, Boolean) SetSwitch(String, Boolean) SetSwitch(String, Boolean)

Задает значение переключателя.Sets the value of a switch.

TryGetSwitch(String, Boolean) TryGetSwitch(String, Boolean) TryGetSwitch(String, Boolean) TryGetSwitch(String, Boolean)

Предпринимает попытку получения значения переключателя.Tries to get the value of a switch.

Применяется к

Дополнительно