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. この要素は、スイッチの名前とそのBoolean値で構成される名前と値のペアです。 valueIts 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の呼び出しなどの操作を行う必要はありません。 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.

設定を確認しています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. 引数が見つかっtrueisEnabled場合、メソッドはを返します。メソッドから制御が戻ったときに、その引数がスイッチの値を示します。 switchNameThe 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. 次に、という名前StringLibraryのライブラリのバージョン1.0 を示します。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. 既定値である場合は、新しい動作が有効になります。これがtrueの場合、新しい動作は無効になり、メンバーは以前と同じように動作します。 falseIf 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.

  • App.config ファイルの<AppContextSwitchOverrides> <ランタイム >セクションに要素を追加します。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メソッドによって解析できるの文字列表現である必要があります。つまり、"true"、"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 アプリケーションの場合は、web.config ファイルの <appSettings >セクションに <add >要素を追加します。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 で実行すると、はファイルパスArgumentExceptionfile://有効な部分ではなくなったため、をスローします。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.

適用対象

こちらもご覧ください