VSTA Integration Newbie

Chapter Six: Loading VSTA Addins with MEF

BillL — Thu, 13 Aug 2009 16:53:00 GMT

My integration journey has come to an end. For my last post, I am going to write about a new way of loading VSTA AddIns: MEF. I have talked about MEF some in my previous posts, and have successfully used both VSTA and MEF together before. This time, I have successfully used MEF to load VSTA AddIns. To do this, I had to edit part of the MEF library to prevent it from locking the .dll and .pdb files, so the debugging and rebuilding of AddIns would still be possible.

Instead of having NEF load the assembly itself, which it usually does, I had it load a byte array of the .dll and .pdb files. All that I needed to edit was part of AssemblyCatalog.cs in the MEF Preview 6 source. I changed the LoadAssembly method from this:

private static Assembly LoadAssembly(string codeBase)

{

Requires.NotNullOrEmpty(codeBase, "codeBase");

AssemblyName assemblyName;

try

{

assemblyName = AssemblyName.GetAssemblyName(codeBase);

}

catch (ArgumentException)

{

assemblyName = new AssemblyName();

assemblyName.CodeBase = codeBase;

}

return Assembly.Load(assemblyName);

}

to this:

private static Assembly LoadAssembly(string codeBase)

{

byte[] assemStream = null, pdbStream = null;

using (FileStream fs = new FileStream(codeBase, FileMode.Open))

{

assemStream = new byte[fs.Length];

fs.Read(assemStream, 0, (int)fs.Length);

}

string pdbPath = Path.Combine(Path.GetDirectoryName(codeBase), Path.GetFileNameWithoutExtension(codeBase) + ".pdb");

bool hasPdb = false;

if (File.Exists(pdbPath))

{

using (FileStream fs = new FileStream(pdbPath, FileMode.Open))

{

pdbStream = new byte[fs.Length];

fs.Read(pdbStream, 0, (int)fs.Length);

hasPdb = true;

}

else

{

Debug.WriteLine("Cannot find the pdb file: " + pdbPath);

}

if (!hasPdb)

{

return Assembly.Load(assemStream);

}

else

{

return Assembly.Load(assemStream, pdbStream);

}

Now we have the ability to load files without locking them, and also have the discoverability benefits of using MEF.

Here is part of the code from the application that allows it to load AddIns with MEF:

Public Sub Compose()

Dim Dir As [String] = Path.Combine(System.Environment.GetFolderPath(System.Environment.SpecialFolder.MyDocuments), "ContactManager\AppAddins")

Dim Dir2 As [String] = Path.Combine(System.Environment.GetFolderPath(System.Environment.SpecialFolder.MyDocuments), "ContactManager\MacroAddIns")

If Directory.Exists(Dir) And Directory.Exists(Dir2) Then

Dim Catalog As New AggregateCatalog(New DirectoryCatalog(Dir), New DirectoryCatalog(Dir2))

Dim Container As New CompositionContainer(Catalog)

Container.SatisfyImportsOnce(Me)

macroBool = True

appLevelBool = True

ElseIf Directory.Exists(Dir) Then

Dim Catalog As New DirectoryCatalog(Dir)

Dim Container As New CompositionContainer(Catalog)

Container.SatisfyImportsOnce(Me)

macroBool = False

appLevelBool = True

ElseIf Directory.Exists(Dir2) Then

Dim Catalog As New DirectoryCatalog(Dir2)

Dim Container As New CompositionContainer(Catalog)

Container.SatisfyImportsOnce(Me)

macroBool = True

appLevelBool = False

End If

End Sub

<Import(("MacroAddIn"), GetType(IAddIn))> Public myMacroAddIn As IAddIn

Private _AppAddIns As IEnumerable(Of IAddIn)

<ImportMany(("AppAddIn"), GetType(IAddIn))> _

Private Property AppAddIns() As IEnumerable(Of IAddIn)

Get

Return _AppAddIns

End Get

Set(ByVal value As IEnumerable(Of IAddIn))

_AppAddIns = value

End Set

End Property

Private Sub LoadAppLevelAddIns()

Try

Compose()

If appLevelBool = True Then

For Each appaddin As IAddIn In AppAddIns

StartAddIn(appaddin)

Me.appLevelAddIns.Add(appaddin)

End If

Catch ex As Exception

System.Diagnostics.Trace.WriteLine(ex.ToString())

End Try

End Sub

Private Function StartAddIn(ByVal myAddIn As IAddIn) As IAddIn

Try

myAddIn.Startup(Me.application)

Return myAddIn

Catch ex As Exception

System.Diagnostics.Trace.WriteLine(ex.ToString())

Return Nothing

End Try

End Function

Private Function CurrentDomain_AssemblyResolve(ByVal sender As Object, ByVal args As ResolveEventArgs) As Assembly

Return Nothing

End Function

Friend Sub LoadMacrosInProcess()

LoadMacros()

Me.m_macroAddInLoadedInProc = True

End Sub

Private Sub LoadMacros()

Try

Compose()

If macroBool = True Then

StartAddIn(myMacroAddIn)

m_macroAddIn = myMacroAddIn

End If

Catch ex As Exception

System.Diagnostics.Trace.WriteLine(ex.ToString())

End Try

If Me.application.MacroManager IsNot Nothing Then

Me.application.MacroManager.CloseThreadSafe()

End If

End Sub

This allows the user to load multiple AppAddIns to be run at startup, and one Macro AddIn to be debugged and run, etc. (Of course, you can always make your Macro AddIn extensible as well, which will still work even if you load the AddIns themselves with MEF.)

I hope you have found this blog helpful in your own integration journey.

Please feel free to email me with any questions.

Chapter Five: Integrating MEF into a VSTA Add-In

BillL — Mon, 10 Aug 2009 17:36:00 GMT

This is one of my last posts in this series. If you have not yet read my previous posts, here are the links to them: Chapter One, Chapter Two, Chapter Three, Chapter Four. (I would especially read Chapter Three, as that is where I introduce MEF, and I would also read the MEF Overview and the Programming Guide, which are linked to in Chapter Three.)

If you remember from my last post, I successfully integrated the VSTA IDE into my Contact Manager application. I have now gone a step further, and integrated MEF into the AddIn itself. To do this, I have created two templates: A regular Macro AddIn template, and a MEF Extension Template.
Here is the default code for each of them.

Macro AddIn code:

Imports System.ComponentModel.Composition

Imports System.ComponentModel.Composition.Hosting

Imports System.ComponentModel.Composition.ImportAttribute

Public Class AppAddIn

Implements IAddIn

Private Application As IContactClass

Private MyContact As IContactObj

Public Sub Startup(ByRef app As IContactClass) Implements IAddIn.Startup

Application = app

MyContact = Application.CreateNewContactObj()

Compose()

End Sub

Public Sub Shutdown() Implements IAddIn.Shutdown

' do nothing

End Sub

Public Sub Compose()

Dim Dir As [String] = Path.Combine(System.Environment.GetFolderPath(System.Environment.SpecialFolder.MyDocuments), "ContactManager\Macros\Extensions")

Dim Catalog As New DirectoryCatalog(Dir)

Dim Container As New CompositionContainer(Catalog)

Container.SatisfyImportsOnce(Me)

End Sub

Private _Macros As IEnumerable(Of IMEFMacro)

<ImportMany(GetType(IMEFMacro))> _

Private Property Macros() As IEnumerable(Of IMEFMacro) Implements IAddIn.Macros

Get

Return _Macros

End Get

Set(ByVal value As IEnumerable(Of IMEFMacro))

_Macros = value

End Set

End Property

Private Sub RunMacro(ByVal MacroName As String) Implements IAddIn.RunMacro

For Each m As IMEFMacro In Macros

If m.Name = MacroName Then

m.Run(Application, MyContact)

End If

End Sub

End Class

MEF Extension code:

Imports System.ComponentModel.Composition

Imports Interfacelibrary

<Export(GetType(IMEFMacro))> _

Public Class AddJohnSmith

Implements IMEFMacro

Public ReadOnly Property Name() As String Implements IMEFMacro.Name

Get

Return "Add John Smith"

End Get

End Property

Public Sub Run(ByVal Application As IContactClass, ByVal Contact As IContactObj) Implements IMEFMacro.Run

Contact.FirstName = "John"

Contact.LastName = "Smith"

Application.AddContact(Contact)

End Sub

End Class

<Export(GetType(IMEFMacro))> _

Public Class AddJaneDoe

Implements IMEFMacro

Public ReadOnly Property Name() As String Implements IMEFMacro.Name

Get

Return "Add Jane Doe"

End Get

End Property

Public Sub Run(ByVal Application As IContactClass, ByVal Contact As IContactObj) Implements IMEFMacro.Run

Contact.FirstName = "Jane"

Contact.LastName = "Doe"

Application.AddContact(Contact)

End Sub

End Class

Now let’s walk through what this code does. When the user first builds the Macro addIn, and then after any subsequent builds, the AddIn runs the Compose method. This method looks in My Documents\ContactManager\Macros\Extensions for the MEF AddIn Extension. (When the MEF Extension template is built, it automatically installs Extension to this folder.) If an Extension is found, The Macro AddIn imports a collection of Macros from the extension. These Macros are then displayed in the Macro Manager, and can be run. This allows for AddIns themselves to be extensible. A user can import Macros from one or multiple files, and import them into the current Macro addIn project.

Here is a brief walkthrough of this process:

First, run the install file in the root folder of the source code.

Open the App, then select File then click Load IDE.

Build the Macro AddIn.

Click New Project at the top and select MEFAddIn.

Build the MEFAddIn.

Close and then Re-Open the IDE.

Rebuild the Macro AddIn.

Now select file and Click Run Macro.

You should see all the Macros specified in the Macro AddIn.

The Final Result:

I hope this journey has been beneficial in your understanding of VSTA and MEF. Please feel free to email me with any questions.

Chapter Four: Integrating the VSTA IDE

BillL — Tue, 28 Jul 2009 14:35:00 GMT

My integration journey is taking some exciting turns. As always, I would encourage you to read the first three posts in this series (Chapter One, Chapter Two, and Chapter Three) before reading this one.

I have finally integrated the VSTA IDE into my Contact Manager program. I am going to go through how I did this, show some code, and talk about some of the problems I encountered. Here is a link to my code:

The first thing to do is to run SetupContactManager.js (Right-click it and select Open with Commmand Prompt so you will. Now look in your MyDocuments folder. There should be a new folder with the name ContactManager. This is where the application will store the add-in and macro data for the program. All the files needed for this sample are included in the ZIP file, so you should not have to download any external dependencies (You will have to have the VSTA 2.0 SDK and SQL Server 2005 Express Edition installed, however.) Make sure any dependency errors are resolved, and then build the project. Open the application and click File then click Load IDE.

The VSTA IDE should open.

Now resolve the Interface Library dependency, by pointing it to the InterfaceLibrary.dll file under the main application's Debug folder.

Now create a method called Macro1 under the Startup and Shutdown methods. Make it do whatever you want.

When you are finished programming this method, go back to the main application and select File then Run Macro:

You should see this window:

Click Run, and the code in your Macro1 method will execute.

Here is an example:

Now I will walk you through the steps I took to get this functionality.

First, let me go over the features in VSTA that made this integration possible.

As you may already know, VSTA is software that allows the user of an application to run custom code in an application while the application is running, through a Visual Studio-like IDE. These custom bits of code are called AddIns. These Add-Ins are stored in a templates folder that is in the same folder as the application. When the user runs the Install batch file, it registers the application with the VSTA runtime using a specified name for the application called the HostID, and creates a folder for its Add-Ins in the MyDocuments folder. The user can now create Macros (custom user-created methods) in his Add-In.

Now let’s dig a little deeper in to the code that makes this possible.

If you look at my code, you will notice that I have added four new files to the solution: VSTADesignTimeIntegration.vb, VSTARuntimeIntegration.vb, MacroManager.vb, and MessageFilter.vb. I am not going to get into MessageFilter.vb, but I will give a brief overview of the other three:

VSTADesignTimeIntegration.vb is in charge of showing the IDE, opening and creating Macro projects, and debugging the Add-In.

VSTARuntimeIntegration.vb is in charge of loading and unloading Add-Ins and Macros.

MacroManager.vb contains the Macro manager user interface, updates the list of Macros, and gets the Macros’ names.

I encourage you to explore these files, and see how they work in the application. Also, look over the documentation provided with the VSTA SDK, especially the part about registering your application.

I am now going to walk you through what happens behind the scenes with VSTA in my application. In the AppLoad method, when the program is not run from script, the first workings of VSTA are started. The messagefilter is instantiated first. Once the messagefilter has been instantiated, the application instantiates VSTARuntimeIntegration and VSTADesignTimeIntegration, and runs their Connect methods. Because VSTARuntimeIntegration comes first, I will walk you through what happens when the application calls its Connect method. First, the application passes an instance of the host class (ContactClass) to VSTARuntimeIntegration. Then the application finds and loads the Add-ins, and runs their Startup methods. The Macros themselves are now loaded. Now the application instantiates VSTADesignTimeIntegration and runs its Connect method. Just like in VSTARuntimeIntegration, the VSTADesignTimeIntegration‘s Connect method passes in ContactClass. The application calls the methods in VSTADesignTimeIntegration when the application loads the IDE and on other IDE events, and when debugging Add-Ins. The Macro Manager provides a dialog box for viewing the available macros in the Add-In. It finds these macros by searching for methods in the Add-In that contain the string “Macro.” It then allows the user to either edit or run a macro based on what button the user clicks.

I have used in this application a type of integration called “design-time only.” This method of integration differs from the method outlined in the VSTA SDK documentation. This integration does not have the Add-In connect to the host using a proxy object, which is the standard integration procedure. Instead, the host imports the add-in using a byte-stream, and does not utilize a proxy object. Without the use of a proxy object, the integration process becomes much simpler. The downside to this is that once the Add-In loads, the host can’t unload the Add-In. In addition, any crash of the Add-In will also crash the host, and debugging the Add-In will pause the host. These downsides, while not necessarily an issue, must be kept in mind when deciding which integration method to use.

Now I will go over some problems I had while integrating VSTA, in hopes that you will know what to do if you run across these same issues. First, make sure that your Add-In template is located in the right folder (the folder specified in the CreateNewMacroProject method in the VSTADesignTimeIntegration.vb file), and that if you are using a setup file like the one in my application, you have the paths and HostID defined correctly.

One of the specific mistakes I made was to instantiate more variables than the program required. This caused various errors in getting my application to run properly. Utilizing good programming practices in general will be immensely beneficial to you in any programming scenario. Also, be very careful in translating code from one language to another: be sure that you recognize the differences in the languages you are translating (the language’s syntax, what you must explicitly define, how the language handles variables, etc.).

One other note:

If your program crashes or closes unexpectedly, check the processes in Task Manager to make sure an orphaned vsta.exe is not running. If it is, end it, or your computer will not shut down.

One other thing you may have noticed that has changed is the lack of a message box before the program loads. To ruin the Script, now you must specify a command-line argument of -s. I have created a shortcut to do this and put it in the Debug and Release folders.

In my previous post, I discussed the Managed Extensibility Framework. However, MEF cannot be used to import VSTA Add-Ins for one reason: once MEF has loaded an Add-In, it cannot alter the Add-In, because the Add-in is locked. That is why VSTA must get a byte stream of the Add-in and work with that, instead of loading the Add-In files themselves. I have integrated MEF into an Add-in itself, however, and will talk about this in my next post.

Chapter Three: MEF

BillL — Thu, 02 Jul 2009 17:20:00 GMT

For chapter three, I will be introducing a framework from Microsoft called the Managed Extensibility Framework, or MEF (MEF on CodePlex, MEF on MSDN ). If you are not familiar with MEF, you will certainly get more out of this post if you read the MEF overview and programming guide (MEF Overview, MEF Guide).

Now I will give a synopsis of what has changed in my code since the last revision. If you would like to look at my code, please download the attached file: Updated Sample with MEF

First, notice the Imports statements at the top of ContactClass.vb:

Imports System.ComponentModel.Composition

Imports System.ComponentModel.Composition.Hosting

Imports System.ComponentModel.Composition.ImportAttribute

Imports InterfaceLibrary

The top three statements import parts of the MEF library, and the bottom one is for the Interface Library, which we will get to a little later.

These next two methods are where ContactClass utilizes MEF:

'Imports the an Instance of the IAddIn interface.

<Import(AllowDefault:=True, AllowRecomposition:=True)> _

Public IContactAddIn As IAddIn

'Called by the ContactApp class's ContactApp_Load() method; asks if the user wants to run the App in script mode. The method then stores the user's response in a boolean variable,

'and, if the user's answer was yes, the method calls the Connect Method on the IContactAddIn Interface and passes in ContactClass.

Public Sub AppLoad()

UpdateDataset()

Dim MBResult = MsgBox _

("Would you like to run this program from Script?" + _ Environment.NewLine + "(If Yes, the Interface will be hidden.)", _ MsgBoxStyle.YesNo)

Select Case MBResult

Case MsgBoxResult.Yes

ScriptBool = True

Compose()

If Not IContactAddIn Is Nothing Then

IContactAddIn.Connect(Me)

Else

MessageBox.Show("No script to run.")

End If

ContactApp.Close()

Case MsgBoxResult.No

ScriptBool = False

End Select

End Sub

'Creates a Catalog from Assemblies in the AddIns directory, then creates a Container and creates a batch to add parts, and Composes these.

Public Sub Compose()

Dim Catalog As New DirectoryCatalog("AddIns")

Dim Container As New CompositionContainer(Catalog)

Dim Batch As New CompositionBatch()

Batch.AddPart(Me)

Container.Compose(Batch)

End Sub

The top <Import> statement tells MEF that ContactClass wants an IContactAddIn, and the AllowDefault parameter prevents an exception if no Add-In exists. The AllowRecomposition parameter allows MEF to look for an AddIn whenever the container is composed or refreshed.

The Appload method now calls a method called Compose. The Compose method creates a catalog, a container and a batch and composes them. (For a description of these, please see the MEF Overview and the wiki section on Composition Batch).

If MEF finds a suitable AddIn, AppLoad calls its Connect method and passes in ContactClass. If MEF doesn’t find an AddIn, the program closes without issue. Remember that the program only uses an AddIn if the user selects to run the program in script mode.

You may be wondering how the App and the AddIn communicate. The answer is found in the Interface Library:

'The Interface for ContactClass.

Public Interface IContactClass

Property ContactArray()

Delegate Sub ContactEventHandler(ByVal ca As IContactEventArgs)

Delegate Sub ActionEventHandler()

Event AddedContact As ContactEventHandler

Event DeletedContact As ContactEventHandler

Event EditedContact As ContactEventHandler

Event ContactsPrinted As ActionEventHandler

Event AddError As ContactEventHandler

Event DeleteError As ContactEventHandler

Event EditOldError As ContactEventHandler

Event EditNewError As ContactEventHandler

Event ContactsPrintedError As ActionEventHandler

Function CreateNewContactObj() As IContactObj

Sub AddContact(ByVal Contact As IContactObj)

Sub DeleteContact(ByVal Contact As IContactObj)

Sub EditContact(ByVal OldContact As IContactObj, _

ByVal NewContact As IContactObj)

Sub PrintList()

End Interface

'The interface for the ContactEventArgs in ContactClass.

Public Interface IContactEventArgs

Property Contact() As IContactObj

End Interface

'The Interface for ContactObj.

Public Interface IContactObj

Property FirstName()

Property LastName()

Property HomePhone()

Property CellPhone()

Property WorkPhone()

Property Email()

End Interface

'The Interface for the AddIn.

Public Interface IAddIn

Sub Connect(ByRef TheContact As IContactClass)

End Interface

The Interface Library provides the language with which the App and the Add-In speak to each other. It acts as a blueprint for what is contained in the App and the AddIn, and allows them both to communicate without holding design-time references to each other.

Now let’s look at the AddIn itself.

Imports System.IO

Imports System.ComponentModel.Composition

Imports InterfaceLibrary

'This class is only used when the user runs the App in script mode.

<Export(GetType(IAddIn))> Public Class ContactAuto

Implements IAddIn

Private MyContactClass As IContactClass

Private MyArray As Array

Private stwr As New StreamWriter("Log.txt", True)

Private Event AllContactsNormalized()

Private Event ContactsNormalizedError()

'Gets an instance of ContactClass and creates an instance of an array that is in that class. It also creates the log file.

Public Sub Connect(ByRef TheContact As IContactClass) Implements IAddIn.Connect

MyContactClass = TheContact

MyArray = MyContactClass.ContactArray

stwr.AutoFlush = True

Run()

End Sub

Notice the Export statement, and how its specified type matches that of the Import statement in ContactClass. When MEF looks in the AddIns folder, it will add this to the catalog, and the container will match it with the Import statement in ContactClass.

Here is a diagram of how the whole Application works:

ContactAuto references the Interface Library, as does ContactClass, but The Interface Library does not reference either of them,. If ContactAuto exists, ContactClass calls its Connect method, which it knows about through the Interface library.

This design allows the AddIn to be free of the Application, and allows a programmer to alter the AddIn without altering the main program. All any new Add-Ins would have to do is reside in the right folder, have a Connect method, and specify an export statement. MEF provides this excellent way of discovering AddIns, and allows for a great amount of Application extensibility. There is a possibility for MEF use in a VSTA integration, so I would encourage you to experiment with this new concept.

Chapter Two: Loading Add-ins

BillL — Mon, 29 Jun 2009 14:34:00 GMT

Here is the second chapter in my integration journey. If you have not looked at the first blog post, it would be a good idea to look there first, because that post will explain the application I am working with and my idea behind it.

First, let’s look at a few things that have changed since my first app. If you open the attached .zip file, you will notice that I have separated the ContactClass and ContactObj classes into their own files. The largest change to this app by far, however, is the way the script (which I will refer to as an Add-In) loads and runs. You may recall that the app formerly had the script file right in the project. For this app revision, the script runs entirely from a .dll file (VB class library). I can do this now, because the main app no longer has to reference the script file. The script file must reference the main app, but not the other way around. Let me show you how I did this:

IAddIn.vb:

'Defines an interface with which to connect to the addin.

Public Interface IAddIn

Sub Connect(ByRef TheContact As ContactClass)

End Interface

ContactClass.vb:

'Called by the ContactApp class's ContactApp_Load() method; asks if the user wants to run the app in script mode. The method then stores the user's response in a boolean variable, and, if the user's answer was yes, the method calls the LoadAddin method and passes in the name of the addin file and the name of the addin class.

Public Sub AppLoad()

UpdateDataset()

Dim MBResult = MsgBox("Would you like to run this program from Script?" + Environment.NewLine + "(If Yes, the Interface will be hidden.)", MsgBoxStyle.YesNo)

Select Case MBResult

Case MsgBoxResult.Yes

ScriptBool = True

LoadAddin("AddIns/ContactAuto.dll", "ContactAuto.ContactAuto")

ContactApp.Close()

Case MsgBoxResult.No

ScriptBool = False

End Select

End Sub

'Loads the specified addin and runs its connect method.

Private Function LoadAddin(ByVal addinPath As String, ByVal startUpClass As String) As IAddIn

Try

Dim assemStream() As Byte = Nothing, pdbStream() As Byte = Nothing

Using fs As New FileStream(addinPath, FileMode.Open)

assemStream = New Byte(fs.Length) {}

fs.Read(assemStream, 0, CType(fs.Length, Integer))

End Using

Dim pdbPath As String = Path.Combine(Path.GetDirectoryName(addinPath), Path.GetFileNameWithoutExtension(addinPath) + ".pdb")

Dim hasPdb As Boolean = False

If File.Exists(pdbPath) Then

Using fs As New FileStream(pdbPath, FileMode.Open)

pdbStream = New Byte(fs.Length) {}

fs.Read(pdbStream, 0, CType(fs.Length, Integer))

hasPdb = True

End Using

Else

Debug.WriteLine("Cannot find the pdb file: " + pdbPath)

End If

Dim assem As System.Reflection.Assembly

If Not hasPdb Then

assem = Assembly.Load(assemStream)

Else

assem = Assembly.Load(assemStream, pdbStream)

End If

Dim t As Type = assem.GetType(startUpClass)

Dim addin As IAddIn = CType((System.Activator.CreateInstance(t)), IAddIn)

addin.Connect(Me)

Return addin

Catch ex As Exception

' Do not let error of this Add-in affect others

System.Diagnostics.Trace.WriteLine(ex.ToString())

System.Diagnostics.Debug.Assert(False)

Return Nothing

End Try

End Function

Direct your attention first up to the IAddIn interface. You can see that all it references is the Connect method in ContactAuto. This interface provides a sort of bridge between the ContactAuto class library and the main application. Now look at the AppLoad method. Notice that it calls a method by the name of LoadAddIn and specifies two parameters. This LoadAddIn method is a part of a VSTA design-time-only integration and is the core to the whole scripting process in this app. All that the AppLoad method needs to do is call the LoadAddIn method and pass it the path to the .dll file (class library) and the class in the library in which to start. Once the method loads and parses the .dll file, it will call the Connect method in the IAddIn interface. The app does not need to reference the script library, it just knows how to load a certain file out of a certain directory, and call the Connect method on it through the IAddIn interface. The Add-In must still hold a reference to the main app, so it can call the app’s methods and handle the app’s events, but the Add-In can be separate from the app. The app does not have to know anything about it other than where it is, one of its classes, and that it has a Connect method. Here is a simple diagram of how ContactClass, IAddIn, and ContactAuto interact:

ContactAuto references ContactClass, but ContactClass does not reference ContactAuto. If ContactAuto exists, ContactClass calls its Connect method through the IAddIn interface.

This design allows the Add-In to be free of the application, and allows a programmer to alter the Add-In without altering the main program. All any new Add-Ins would have to do is reside in the right folder, and have a Connect method and a class that is the same name as the one specified in the start-up class parameter of LoadAddIn. This is one way of discovering and loading Add-Ins. I will be showing you a different, even more “Loosely Coupled” way in my next post.

Chapter One: A Sample Program and Inversion of Control

BillL — Thu, 18 Jun 2009 19:00:00 GMT

My name is Bill, and I am an integration newbie.

The purpose of my blog is to chronicle my experiences as I work to integrate Visual Studio Tools for Applications into my own program. Hopefully, this will help other programmers get started with VSTA integration.

The purpose of the sample in this particular blog post is to introduce the application I will be integrating with VSTA, and to introduce the concept of Inversion of Control and its benefits to software development.

Here is a brief and very basic explanation of Inversion of Control:

Imagine a class named ClassA. ClassA is the main class for an application and has dependencies on two other classes, Class 1 and Class 2:

Class ClassA

Private x, y, a, b, c As Integer

Private str As String

Sub Main()

MyClass1 As New Class1

MyClass1.DoSomething(x, y)

MyClass2 As New Class2

MyClass2.DoSomethingElse(a, b, c)

str = MyClass2.DoEvenMore()

Console.WriteLine(str)

End Sub

End Class

If the programmer wants to make any significant changes to either of these dependencies, they must also change the main class’s code. For example, if the programmer changed Class1, he would also have to change the code in ClassA for his program to compile, let alone run! The programmer wants to be able to change the code in Class1 or Class2 without altering ClassA. Right now, this is not possible because of ClassA’s dependencies on Class1 and Class2. The way to make this possible is to by use Inversion of Control. Inversion of Control, at its most basic level, is, instead of having Class A run methods in Classes 1 and 2, Classes 1 and 2 would actually run (call into) methods in Class A, the main class.

Class A is the main application, so the programmer will not want to change that, just some of its dependencies (Classes 1 and 2). All ClassA has to do is start both of them, and then allow them to control ClassA. Instead of ClassA controlling them, as is normal, Classes 1 and 2 are controlling Class A.

To start the process of implementing Inversion of Control with VSTA, I made a relatively simple application called “Contact Manager,” which does precisely what its title would imply. The user can control this application by either using the GUI or by letting the application run silently from a script. The script has the ability to add, delete and edit contacts based on user-generated data in text file in the program’s directory. It will also normalize all contacts in the database (capitalize the first and last names) and print out a sorted, formatted list of all contacts in the database.

The GUI has printing as well as adding, deleting and editing capabilities. When contacts are added or edited (in both script mode and interface mode), they are automatically normalized (the first and last names are capitalized). Another feature of the interface is its searching ability. The user can search for all or part of the first or last name of a contact, and the app will display all the results to the user.

Now that we’ve gone over the program’s functionality, let’s look deeper at the code itself. I have attached my source code for this project and I would encourage you to look at that as well.

The MainForm.vb file has three main classes: ContactClass, ContactApp and ContactObj. Let’s walk through their important parts:

1. ContactClass: the class that handles most of the behind the scenes work. It updates and alters the data in the database based on either script commands or interface commands. This class also contains a sub-class, ContactEventArgs, which defines the arguments for all the events in ContactClass. Here are the methods for ContactClass:

Public Sub AppLoad()	Asks if the user wants to run the app in script mode, then takes appropriate action based on the user’s input.
Public Sub UpdateDataset()	Updates the dataset and the array.
Private Function GetContactID (ByVal Contact As ContactObj) As Integer	Gets the automatically assigned ID for the specified contact from the dataset
Public Sub AddContact(ByVal Contact As ContactObj)	Adds the contact to the database, or gives an error if the contact already exists
Public Sub DeleteContact(ByVal Contact As ContactObj)	Deletes the contact from the database, or gives an error if the contact does not exist (Script mode only).
Public Sub EditContact(ByVal OldContact As ContactObj, ByVal NewContact As ContactObj)	Edits the contact, or gives an error.
Private Sub NormalizeContact (ByRef Contact As ContactObj)	Capitalizes the first letter of the first and last name values in the contact.
Public Sub PrintList()	Prints a sorted list of all the contacts in the database if the database is not empty.
Public Sub PrintDocument1_PrintPage (ByVal sender As System.Object, ByVal e As System.Drawing.Printing. PrintPageEventArgs)	Creates the contact list page(s) of sorted contacts.

Let’s take a closer look at the AppLoad method:

ContactApp class's ContactApp_Load method calls this method. It asks if the user wants to run the app in script mode if yes, the Connect method on ContactAutoClass is called and passed ContactClass.

Public Sub AppLoad()

UpdateDataset()

Dim MBResult = MsgBox("Would you like to run this program from Script?" + Environment.NewLine + "(If Yes, the Interface will be hidden.)", MsgBoxStyle.YesNo)

Select Case MBResult

Case MsgBoxResult.Yes

ScriptBool = True

MyContactAuto.Connect(Me)

ContactApp.Close()

Case MsgBoxResult.No

ScriptBool = False

End Select

End Sub

End Class

2. ContactApp is the main class for the User Interface. Updates but does not edit content. All other interface forms in the application behave in a way similar to this.

If the user runs the program in Script mode, the only methods in this class that are used are ContactApp_Load and PrintDocument1.Print.

If the user runs the program in interface mode, this class becomes the bridge between the actual interface and the behind-the-scenes work: ContactApp calls the right methods in ContactClass based on what the user selects in the interface.

Private Sub ContactApp_Load (ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load	When the app starts, this method centers the app to the screen, calls AppLoad in ContactClass, and populates the list box.
Private Sub AddContactToolStripMenuItem_Click (ByVal sender As System.Object, ByVal e As System.EventArgs) Handles AddContactToolStripMenuItem.Click	When the Add Contact tool strip item is clicked, this method loads the AddContactForm.
Private Sub EditContactToolStripMenuItem_Click (ByVal sender As System.Object, ByVal e As System.EventArgs) Handles EditContactToolStripMenuItem.Click	Brings up the Edit Contact Form if the user has selected a contact in the list box.
Private Sub DeleteContactToolStripMenuItem_Click (ByVal sender As System.Object, ByVal e As System.EventArgs) Handles DeleteContactToolStripMenuItem.Click	Deletes a selected contact if the user has selected a contact in the list box.
Private Sub AboutToolStripMenuItem_Click (ByVal sender As System.Object, ByVal e As System.EventArgs) Handles AboutToolStripMenuItem.Click	Shows the About box.
Private Sub ExitToolStripMenuItem_Click (ByVal sender As System.Object, ByVal e As System.EventArgs) Handles ExitToolStripMenuItem.Click	Closes the app.
Private Sub FindToolStripMenuItem_Click (ByVal sender As System.Object, ByVal e As System.EventArgs) Handles FindToolStripMenuItem.Click	Shows the Find dialog.
Private Sub ListBox1_SelectedIndexChanged (ByVal sender As System.Object, ByVal e As System.EventArgs) Handles ListBox1.SelectedIndexChanged	Shows the contact values in their respective fields when the user selects a contact in the list box.
Private Sub PrintContactListToolStripMenuItem_Click (ByVal sender As System.Object, ByVal e As System.EventArgs) Handles PrintContactListToolStripMenuItem.Click	Shows a preview of the document to be printed.
Public Sub FillListBox()	Populates the list box on the main form.
Private Sub ListBox1_KeyDown (ByVal sender As Object, ByVal e As System.Windows.Forms.KeyEventArgs) Handles ListBox1.KeyDown	Allows the user to use the Delete, Insert, and F1 keys to Delete a selected contact, Add a new contact, and show the About Box, respectively.

3. ContactObj is the class that defines what a Contact is and provides methods for accessing and altering Contact data. Other than methods for accessing and altering its properties and an overload of the CompareTo method, the ContactObj class has no methods:

Public Overloads Function CompareTo(ByVal obj As Object) As

Integer Implements IComparable.CompareTo

Public Property FirstName()

Public Property LastName()

Public Property HomePhone()

Public Property CellPhone()

Public Property WorkPhone()

Public Property Email()

The other important file is ContactAuto.vb, which contains ContactAuto. The methods in ContactAuto only run when the app is in Script mode. This file has only one class, ContactAuto. Let me direct your attention to the methods Connect and Run. ContactApp calls both these methods. Look at ContactApp in MainForm.vb for a moment. Notice first how ContactApp_Load calls a method called AppLoad in ContactClass. AppLoad gets user input on whether or not to run the app in script mode. If the user decides to run the app in script mode, AppLoad calls Connect in ContactAuto and passes in ContactClass. Connect stores ContactClass, and gets the contact array from its instance of ContactClass and stores it separately. It then calls the Run method. The Run method controls all of the automation of ContactClass. Other than connect and the various event handlers, Run calls all of the methods in ContactAuto. ContactAuto as a whole has four main automation abilities: It can add, delete and edit contacts based on text files, and will create those text files if they do not exist in the Contact Manager directory. AddFromFile, DeleteFromFile, and EditFromFile define the procedures for reading the text files, but methods in ContactClass carry out any changes to the actual database. The second automation ability is the normalization (capitalization of the contact’s first and last name) of all contacts in the ContactArray and the Database. Whenever ContactClass adds or edits a contact it automatically normalizes that contact, but if the user decides to alter the code to connect to a different database, whoever or whatever originally inputted that data might not have normalized the data. The NormalizeAllContacts method ensures that no matter what database is used, the app will have normalized all its contacts.

The third automation ability is printing a list of all contacts in the database. The actual page setup is defined in ContactClass, and this setup is used both by User Interface printing and script printing. The script differs from the interface by printing the list automatically instead of showing the user a preview. This, along with the other methods in Run, allows the user to start the program, and then have the program run without user intervention once the user selects yes in this message box:

The last automation ability is the logging of all actions taken by the script, as well as any errors encountered, and the date and time of these events. Each logging method is a handler for an event that an action raises when it either completes successfully or encounters a problem. The app saves all logging to Log.txt, which the app creates if it does not already exist. The app will not overwrite this log file in subsequent runs of the program. From the time that the log file is created, all data written to the log file stays in it unless cleared by the user.

Public Sub Connect(ByRef TheContact As ContactClass)	Gets an instance of ContactClass and creates an instance of an array that is in that class. It also creates the log file.
Public Sub Run()	Creates handlers for the events in this class and ContactClass, and calls the methods for contacts to be added, deleted, edited, normalized, and printed.
Private Sub AddFromFile()	Imports contacts from a text file and adds them to the the database through ContactClass.AddContact.
Private Sub DeleteFromFile()	Imports contacts from a text file and deletes them from the the database through ContactClass.DeleteContact.
Private Sub EditFromFile()	Imports contacts to be edited from a text file and applies the changes to the database through ContactClass.EditContact.
Private Sub ReplaceNullValues(ByRef Contact As ContactObj)	Changes null values in each imported contact to empty strings so as to prevent exceptions.
Private Sub NormalizeAllContacts(ByRef ContactArray As Array)	Capitalizes the first letter of the first and last names of all contacts in the contact array.
Private Sub PrintContactList()	Calls the PrintList method in MyContact (which prints out a a sorted list of all contacts in the database), then raises the ContactsPrinted event.
Private Sub WriteAddToLog (ByVal ca As ContactClass.ContactEventArgs)	When the AddedContact event is raised in ContactClass, it is handled by this method, which logs the event and relevant data.
Private Sub WriteDeleteToLog (ByVal ca As ContactClass.ContactEventArgs)	When the DeletedContact event is raised in ContactClass it is handled by this method, which logs the event and relevant data.
Private Sub WriteEditToLog (ByVal ca As ContactClass.ContactEventArgs)	When the EditedContact event is raised in ContactClass it is handled by this method, which logs the event and relevant data.
Private Sub WriteNormalizationToLog()	When the ContactsNormalized event is raised in the NormalizeContacts method it is handled by this method, which logs the event and relevant data.
Private Sub WritePrintingToLog()	When the ContactsPrinted event is raised in the PrintContactList method it is handled by this method, which logs the event and relevant data.
Private Sub WriteAddErrorToLog(ByVal ca As ContactClass.ContactEventArgs)	When the AddError event is raised in ContactClass it is handled by this method, which logs the event and relevant data.
Private Sub WriteDeleteErrorToLog(ByVal ca As ContactClass.ContactEventArgs)	When the DeleteError event is raised in ContactClass it is handled by this method, which logs the event and relevant data.
Private Sub WriteEditOldErrorToLog(ByVal ca As ContactClass.ContactEventArgs)	When theEditOldError event is raised in ContactClass it is handled by this method, which logs the event and relevant data.
Private Sub WriteEditNewErrorToLog(ByVal ca As ContactClass.ContactEventArgs)	When theEditNewError event is raised in ContactClass it is handled by this method, which logs the event and relevant data.
Private Sub WriteNormalizationErrorToLog ()	When theContactsNormalizedError event is raised in ContactAuto it is handled by this method, which logs the event and relevant data.
Private Sub WritePrintingErrorToLog()	When theContactsPrintedError event is raised in ContactClass it is handled by this method, which logs the event and relevant data.

Reason for the Design:

The reason for this design is greater extensibility of the application through Inversion of Control, as discussed in the introduction.

As an example, look here at the AddFromFile method in ContactAuto:

Try

Dim str As New StreamReader("Add.txt")

Dim line

Dim Contact As New ContactObj

line = str.ReadLine()

Contact.FirstName = line

line = str.ReadLine()

Contact.LastName = line

line = str.ReadLine()

Contact.HomePhone = line

line = str.ReadLine()

Contact.CellPhone = line

line = str.ReadLine()

Contact.WorkPhone = line

line = str.ReadLine()

Contact.Email = line

If (Contact.FirstName <> Nothing) And (Contact.LastName <> Nothing) Then

ReplaceNullValues(Contact)

MyContact.AddContact(Contact)

End If

line = str.ReadLine()

Loop Until line = Nothing

str.Close()

Catch ex As FileNotFoundException

End Try

Dim stwa As New StreamWriter("Add.txt")

stwa.Flush()

stwa.Close()

The programmer could change this to do whatever the programmer wants, because it uses the Inversion of Control Principle. All the ContactClass AddContact method needs to know is that if anything passes in a contact object it should add it to the database. The ContactAuto class can get a contact however it wants, and the ContactClass will add it the same way. The ContactAuto class is calling a method in ContactClass, and thereby controlling it-An external class is controlling the main class!

Now let’s look at the main class’s dependency diagram:

The ContractObj is the main data type used in this sample. The ContactClass functions independently of the GUI. In addition, no outside forms (Such as the AddContactForm) connect directly to ContactClass. If these forms need to call something in ContactClass, they do it through ContactApp’s instance of ContactClass.

Inversion of control works well with this program, as the programmer can change ContactAuto, ContactApp, and all the other forms without needing to change much of anything in ContactClass. This makes the application very extensible, as the programmer can tailor the script and forms to match each customer’s specifications without the programmer having to build a new application every time. This ability is one of the fundamental advantages of VSTA, and one of the ways VSTA is a great time- and money-saver.