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:

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

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

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

  1. In Solution Explorer, right-click the References folder and choose Add Reference.

  2. On the Projects tab, choose the desired project and click OK.

  3. Under the References folder, click the project reference you just added.

  4. 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

  1. From the Tools menu, point to your project's Properties and then select the Build tab.

  2. 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.

See Also

Concepts

Contracts, Views, and Adapters

Add-in Discovery

Pipeline Development