Pipeline Development Requirements
To enable pipeline segments and add-ins to be discovered and activated, they must meet specified scope, attribute, and directory structure requirements.
Pipeline Segments and Assemblies
The add-ins, contracts, and views must be public. Adapters and their constructors can be internal.
Typically, pipeline segments are contained within their own assembly but you can combine the following segments in the same assembly:
Host views of add-ins and add-in-side views.
Host-side adapters and add-in-side adapters.
You can combine the host and add-in-side adapters in the same assembly only if you also combine the views in the same assembly.
If you combine a segment on one side of the pipeline with its counterpart on the other side of the pipeline, such as the host views of add-ins with the add-in views, you must deploy that assembly to both sides of the pipeline for that segment.
If you are not combining views in the same assembly, you can combine the host with the host view of the add-in in the same assembly.
Attribute Requirements
The following pipeline segments require attributes on the classes that define them:
Add-ins require AddInAttribute.
Contracts require AddInContractAttribute.
Add-in views require AddInBaseAttribute.
Add-in-side adapters require AddInAdapterAttribute.
Host-side adapters require HostAdapterAttribute.
The host view of the add-in pipeline segment does not require an attribute because that object is passed to the AddInStore.FindAddIns(Type, String, String[]) method, and therefore does not need to be discovered.
The following illustration shows the pipeline segments with their required attributes.
Add-in model with required attributes on types
.png "Add-in model with required attributes on types.")
Pipeline Directory Requirements
For the .NET Framework to discover pipeline segments and activate add-ins, the pipeline segments must be put in a specified directory. The specified directory names are required but are not case-sensitive. The only names that are not specified are the name of the pipeline root directory (which you provide to the discovery methods), and the names of the subdirectories that contain the add-ins. All the specified segment names must be subdirectories on the same level under the pipeline root.
The following illustration shows these directory requirements.
Required directories for add-in development
.png "Required directories for add-in development.")
The following table describes the required directory structure.
Directory |
Description |
|---|---|
Pipeline root |
The directory that contains the subdirectories of the pipeline segments. There is no required name for this directory and it can be at any location. Example: ..\Pipeline |
AddIns |
Optional. The directory that contains one or more subdirectories, each of which contains an add-in. This directory must be named AddIns. Example: ..\Pipeline\AddIns You can have add-ins at other locations in the system. |
AddInSideAdapters |
The directory that contains the add-in-side adapters assembly. This directory must be named AddInSideAdapters. Example: ..\Pipeline\AddInSideAdapters |
AddInViews |
The directory that contains the add-in views assembly. This directory must be named AddInViews. Example: ..\Pipeline\AddInViews |
Contracts |
The directory that contains the contracts assembly. This directory must be named Contracts. Example: ..\Pipeline\Contracts |
HostSideAdapters |
The directory that contains the host-side adapters assembly. This directory must be named HostSideAdapters. Example: ..\Pipeline\HostSideAdapters |
The AddInStore.Update and AddInStore.Rebuild methods have overloads that take a string variable that represents the pipeline root, or a PipelineStoreLocation value. These methods discover the available add-ins and pipeline segments in the system and maintain their information cached in an information store. For more information about the discovery methods, see Add-in Discovery.
The host application and the host view of the add-in pipeline segment are typically deployed in the same directory, which can be at any location. The host application requires a reference to the host view of the add-in segment that represents the add-in to activate.
The pipeline can be at any location, including within the directory structure of your Visual Studio solution. You must copy the pipeline segments to their directories in the pipeline. The pipeline directory and its subdirectories are designed to contain multiple pipelines. For more information about various pipelines scenarios, see Add-in Pipeline Scenarios.
Add-ins at other Locations
You are not required to have add-ins in the pipeline directory structure. If they are not in the pipeline directory structure, you must call the AddInStore.UpdateAddIns method or the RebuildAddIns method that takes the path to the containing directory of the add-ins as its parameter.
You must also include the addInPaths parameter when calling the AddInStore.FindAddIns method.
If your host application knows the paths and full type names of its add-ins, it can use the FindAddIn method to find a specific add-in, which avoids queries on the pipeline directory structure. However, a pipeline directory structure is still required.
Pipeline Segment References in Visual Studio
When adding a reference in a project to another pipeline segment, such as the add-in-side adapter that requires a reference to the contract segment, make a reference to that segment's project instead of its assembly. In this example, the reference would be to the contract project. A project reference prevents referenced assemblies from being deployed to the pipeline, which can cause conflicts. Conflicts are also prevented by not copying the files locally.
To add a project reference
In Solution Explorer, right-click the References folder and choose Add Reference.
On the Projects tab, choose the desired project and click OK.
Under the References folder, click the project reference you just added.
In the reference Properties, set Copy Local to False.
Required References
The following table lists the pipeline segments that require assembly references to System.AddIn.dll and System.Contract.dll. Some segments also require references to other compiled segments.
Pipeline segment |
Assembly and project references |
Namespace and type references |
|---|---|---|
Contract |
System.AddIn.dll System.AddIn.Contract.dll |
System.AddIn.Pipeline System.AddIn.Contract |
Add-in view |
System.AddIn.dll |
System.AddIn.Pipeline |
Add-in-side adapter |
System.AddIn.dll System.AddIn.Contract.dll Add-in view segment Contract segment |
System.AddIn.Pipeline |
Host-side adapter |
System.AddIn.dll System.AddIn.Contract.dll Host view segment Contract segment |
System.AddIn.Pipeline |
Host |
System.AddIn.dll Host view segment |
System.AddIn.Hosting host view |
Add-In |
System.AddIn.dll Add-in view segment |
System.AddIn add-in view |
The host view of the add-in has no reference requirements but it is required for the host application.
Deploying to the Pipeline in Visual Studio
In Visual Studio, you can build pipeline segments into the pipeline directory structure by changing the output build path.
To deploy to the pipeline in Visual Studio
From the Tools menu, point to your project's Properties and then select the Build tab.
Change the Output path for the pipeline segments to their respective directories in the pipeline directory structure.
The host application and the host view are typically deployed in the same directory. The pipeline directory can be in any location but is typically in the same directory as the host application.