AppContext AppContext AppContext AppContext Class

Definizione

Fornisce i membri per l'impostazione e il recupero dei dati relativi al contesto di un'applicazione.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
Ereditarietà
AppContextAppContextAppContextAppContext

Commenti

La AppContext classe consente agli autori di librerie di fornire un meccanismo uniforme per la rinuncia esplicita alla nuova funzionalità per gli utenti.The AppContext class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. che stabilisce un contratto a regime di controllo libero ("loosely-coupled") tra componenti per poter comunicare una richiesta di rinuncia esplicita.It establishes a loosely-coupled contract between components in order to communicate an opt-out request. Questa funzionalità è importante in genere quando viene apportata una modifica alle funzionalità esistenti.This capability is typically important when a change is made to existing functionality. Al contrario, esiste già un consenso esplicito per la nuova funzionalità.Conversely, there is already an implicit opt-in for new functionality.

AppContext per sviluppatori di librerieAppContext for library developers

Le librerie utilizzano AppContext la classe per definire ed esporre le opzioni di compatibilità, mentre gli utenti della libreria possono impostare tali opzioni in modo da influire sul comportamento della libreria.Libraries use the AppContext class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. Per impostazione predefinita, le librerie forniscono la nuova funzionalità e la modificano (cioè offrono la funzionalità precedente) solo se l'opzione è impostata.By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. Questo consente alle librerie di fornire un nuovo comportamento per un'API esistente, continuando a supportare i chiamanti che dipendono dal comportamento precedente.This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior.

Definizione del nome dell'opzioneDefining the switch name

Il modo più comune per consentire ai consumer della libreria di rifiutare esplicitamente la modifica del comportamento consiste nel definire un commutatore denominato.The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. Il value relativo elemento è una coppia nome/valore costituita dal nome di un'opzione e dal Boolean relativo valore.Its value element is a name/value pair that consists of the name of a switch and its Boolean value. Per impostazione predefinita, l'opzione è sempre implicitamente false, che fornisce il nuovo comportamento (e rende il nuovo comportamento esplicito per impostazione predefinita).By default, the switch is always implicitly false, which provides the new behavior (and makes the new behavior opt-in by default). Impostando l'opzione true su, viene abilitata, che fornisce il comportamento legacy.Setting the switch to true enables it, which provides the legacy behavior. Impostare in modo esplicito l' false opzione su fornisce anche il nuovo comportamento.Explicitly setting the switch to false also provides the new behavior.

È vantaggioso usare un formato coerente per i nomi dei commutiri, dal momento che si tratta di un contratto formale esposto da una libreria.It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. Di seguito sono riportati due formati ovvi.The following are two obvious formats.

  • Opzione.spaziodeinomi.nomeopzioneSwitch.namespace.switchname

  • Opzione.libreria.nomeopzioneSwitch.library.switchname

Una volta definita e documentata l'opzione, i chiamanti possono utilizzarla utilizzando il registro di sistema, aggiungendo un AppContext.SetSwitch(String, Boolean) <elemento > AppContextSwitchOverrides al file di configurazione dell'applicazione oppure chiamando il metodo a livello di codice.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. Per ulteriori informazioni sulla modalità di utilizzo dei chiamanti e sull'impostazione del valore delle opzioni di AppContext configurazione, vedere la sezione AppContext for Library consumers .See the AppContext for library consumers section for more information about how callers use and set the value of AppContext configuration switches.

Quando il Common Language Runtime esegue un'applicazione, legge automaticamente le impostazioni di compatibilità del registro di sistema e carica il file di configurazione dell'applicazione per popolare l' AppContext istanza dell'applicazione.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. Poiché l' AppContext istanza viene popolata a livello di codice dal chiamante o dal runtime, non è necessario eseguire alcuna azione, ad esempio la chiamata al SetSwitch metodo, per configurare l' AppContext istanza.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.

Verifica dell'impostazioneChecking the setting

È quindi possibile controllare se un consumer ha dichiarato il valore dell'opzione e agire in modo appropriato chiamando il AppContext.TryGetSwitch metodo.You can then check if a consumer has declared the value of the switch and act appropriately by calling the AppContext.TryGetSwitch method. Il metodo restituisce true se l' switchName argomento viene trovato e quando il metodo restituisce, il relativo isEnabled argomento indica il valore dell'opzione.The method returns true if the switchName argument is found, and when the method returns, its isEnabled argument indicates the value of the switch. In caso contrario, il metodo restituisce false.Otherwise, the method returns false.

un esempioAn example

Nell'esempio seguente viene illustrato l'utilizzo della AppContext classe per consentire al cliente di scegliere il comportamento originale di un metodo di libreria.The following example illustrates the use of the AppContext class to allow the customer to choose the original behavior of a library method. Di seguito è riportata la versione 1,0 di una StringLibrarylibreria denominata.The following is version 1.0 of a library named StringLibrary. Definisce un SubstringStartsAt metodo che esegue un confronto ordinale per determinare l'indice iniziale di una sottostringa all'interno di una stringa più grande.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

Nell'esempio seguente viene quindi utilizzata la libreria per trovare l'indice iniziale della sottostringa "archæ" in "archeologo".The following example then uses the library to find the starting index of the substring "archæ" in "The archaeologist". Poiché il metodo esegue un confronto ordinale, non è possibile trovare la sottostringa.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'

La versione 2 della libreria, tuttavia, modifica il SubstringStartsAt metodo in modo da usare il confronto con distinzione delle impostazioni cultura.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

Quando l'app viene ricompilata per l'esecuzione con la nuova versione della libreria, viene ora segnalato che la sottostringa "archæ" si trova in corrispondenza dell'indice 4 in "archeologo".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

È possibile impedire a questa modifica di suddividere le applicazioni che dipendono dal comportamento originale definendo < un'opzione di > AppContextSwitchOverrides.This change can be prevented from breaking the applications that depend on the original behavior by defining an <AppContextSwitchOverrides> switch. In questo caso, l'opzione è denominata StringLibrary.DoNotUseCultureSensitiveComparison.In this case, the switch is named StringLibrary.DoNotUseCultureSensitiveComparison. Il valore predefinito, false, indica che la libreria deve eseguire il confronto con distinzione delle impostazioni cultura della versione 2,0.Its default value, false, indicates that the library should perform its version 2.0 culture-sensitive comparison. trueindica che la libreria deve eseguire il confronto ordinale della versione 1,0.true indicates that the library should perform its version 1.0 ordinal comparison. Una lieve modifica del codice precedente consente al consumer della libreria di impostare l'opzione per determinare il tipo di confronto eseguito dal metodo.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

Se l'applicazione può quindi usare il file di configurazione seguente per ripristinare il comportamento della versione 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>

Quando l'applicazione viene eseguita con il file di configurazione presente, produce l'output seguente:When the application is run with the configuration file present, it produces the following output:

'archæ' not found in 'The archaeologist'

AppContext per i consumer della libreriaAppContext for library consumers

Se si è l'utente di una libreria, la AppContext classe consente di sfruttare i vantaggi del meccanismo di esclusione del metodo della libreria o della libreria per le nuove funzionalità.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. I singoli metodi della libreria di classi che si sta chiamando definiscono determinate opzioni che abilitano o disabilitano un nuovo comportamento.Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. Il valore dell'opzione è un valore booleano.The value of the switch is a Boolean. Se è true, che corrisponde in genere al valore predefinito, il nuovo comportamento è abilitato; in caso affermativo, il nuovo comportamento viene disabilitato e il membro si comporta come in precedenza. 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.

È possibile impostare il valore di un'opzione in uno dei quattro modi seguenti:You can set the value of a switch in one of four ways:

  • Chiamando il AppContext.SetSwitch(String, Boolean) metodo nel codice.By calling the AppContext.SetSwitch(String, Boolean) method in your code. L' switchName argomento definisce il nome dell'opzione e la isEnabled proprietà definisce il valore dell'opzione.The switchName argument defines the switch name, and the isEnabled property defines the value of the switch. Poiché AppContext è una classe statica, è disponibile in base al dominio dell'applicazione.Because AppContext is a static class, it is available on a per-application domain basis.

    La chiamata AppContext.SetSwitch(String, Boolean) di ha un ambito di applicazione, ovvero ha effetto solo sull'applicazione.Calling the AppContext.SetSwitch(String, Boolean) has application scope; that is, it affects only the application.

  • Aggiungendo un <AppContextSwitchOverrides> elemento <alla sezione runtime > del file app. config.By adding an <AppContextSwitchOverrides> element to the <runtime> section of your app.config file. L'opzione ha un solo attributo, value, il cui valore è una stringa che rappresenta una coppia chiave/valore contenente sia il nome dell'opzione che il relativo valore.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.

    Per definire più opzioni, separare la coppia chiave/valore di ogni opzione nell' value attributo dell' <elemento > AppContextSwitchOverrides con un punto e virgola.To define multiple switches, separate each switch's key/value pair in the <AppContextSwitchOverrides> element's value attribute with a semicolon. In tal caso, l' <AppContextSwitchOverrides> elemento ha il formato seguente:In that case, the <AppContextSwitchOverrides> element has the following format:

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

    L'uso <AppContextSwitchOverrides> dell'elemento per definire un'impostazione di configurazione presenta un ambito di applicazione, ovvero ha effetto solo sull'applicazione.Using the <AppContextSwitchOverrides> element to define a configuration setting has application scope; that is, it affects only the application.

    Nota

    Per informazioni sulle opzioni definite dalla .NET Framework, vedere l' <elemento AppContextSwitchOverrides >.For information on the switches defined by the .NET Framework, see the <AppContextSwitchOverrides> element.

  • Aggiungendo un valore stringa il cui nome è il nome dell'opzione alla HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext chiave nel registro di sistema.By adding a string value whose name is the name of the switch to the HKLM\SOFTWARE\Microsoft\.NETFramework\AppContext key in the registry. Il valore deve corrispondere alla rappresentazione di stringa di Boolean un oggetto che può essere analizzato Boolean.Parse dal metodo, ovvero deve essere "true", "true", "false" o "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". Se il runtime rileva qualsiasi altro valore, ignora l'opzione.If the runtime encounters any other value, it ignores the switch.

    L'uso del registro di sistema AppContext per definire un'opzione ha un ambito del computer, ovvero ha effetto su tutte le applicazioni in esecuzione nel computer.Using the registry to define an AppContext switch has machine scope; that is, it affects every application running on the machine.

  • Per le applicazioni ASP.NET, è necessario aggiungere un <elemento Add > alla <sezione > AppSettings del file Web. config.For ASP.NET applications, you add an <Add> element to the <appSettings> section of the web.config file. Ad esempio:For example:

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

Se si imposta lo stesso switch in più di un modo, l'ordine di precedenza per determinare quale impostazione esegue l'override degli altri è:If you set the same switch in more than one way, the order of precedence for determining which setting overrides the others is:

  1. Impostazione a livello di codice.The programmatic setting.

  2. Impostazione nel file di configurazione dell'applicazione o nel file Web. config.The setting in the app config file or the web.config file.

  3. Impostazione del registro di sistema.The registry setting.

Di seguito è riportata una semplice applicazione che passa un URI di file Path.GetDirectoryName al metodo.The following is a simple application that passes a file URI to the Path.GetDirectoryName method. Quando viene eseguito con la .NET Framework 4,6, viene generata ArgumentException un' file:// eccezione perché non è più una parte valida di un percorso di 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()

Per ripristinare il comportamento precedente del metodo e impedire l'eccezione, è possibile aggiungere l' Switch.System.IO.UseLegacyPathHandling opzione al file di configurazione dell'applicazione per l'esempio: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>

Vedere ancheSee also

Opzione AppContextAppContext switch

Proprietà

BaseDirectory BaseDirectory BaseDirectory BaseDirectory

Ottiene il percorso della directory base usata dal resolver dell'assembly per verificare la presenza di assembly.Gets the pathname of the base directory that the assembly resolver uses to probe for assemblies.

TargetFrameworkName TargetFrameworkName TargetFrameworkName TargetFrameworkName

Ottiene il nome della versione del framework di destinazione dell'applicazione corrente.Gets the name of the framework version targeted by the current application.

Metodi

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

Restituisce il valore dell'elemento dati denominato assegnato al dominio applicazione corrente.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)

Imposta il valore di un'opzione.Sets the value of a switch.

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

Prova a ottenere il valore di un'opzione.Tries to get the value of a switch.

Si applica a

Vedi anche