AppContext クラス

定義

アプリケーションのコンテキストについてのデータを設定したり取得したりするためのメンバーを提供します。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
継承
AppContext

注釈

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.

スイッチ名を定義するDefine 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 要素は、スイッチの名前とその値で構成される名前と値のペアです BooleanIts 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 」セクションを参照してください AppContextSee 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 インスタンスを構成するために、メソッドの呼び出しなどの操作を行う必要はありません AppContextBecause 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.

[この項目を条件付きで表示する] という設定をオンにしますCheck 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.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

次の例では、ライブラリを使用して、"the archaeologist" の部分文字列 "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

新しいバージョンのライブラリに対して実行するようにアプリを再コンパイルすると、"the archaeologist" のインデックス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 ファイルのセクションに要素を追加し <runtime> ます。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.

  • レジストリにエントリを追加します。By adding an entry to the registry. HKLM\SOFTWARE\Microsoft . Netframework\ appcontext サブキーに新しい文字列値を追加します。Add a new string value to the HKLM\SOFTWARE\Microsoft.NETFramework\AppContext subkey. エントリの名前をスイッチの名前に設定します。Set the name of the entry to the name of the switch. True、、 true False 、またはのいずれかのオプションに値を設定します falseSet its value to one of the following options: True, true, False, or false. ランタイムがその他の値を検出した場合、スイッチは無視されます。If the runtime encounters any other value, it ignores the switch.

    64ビットオペレーティングシステムでは、 HKLM\SOFTWARE\Wow6432Node\Microsoft . Netframework\ appcontext サブキーにも同じエントリを追加する必要があります。On a 64-bit operating system, you must also add the same entry to the HKLM\SOFTWARE\Wow6432Node\Microsoft.NETFramework\AppContext subkey.

    レジストリを使用してスイッチを定義すると AppContext 、マシンのスコープを持つことになります。つまり、コンピューター上で実行されているすべてのアプリケーションに影響します。Using the registry to define an AppContext switch has machine scope; that is, it affects every application running on the machine.

  • ASP.NET アプリケーションの場合は、 <Add> web.config ファイルのセクションに要素を追加し <appSettings> ます。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.GetDirectoryNameThe 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

アセンブリを探すためにアセンブリ リゾルバーが使用するベース ディレクトリのファイル パスを取得します。Gets the file path of the base directory that the assembly resolver uses to probe for assemblies.

TargetFrameworkName

現在のアプリケーションの対象となるフレームワークのバージョンの名前を取得します。Gets the name of the framework version targeted by the current application.

メソッド

GetData(String)

現在のアプリケーション ドメインに割り当てられている名前付きデータ要素の値を返します。Returns the value of the named data element assigned to the current application domain.

SetSwitch(String, Boolean)

スイッチの値を設定します。Sets the value of a switch.

TryGetSwitch(String, Boolean)

スイッチの値の取得を試みます。Tries to get the value of a switch.

適用対象