Add-in Discovery
Host applications can discover add-ins that are available to them. Discovery consists of two tasks:
Registering information about all add-ins and pipeline segments into cache files.
Finding add-ins for a specified host view of the add-in by searching the cache.
Depending on the application, the host typically discovers add-ins at startup, when a document is loaded, or upon a user request. The AddInStore class provides methods to perform these tasks.
Once you have discovered the add-ins, you can activate them as described in Add-in Activation and How to: Activate Add-ins with Different Isolation and Security Levels.
Registering Add-ins and Pipeline Segments
Registering involves determining valid add-ins by checking the attributes of pipeline segments and constructing information about their pipelines. For more information about applying attributes to pipeline segments and creating the pipeline directory structure, see Pipeline Development Requirements. The pipeline directory structure can contain one or more pipelines. This information is cached in two files in the pipeline root directory: PipelineSegments.store and AddIns.store.
The methods used for registration take a string variable that represents the pipeline root path, or a value from the PipelineStoreLocation enumeration. They create new cache files if these files have not been previously created.
The methods either rebuild or update the cache files, as the following table describes.
Registration method |
Description |
|---|---|
Rebuilds the pipeline segments cache and includes any new additions. This method also rebuilds the add-ins cache if the add-ins are within the pipeline directory structure. |
|
Rebuilds the add-ins cache for add-ins at a specified location. Call this method if your add-ins are outside the pipeline directory structure. |
|
Updates the pipeline segments cache with any additions. This method also updates the add-ins cache if the add-ins are within the pipeline directory structure. If there are no new pipeline segments or add-ins, this method simply validates the cache. |
|
Updates the add-in cache for any new add-ins at a specified location. Call this method if your add-ins are outside the pipeline directory structure. If there are no new add-ins installed, this method simply validates the cache. |
The Rebuild and Update method overloads take as a parameter either the root directory of the pipeline directory structure or a value from the PipelineStoreLocation enumeration.
These methods use reflection-only loading to obtain information and do not run the add-in's code or the pipeline segment's code. Cached information is time-stamped so that it is not recomputed during updates.
Cache Files
The result of calling the registration methods are two cache files:
PipelineSegments.store
This file is located in the root directory of the pipeline directory structure.
AddIns.store
This file is located in the directory that contains one or more add-in subdirectories. This directory can be within the pipeline directory structure or at another location.
Finding Add-Ins
The FindAddIns method examines the store files to find all add-ins that match a specified host view of the add-in. The host view of the add-in is the abstract base class or interface that describes the methods used by the host and the add-in, as specified in the contract. To find the cache files created by the registration methods, this method takes as a parameter either the root directory of the pipeline directory structure or a value from the PipelineStoreLocation enumeration.
.gif "Note") Note |
|---|
Call FindAddIns only after you are sure that the store files are built and updated so that all available add-ins can be found. |
The FindAddIns method returns an IList<T> collection of tokens that describe each available add-in that has a valid pipeline. Each token is described by the AddInToken class.
Each token has the following information about an add-in, which is obtained from the AddInAttribute attribute on the add-in's class:
Name
Description
Publisher
Version
In most cases, there is only one token in the IList<T> collection. If there is more than one token, the host application can use this information to help the user select the add-in to activate. For more information about activation, see Add-in Activation.
To find add-ins outside the pipeline directory structure, you must include the AddInPaths parameter. Because this parameter is an array of strings, you can specify multiple locations.
You can also find a specific add-in with the FindAddIn method that returns a collection of one token.
Example
The following example shows how to build the cache files and find add-ins.
' Get the path for the pipeline root.
' Assumes that the current directory is the
' pipline directory structure root directory.
Dim pipeRoot As String = Environment.CurrentDirectory
' Update the cache files of the
' pipeline segments and add-ins.
Dim warnings() As String = AddInStore.Update(pipeRoot)
For Each warning As String In warnings
Console.WriteLine(warning)
Next
' Search for add-ins of type Calculator (the host view of the add-in)
' specifying the host's application base, instead of a path,
' for the FindAddIns method.
Dim tokens As Collection(Of AddInToken) = _
AddInStore.FindAddIns(GetType(Calculator), PipelineStoreLocation.ApplicationBase)
// Get path for the pipeline root.
// Assumes that the current directory is the
// pipeline directory structure root directory.
String pipeRoot = Environment.CurrentDirectory;
// Update the cache files of the
// pipeline segments and add-ins.
string[] warnings = AddInStore.Update(pipeRoot);
foreach (string warning in warnings)
{
Console.WriteLine(warning);
}
// Search for add-ins of type Calculator (the host view of the add-in)
// specifying the host's application base, instead of a path,
// for the FindAddIns method.
Collection<AddInToken> tokens =
AddInStore.FindAddIns(typeof(Calculator),PipelineStoreLocation.ApplicationBase);
See Also
Concepts
Pipeline Development Requirements
Contracts, Views, and Adapters