Activation Configuration Files
An application that provides a managed extensibility model can require extensions to run with a particular version of the .NET Framework runtime, by specifying that version in an application configuration file or a host configuration file. Before the .NET Framework version 4, the only way to write extensions with a later version of the runtime was to provide a different configuration file for the application. Unfortunately, this had the undesirable consequence of forcing all extensions to use the newer runtime.
Activation configuration files provide an alternative solution for the specific scenario in which the extension author uses an application’s extensibility model as a platform and fully controls all the extensions that are loaded. In that scenario, it is reasonable to allow the extension author to decide which version of the runtime is loaded and activated.
For example, you might want to use the .NET Framework 4 to create a set of Microsoft Management Console (MMC) snap-ins to customize the user interface of a management console, on computers where MMC specifies the activation of the .NET Framework version 2.0 runtime. You cannot directly replace the activation information for MMC, but you can use an environment variable to specify the location of an activation configuration file that overrides it for a particular console, so that the .NET Framework 4 runtime is activated when the console is launched.
Providing an Activation Configuration File
Activation configuration file names follow the same pattern as application configuration file names, but use the extension .activation_config. For example, an application named MyApp.exe has an application configuration file named MyApp.exe.config and an activation configuration file named MyApp.exe.activation_config.
Activation configuration files can contain any configuration file elements, but the only elements that are parsed are those that are normally used for activation:
Elements in the <startup> section.
The <gcServer>, <appdomainResourceMonitoring>, and <etwEnable> elements in the <runtime> section.
.gif "Important note")
ImportantMake sure that these three <runtime> settings in the activation configuration file are the same as the corresponding settings in the application or host configuration file.
The activation configuration file is used only by the shim code that starts the runtime. The runtime itself has no interaction with the file.
Once you have created the application configuration file, set the COMPLUS_ApplicationMigrationRuntimeActivationConfigPath environment variable to the path where the file is located. During the process of selecting the runtime to be activated, this path is searched for an application configuration file whose name matches the pattern.
If the environment variable is set but the specified path contains no activation configuration file that matches the pattern, runtime activation is controlled by the application or host configuration file, as usual.
The environment variable can be set globally or by a launcher process that configures the environment. Setting global environment variables is subject to race conditions with other applications.
For example, the following command-line session copies an activation configuration file to a folder, sets the environment variable to that path, and runs the application:
copy c:\MyConfigs\MyApp.exe.activation_config c:\CustomConfigs
set COMPLUS_ApplicationMigrationRuntimeActivationConfigPath =
c:\CustomConfigs
c:\Program Files\MyApp\MyApp.exe
The following activation configuration file specifies activation of the .NET Framework 4 runtime, and duplicates a hypothetical <appDomainResourceMonitoring> setting from the hypothetical application's configuration file:
<configuration>
<startup>
<supportedRuntime version="v4.0.30319"/>
</startup>
<runtime>
<appDomainResourceMonitoring enabled="true"/>
</runtime>
</configuration>
Supported Activation Methods
Activation configuration files affect the following activation methods. The term "legacy" refers to versions of the .NET Framework before the .NET Framework 4.
Running any managed .exe file on a computer where the .NET Framework 4 is installed.
Using the legacy hosting API; for example, the CorBindToRuntimeHost global function.
Loading and running legacy mixed-mode components created with Visual C++.
Loading and running legacy COM components.
Note
Activation configuration files are not used when you load and run COM components that were created using the .NET Framework 4 or later.
Using the ICLRMetaHostPolicy::GetRequestedRuntime method in the hosting API with the METAHOST_POLICY_USE_PROCESS_IMAGE_PATH flag.
Using the ICLRMetaHostPolicy::GetRequestedRuntime method and supplying an assembly file path for the pwzBinary parameter.
Note
Activation configuration files are not used if the ICLRMetaHostPolicy::GetRequestedRuntime method is called and neither the pwzBinary parameter nor the METAHOST_POLICY_USE_PROCESS_IMAGE_PATH flag is used.