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.

ライブラリ開発者 AppContextAppContext 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. 2 つの明確な形式を次に示します。The following are two obvious formats.

  • Switch.namespace.switchnameSwitch.namespace.switchname

  • Switch.library.switchnameSwitch.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.

共通言語ランタイムは、アプリケーションを実行するときに自動的に、レジストリの互換性設定を読み取って、アプリケーションを設定するには、アプリケーション構成ファイルを読み込みます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

コンシューマーがスイッチと適切に呼び出すことによって動作の値を宣言されているかどうかをチェックすることができますし、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.0StringLibraryします。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æ"の部分文字列の開始インデックスを検索します。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

ライブラリの新しいバージョンに対して実行するアプリを再コンパイルするときにインデックス 4「考古」で"archæ"部分文字列が見つかったことを今すぐ報告します。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'

ライブラリのコンシューマーの AppContextAppContext 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.

4 つの方法では、スイッチの値を設定できます。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. スイッチが 1 つの属性を持つ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メソッドは、"False"または"false""True"を"true"である必要があります。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>
    

1 つ以上の方法で、同じスイッチを設定する必要のある設定を上書き、他のユーザーを決定するための優先順位の順序は。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

AppContext スイッチAppContext 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.

適用対象

こちらもご覧ください