Add-in Activation
Once you have used the discovery methods and obtained a collection of add-in tokens for a specified host view, you can activate an add-in from the collection by using its token, which is represented by an AddInToken object. For more information about how to discover add-ins that are available on your system, see Add-in Discovery.
When you use the Activate method overloads on an AddInToken object, you can specify the following activation options:
The application domain that the add-in is loaded into.
The security trust level or permission set that is granted to the application domain that is created for the add-in.
The external process in which to activate the add-in. This is an advanced add-in development option.
The Activate method returns the host view of the add-in; the host application can then call methods as defined in the contract. The host application can control the life of the add-in by shutting it down with the AddInController class. It can also let the garbage collector reclaim the add-in when it is no longer referenced.
Activation
Typically, host applications keep the host and the add-in running in separate application domains, with one application domain per add-in. This enables add-ins to operate in isolated contexts from both the host and from other add-ins. This isolation prevents conflicts and enables versioning of the add-ins.
Because the add-in is in its own application domain, you can test it in its own environment and also test its side of the pipeline. The add-in adapter, contract, and add-in view pipeline segments are loaded into the same application domain as the add-in. Any other assemblies required by the add-in are also loaded into the add-in's application domain.
When activating add-ins, the host application typically uses the Activate method overload that takes a specified security level and that automatically creates an application domain for the add-in. You can specify a AddInSecurityLevel or a PermissionSet for the security level. When the Activate method creates an application domain for the add-in, it sets the application domain's configuration file to be addinassemblyname.config, if that configuration file exists.
For finer control or to pool add-ins, you can use overloads of the AddInToken.Activate method to specify an existing application domain for loading add-ins. If you specify an existing application domain, you can easily share resources, security contexts, and culture information with other add-ins.
You should consider the security context that will be applied to the add-in's application domain. For example, a host application may be running in full trust but may need to run add-ins with fewer permissions. You can use overloads of the Activate method to specify a security zone with the AddInSecurityLevel enumeration. These security zones include FullTrust, Host, Intranet, or Internet. The appropriate permissions for the security zone are applied to the code that is running in the application domain. The permissions available for these security zones depend on existing .NET Framework security settings.
If you do not want to use permissions for a security zone, you can use overloads of the Activate method to provide your own PermissionSet object.
You can use overloads of the Activate method to create an external process for the add-in or to attach the add-in to an existing external process that was created to host add-ins. These overloads use the AddInProcess and AddInEnvironment classes. For more information about activating add-ins in an external process, see How to: Activate Add-ins with Different Isolation and Security Levels.
Add-in Lifetime Control
The AddInController class provides methods for the following add-in tasks:
Shut down the add-in.
Get the add-in's application domain.
Get a token of the add-in for future activation.
Get an AddInEnvironment object for use with external process activation.
Use the GetAddInController method to obtain the controller for a specified add-in.
The Shutdown method handles the details required to shut down an add-in. These include knowing where the add-in is loaded, its application domain, and possibly the external processes that the add-in is running in. If the application domain was created automatically, this method unloads that application domain. If the add-in was activated in a specified application domain, the lifetime service on the remote contract object will time out, which leaves the application domain loaded. When the contract object is disposed, the add-in will be available to be reclaimed by garbage collection.
Example
The following example activates an add-in with a specified security level in an automatically created application domain.
'Ask the user which add-in they would like to use.
Dim selectedToken As AddInToken = ChooseAddIn(tokens)
'Activate the selected AddInToken in a new
'application domain with the Internet trust level.
Dim CalcAddIn As Calculator = selectedToken.Activate(Of Calculator)(AddInSecurityLevel.Internet)
'Run the add-in using a custom method.
RunCalculator(CalcAddIn)
//Ask the user which add-in they would like to use.
AddInToken selectedToken = ChooseAddIn(tokens);
//Activate the selected AddInToken in a new
//application domain with the Internet trust level.
Calculator CalcAddIn = selectedToken.Activate<Calculator>(AddInSecurityLevel.Internet);
//Run the add-in using a custom method.
RunCalculator(CalcAddIn);
See Also
Tasks
How to: Activate Add-ins with Different Isolation and Security Levels
Concepts
Contracts, Views, and Adapters