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.

  Important
  Make 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.

See Also

Other Resources

Deploying the .NET Framework and Applications

Hosting (Unmanaged API Reference)