How to start?
You will need several assemblies. This is because to reach the level of decoupling that is desired, the pipeline has a certain pattern of dependencies between projects. I’m not sure if I am subconsciously not objecting to it or actually actively like this now, was not always the way.
A pipeline?
Yes, you need one.
What is a pipeline?
It’s a series of folders that live somewhere (does not have to be under your application's path) and each of the assemblies have their place in the structure. The folders will look like this:
It’s probably a good idea to build one now in your project tree and set the build output as you go.
There is a graphic explaining the pipeline on the CLR Add-In team blog (with nice colours), it is also in the Orcas MSDN under the title: "Pipeline Development Requirements". The MSDN one has the addition of lines to indicate the static dependancies.
I've chosen to show it differently in my graphics (don't say a word!) to indicate the order of it all coming together as well as the references. In the graphic the arrow lines illustrate the dependancies between the projects.
Also, I make reference to the sample code throughout this post. Download link is at the bottom.
Step 1: Define Contracts
The first step is to define the contracts in your contracts assembly and DTOs in your DTO’s assembly.
Your contract should be one interface per kind of add-in you will support. These interfaces need to inherit System.AddIn.Contract.IContract and be decorated with System.AddIn.Pipeline.AddInContractAttribute.
Types in the DTO that you wish to pass over the boundary will need to be serializable.
Jason He’s example of a Paint.NET Add-In (link below) takes a different path, by adding the extra types in the Add-In View, adding more wrappers. His approach may have advantages that I have not discovered yet, but it reminds me of some of the dancing you have to do when for example you have the same type in a Web Reference and a binary reference in the same project.
My preference is then to make a behavior-free separate assembly that anyone can take a dependency on safely. This is the reason for including a DTO project. I also like having the DTO types there to do as a [DataContract] does in WCF. This will allow the Add-In contract to remain static if the host side changes it’s implementations of the DTO equiv. types.
Change the project properties of the Contracts project to build to: ..\Pipeline\Contracts\
Also note, for types that take a dependency on the DTO project, set the Copy Local property of the reference to False. This is to keep the pipleline path clean. i.e. we don’t actually want a copy of the DTO assembly in the \pipeline\contracts\ path! This will slow our discovery and generate warnings as the Add-In infrastructure tries to examine it for contracts.
Step 2: Host View and Add-In View
Add two new assemblies: host view and add-in view
Each has a public abstract class that mirrors the contract interface but does not reference it.
Host view does not even need a reference to System.AddIn.
When building the Add-In View, be sure to:
- Apply System.AddIn.Pipeline.AddInBaseAttribute
- Set the project to build to ..\Pipeline\AddInViews\
Step 3: Host Adaptor and Add-In Adaptor
Add two more assemblies: host adaptor and add-in adaptor
Add-in adapter will have one AddinToContractAdapter class for each Add-In type and the Host adapter has one ContractToHostViewAdapter class for each Add-In type.
The AddinToContractAdapter descends from System.AddIn.ContractBase and implements the contract for the Add-In
The ContractToHostViewAdapter descends from the Abstract class in the Host View for the Add-In.
Set the build output path of the Host Side adapter to: ..\Pipeline\HostSideAdapters\
And set the build output path of the Add-In Side adapter to: ..\Pipeline\AddInSideAdapters\
The purpose of these adapters is too marshal calls between the instances of your IContract's and should just look like wrapper code.
Step 4: Build the Add-Ins
Every Add-In needs to take a dependency on the Add-In View project and the DTO project. Be sure to set their Copy Local = False in the reference properties.
Each Add-In also needs to descend from the abstract class in the Add-In View project, implement overrides, and to be decorated with System.AddIn.AddInAttribute.
The AddIn Attribute is the key to how the Add-In will be seen by the host so pay attention to the parameters on the constructor.
Set the build output path of each Add-In to: ..\Pipeline\AddIns\<addinName>\
I should mention that the Add-In's in the sample code below are just stubs to show the complete loop. The Book Library Add-In returns empty objects of the prescribed types, the other two throw an Exception. This is to show error handling.
Step 5: The Add-In Host
Take a reference to the Host View and Dto projects, this time it is OK to have the reference Copy Local.
In the attached example the Book Library add-in returns empty objects of the designed type, however the other two (DVD Library and CD Library) throw an Exception for each operation.
By the end of the process, the project will look like this:
Trouble shooting & Error Handling
Just skiming over this topic, but it is wise to wire up a handler to AppDomain.UnhandledException for the app domain that will run your Add-Ins, and Application.ThreadException (Windows Forms examples) as well as wrapping calls into the Add-In with a Try... Catch block.
If you are trying to work out why your AddIns are not being discovered, remember that:
- AddInStore.Rebuild()
- AddInStore.RebuildAddIns()
- AddInStore.Update()
- AddInStore.UpdateAddIns()
...all return an array of strings that can be examined to determine how the AddIn discovery went.
Source Code:
The source code for this example is available for download from the following link:
LibraryAddInDemoCode_deepdark.net.zip (152.81 KB)
It requires Visual Studio Codename Orcas Beta 1.
Summary:
There are a couple of steps to implementing the new System.Addin stuff, but none of it is hard!
...and considering that it replaces a lot of very untidy and error-prone Reflection code that we had to do in prior versions of the framework I think this is a great addition to the toolbox.
This post is not meant to be a hardcore reference, just the total of my experience with this technology to date. If you have any feedback please don't hesitate to contact me by email or leaving a comment on this post.
Sources:
Listening to: The Chillout Sessions 3