VSTA v 1 ShapeAppBasicVB Samples and Walkthrough

This zip file includes the ShapeAppVB and ShapeAppBasicVB applications as well as a walkthrough.  The walkthrough will take you step by step integrating VSTA into ShapeAppVB.  Once the walkthrough is complete, the host application will search for and load two add-ins created using a project template.  This is based on the ShapeAppCSharp walkthrough included with the VSTA SDK.

Overview:

This walkthrough will guide you through the steps of integrating VSTA into ShapeAppVB so that it searches for and loads add-ins.  To change the base application ShapeAppVB to the integrated application ShapeAppBasicVB the following steps must be taken, each step contains several tasks with detailed step-by-step instructions:

1.       Create the host application library (HostApp.exe).

For this walkthrough ShapeAppVB will be the host application.  The host application should be completed prior to integration because changes in the HostApp.exe may require changes in the proxy and type Infrastructure manager files. 

2.       Create the proxy.

Proxies allow for communication between the host application and add-ins.  The proxy layer is a C# code file generated by the Visual Studio 2005 Tools for Applications tool ProxyGen and the proxy dll is used to create project templates.  For integration, a proxy project is added to the solution of the host application.   

3.       Register the host application.

Visual Studio 2005 Tools for Applications maintains a collection of settings that pertain to host applications and requires that host applications are registered by adding a key to the registry.  These keys are used for VSTA to distinguish host applications from one another and can be used to specify some properties of the host application- such as its name and default template location. 

4.       Create project templates.

Project templates enable end-user developers to use Visual Studio 2005 Tools for Applications to create add-ins that extend your application.  Project templates are generated using the ProjectGen tool and include files, references, default project properties, and compiler options. 

5.       Create the TypeInfrastructureManager.

Type maps are used to determine how to convert types between the object model of the host application and the proxy types of the add-in assemblies.  The TypeinfrastructureManager is a C# code file generated by the Visual Studio 2005 Tools for Applications tool ProxyGen.  For integration, a TypeInfrastructureManager project is added ot the solution of the host application.   

6.       Modify the host application to load add-ins.

Visual Studio 2005 Tools for Applications provides the add-in management API which allows applications to load and unload add-ins.  A Host Item Provider enables the add-ins to access the object model of the application and type maps are used to convert types between the add-in assemblies and the object model of the host application.  For integration, a host item provider, type infrastructure manager, and API code are added to the host solution. 

7.        Test the updated host application.

Following the steps outlined in this walkthrough will result in a host application and two add-ins.  The host application has been modified to find and load the add-ins.  This achieves basic integration of Visual Studio 2005 Tools for Applications into the host application.

Introduction

This sample is based heavily on the ShapeAppCSharp examples distributed with the VSTA SDK.  It is not necessary to perform the SDK walkthrough for or be familiar with the ShapeAppCSharp or ShapeAppMFC samples prior to this one. 

ShapeAppVB

This sample contains the source code for the unmodified ShapeAppVB application.  Use this sample to learn how ShapeAppVB works and how the ShapeAppVB object model is designed.

ShapeAppVB provides the following features:

·         Users can create documents that are displayed in a tabbed interface.

·         Users can drag shapes onto documents.  The shapes include squares, stars, circles, triangles, and octagons.

·         Users can modify the location, size, or color of shapes in documents by right-clicking shapes and clicking shortcut menu commands.

·         Users can save documents and the current state of the shapes on the documents.

ShapeAppBasicVB

This sample contains the source code for a basic integration of Visual Studio 2005 Tools for Applications with ShapeAppVB. This sample also includes project templates for ShapeAppBasicVB and the source code for an application-level add-in. Use the ShapeAppBasicVB sample to learn about the core integration tasks that you must perform for any host application that is integrated with Visual Studio 2005 Tools for Applications.

ShapeAppBasicVB demonstrates the following integration tasks of Visual Studio 2005 Tools for Applications:

·         How to generate proxies for the object model of ShapeAppVB. The proxies for ShapeAppVB are located in the ShapeAppVBProxy project. The Proxy.cs file contains the proxy code, and the ShapeAppVBOM.xml file contains the XML proxy descriptor file. For more information about proxies, see “Creating Proxies Using the Proxy Generation Tool (Proxygen.exe)” in the SDK.

·         How the register ShapeAppVB, and create project templates as well as application level add-ins.

·         How to modify ShapeAppVB to load application-level add-ins using the add-in management API. This code is located in the HostItemProvider.vb and Program.vb files. For more information about the add-in management API, see “Add-in Management Overview” in the SDK.

Differences between ShapeAppVB and ShapeAppCSharp

In translating the ShapeApp program from C# to VisualBasic.Net several changes where necessary. Other changes were made to accommodate programming and organizational styles.  Here is a partial list of changes:

·         Namespace was reduced from Microsoft.VisualStudio.Tools.Application.Samples.ShapeApp to ShapeAppVB.  Because this changes the full name of the shapes saved in the files, it prevents files from one version being opened in another.

·         Implicit Operator Overloading in the structs for System.Drawing.[Color, Point, Size] were changed to the overloaded method ConvertToSystemDrawing in each struct.  There are two methods in each struct- one accepts no input and returns the System.Drawing.[Color, Point, Size] equivalent of the local structure, the other accepts a structure as input and returns the System.Drawing.[Color, Point, Size] equivalent of the structure passed in.

·         The file drawingSurface_DragDrop.cs contained only one method- drawingSurface_DragDrop.  This method was moved into the Drawing file and the original file was removed from the project.

·         The file Utilities.cs contained only one class- ShapeDragDropInfo.  This file was renamed ShapeDragDropInfo to avoid confusion.

·         The shapes (circle, octagon, square, star, and triangle) as well as their base classes (Shape, IShape, and SolidPathShape) were changed from internal to public to avoid a scope problem with the TypeInfrastructureManager file. 

·         Array base 0 handling.  In a few places (rebuildWindowMenu in ApplicationForm) code designed to work around array handling had to be modified to avoid null reference exceptions.

·         Variable name changes.  In the CSharp version the naming convention for properties was:

o   Local variable:  propertyName

o   Public property:  PropertyName

This case sensitive convention is not compatible with Visual Basic and was changed to:

o   Local variable:  propertyName_value

o   Public property:  PropertyName 

·         GUI background color- changed for ease in distinguishing the version.

·         The files were reorganized. 

Walkthrough to integrate ShapeAppVB to ShapeAppBasicVB

Note:  For the Visual Studio 2005 Command Prompt commands the following assumptions were made.  Be sure to copy each command as one line only, by not selecting past the last character and make changes as necessary:

·         The system drive is “C”.

·         The files are extracted and placed as directed in C:\ShapeAppSamples.

·         Visual Studio 2005 Tools for Applications SDK is installed in the default directory.

·         The 2007.02 SDK is installed. 

Create the Host Application Library

I)         Extract, build, and run the ShapeAppVB solution.

1.       Extract the zip file to the folder C:\ShapeAppSamples.  It is strongly suggested that you use this directory, if you do not you will need to make changes. 

2.       Open the solution by selecting the ShapeAppVB.sln file in C:\ShapeAppSamples\ShapeAppVB\ShapeAppVB.

3.       Build and run the solution by pressing F5 in Visual Studio 2005 DTE.  The ShapeAppVB application should now appear.

4.       Create a drawing by selecting the new file icon, and then drag a shape onto the drawing surface from the shape menu to the left of the drawing surface.  Save this as Document1 in the ShapeAppVB folder.

5.       Close the application, but leave the project open in Visual Studio 2005.

 Create the Proxy

II)       Create a proxy project in the ShapeAppVB solution

The proxy file will be created using the tool ProxyGen.  ProxyGen outputs descriptor files in XML format and code files in CSharp.  More language output options may be available in the next release.  For more information on ProxyGen see the Proxy Generation Tool section under tools in the Visual Studio 2005 Tools for Applications SDK.

1.       Within Visual Studio 2005 in the ShapeAppVB solution, from the File menu select Add then New Project.

2.       Under the Project types pane ensure that you are in the Visual C# node.

3.       Under the Templates pane select Class Library.

4.       Name the new project ShapeAppVBProxy, select C:\ShapeAppSamples\ShapeAppVB for the location.

5.       Click OK to add the new project.

6.       Remove the default Class1.cs file by right clicking on it in the Solution Explorer pane and selecting Delete.

7.       Sign the assembly with a strong name.

                     i.            Right click ShapeAppVBProxy in the Solution Explorer and select Properties.

                   ii.            On the Signing tab, select Sign the assembly check box.

                  iii.            In the Choose a strong name key file list box, select New.  This will open the Create Strong Name Key dialog box.

                 iv.            In the Key file name box type “key.snk”.

                   v.            Ensure that the Protect my key file with a password is not checked.

                 vi.            Click OK, but leave the Properties page open.

8.       Change the build path to match the ShapeAppVB build path

                     i.            In the Properties page, select the Build tab.

                   ii.            Under the Output section select the Browse button next to the Output path box.

                  iii.            In the Select Output Path window navigate to the folder C:\ShapeAppSamples\ShapeAppVB\ShapeAppVB\bin\Debug.

                 iv.            Click Open to change the build path.

9.       Build the project pressing Ctrl + Shift + B.

III)      Create the proxy descriptor and proxy code file.

1.       Create the proxy descriptor file using ProxyGen.

                     i.            Open the Visual Studio 2005 Command Prompt.

·         Select the Start button from the Window’s desktop.

·         Select All Programs, then Microsoft Visual Studio 2005.

·         Select Visual Studio Tools then Visual Studio 2005 Command Prompt.

                   ii.            Change the directory to the ProxyGen folder.

                  iii.            Use ProxyGen to create a descriptor xml and proxy code file using the ShapeAppVB.exe as the library to base the proxy on.  Several errors will be generated stating that the Create_Instance and Dispose_Instance of type MyForms contains generic parameters and will be excluded, that Generics Members are not supported and will be replaced by System.Object, and that Static members are not supported and can be enabled by setting isExcluded=false.  These errors do not affect the end result and may be ignored.  If you receive an error stating that an unrecoverable error was encountered, check that there is no space between the colon following the commands and the quotation mark specifying the file.

                 iv.            Leave the command prompt open.

2.       Add the Entry Point to the descriptor file

                     i.            Add the ShapeAppVBOM.xml file created by ProxyGen to the ShapeAppVBProxy project in the ShapeAppVB solution in Visual Studio 2005.

·         In the ShapeAppVB solution, right click on the ShapeAppVBProxy project in the Solution Explorer.

·         Select Add, then Existing Item.

·          In the Add Existing Item – ShapeAppVBProxy window, change the Files of type filter to All Files.

·         Select the ShapeAppVBOM.xml file.

·         Select Add to add the file to the project.

                   ii.            In the ShapeAppVBOM.xml descriptor file, find the class with the originalFullyQualifiedName “ShapeAppVB.Application” (use the find function).

                  iii.            Add the attribute isAddInEntryPoint=”true” after the attribute isStatic=”false” for this class.

3.       Correct the nested class syntax by changing all “+” to “.” using the replace all function for the ShapeAppVBOM.xml document (there should be 4 occurrences).  This is a known bug in ProxyGen and should be corrected in the next release.  In the meantime, all nested classes will appear as “ClassMain+ClassNested” instead of “ClassMain.ClassNested” and need to be corrected manually.

4.       Save the file.

5.       Use the descriptor file to further define the auto-generated Proxy.cs output code.        

                     i.            In the command window use ProxyGen to update the Proxy.cs file.  This must be done with the descriptor file only WITHOUT using a library for basis.  This is because ProxyGen has known problems using Visual Basic libraries for this step and should be corrected in the next release.

                   ii.            An error stating that ProxyGen was unable to generate a proxy for ShapeAppVB.My.MyProject will appear.  This error may be ignored.  If an error stating that the ‘+’ character cannot be included in a name appears, check that you have followed steps III.3 – III.4 correctly and retry.

IV)    Create the Proxy DLL.

1.       Add the auto generated proxy file to the ShapeAppVBProxy project.

                     i.            Within Visual Studio 2005, in the ShapeAppVB solution, right click on the ShapeAppVBProxy project in the Solution Explorer pane.

                   ii.            Select Add, then Existing Item.

                  iii.            In the Add Existing Item – ShapeAppVBProxy window select the file Proxy.cs.

                 iv.            Select the Add button to add the file.

2.       Add the necessary references for the proxy file.

                     i.            Right click on the ShapeAppVBProxy project in the Solution Explorer pane.

                   ii.            Select Add Reference.  The Add Reference window should now appear.

                  iii.            Select the following references to add (select multiple references by holding the control key):

·         Microsoft.VisualStudio.Tools.Application.Adapter

·         Microsoft.VisualStudio.Tools.Application.Contract

·         System.AddIn.Contract

·         System.Drawing*

·         System.Windows.Forms*

*These references are specific to this project.  The other references are needed by all proxy projects.

                 iv.            Select the OK button to add the selected references.

3.       Build the Proxy.dll by pressing Ctrl + Shift + B.

Register the Host Application

V)        Register the Host Application.

1.       Create a folder named “Templates” in C:\ShapeAppSamples\ShapeAppVB.  This is where the project templates will be stored.

2.       Click Start, then Run to bring up the Run window.

3.       In the Run window, type “regedit” then press OK to bring up the Registry Editor.

4.       In the Registry Editor navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSTAHostConfig.

5.       Add a node for ShapeAppVB.

                     i.            Right click on the VSTAHostConfig node and select New, then Key.

                   ii.            Name the new folder “ShapeAppVB”.

6.       Add registry entries for AppName and the ProjectTemplatesLocation.

                     i.            Right click on the ShapeAppVB folder under the VSTAHostConfig folder.

                   ii.            Select New then String Value.

                  iii.            Change the new entry’s name to “AppName”, then double click it to bring up the Edit String dialog.

                 iv.            In the Edit String dialog enter “ShapeAppVB” then press OK.

                   v.            Right click on the ShapeAppVB folder.

                 vi.            Select New then String Value.

                vii.            Change the new entry’s name to “ProjectTemplatesLocation”, then double click to bring up the Edit String dialog.

              viii.            In the Edit String dialog type the path of the Templates folder created above in step V.1, “C:\ShapeAppSamples\ShapeAppVB\Templates”.

7.       Run set up for the application.

                     i.            Open a Visual Studio 2005 Command Prompt if one is not already open.

                   ii.            Enter the command “vsta /hostId ShapeAppVB /setup”. The folder in the VSTAHost hive will exactly match the hostID name typed with this command if it is valid.  If the name is typed “shapeappvb” the folder will be “shapeappvb”, if the name is typed “ShapeAppVB” the folder will be “ShapeAppVB”.  If you mistype this command, for example typing “ShapeAppVB_X”, no folder will be created or error generated. 

                  iii.            Because there is no feedback from this command, check that the VSTAHost registry hive now contains a ShapeAppVB folder.

·          In the Registry Editor press F5 to refresh the view.

·         Expand the node HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSTAHost. 

·         Check that the folder ShapeAppVB now exists here.

                 iv.            Close the Registry Editor.

Create Project Templates

VI)        Add the Proxy dll to the Global Assembly Cache.

1.       Open a Visual Studio 2005 Command Prompt (if you do not still have one open).

2.       Use the gacutil tool to add the ShapeAppVBProxy dll to the GAC.

3.       A message “Assembly successfully added to the cache” should now appear.  If this message does not appear, the dll was not added to the GAC.

VII)      Use ProjectGen to create the templates.

1.       Open ProjectGen.

                     i.            Open a Visual Studio 2005 Command Prompt if one is not already open.

                   ii.            Change directories to the ProjectGen folder.

                  iii.            Execute the command “ProjectGen.exe”.

                 iv.            This should bring up the Project Template Wizard.

2.       Specify Template Properties.  Project Template Wizard screen 1.

                     i.            In the Template name box enter “ShapeAppVB Add-in”.  This is the name of the add-in that will appear in the Templates pane of the New Project dialog box.

                   ii.            In the Template description box enter “A project for creating add-ins for ShapeAppVB”.  This is the description that will appear above the name in the New Project dialog box.

                  iii.            In the Default project name box enter “ShapeAppVB_AddIn”.  This is the default project name that appears in the New Project dialog box.

                 iv.            Leave the Template icon blank, use defaults for this example.  Use this to specify an icon for the template.

                   v.            In the Host identifier box select ShapeAppVB.  This list is automatically populated with HostID’s of the host applications that have been registered in step V.

                 vi.            Select Next to move to the next screen.

3.       Specify Host Item.   Project Template Wizard screen 2.

                     i.            In the Proxy assembly name box browse to the ShapeAppVBProxy.dll stored in C:\ShapeAppSamples\ShapeAppVB\ShapeAppVB\bein\Debug.

(This step can be a stumbling block if the ShapeAppVBProxy.dll was not added to the GAC or if it was not generated correctly.  If it was not generated correctly, remove the reference from the GAC and re-do the steps III and IV in the Create the Proxy section as well as step VI in the Create Project Templates section.  Follow the instructions carefully and the re-created proxy file should work.)

                   ii.            In the Base type box select ShapeAppVB.Application.  This drop down is automatically populated with the classes identified as add in entry points in the proxy assembly.

                  iii.            In the Host item name box type “ThisApplication”.  This is the name of the host item which determines the name of the code file (ex:  ThisApplicaiton.vb or ThisApplication.cs).

                 iv.            Leave the rest of this page blank.  The other boxes specify icons, but we will use the defaults.

                   v.            Select Next to move to the next screen.

4.       Specify Project Properties.  Project Template Wizard screen 3.

                     i.            In the Debug exe box navigate to C:\ShapeAppSamples\ShapeAppVB\ShapeAppVB\bin\Debug\ShapeAppVB.exe  then select Open.  This specifies which application to run when the user presses F5 to start debugging the application.

                   ii.            Leave the other boxes blank.  The Debug command line is used to identify replacement variables; the In-process host box is used to identify in-process hosts which are not used in this example.

                  iii.            Select Next to move to the last screen.

5.       Generate Project Template.  Project Template Wizard screen 4.

                     i.            Ensure that the Create project template option is checked.

                   ii.            In the Create project template box navigate to C:\ShapeAppSamples\ShapeAppVB\Templates.  This will cause subfolders to be added to the Templates folder.  These folders are set up in the following manner:  <Language>\<HostID>\<LocaleID> with the templates placed in the <LocaleID> folder as zip files.

                  iii.            Select the option to Register template with host application.  This causes the templates to appear in the VSTA IDE.

                 iv.            Ensure the Save project template descriptor file is selected.

In the Save project template descriptor file type “C:\ShapeAppSamples\ShapeAppVB\ProjectDescriptor.xml”.  This saves an xml description of the project that can be used to base other templates on.  To create more templates with this file, the file may be inputted in the Project Template Wizard or used from the command line. 

                   v.            Select Finish.  A pop up indicating that the templates are being registered with Visual Studio should appear.

                 vi.            Once the Registering Project Templates pop-up indicates that the template registration was successful select OK.

                vii.            The Project Template Wizard should now disappear, returning focus to the command prompt.

6.       Test the Project Templates.

                     i.            Open a Visual Studio 2005 Command Prompt if one is not already open.

                   ii.            Run the ShapeAppVB application by running the command “vsta /hostid ShapeAppVB”.

                  iii.            It may take a few moments to configure the environment.

                 iv.            The VSTA IDE should now open.  A message stating that the setting file cannot be found and the most recent setting will be used.  This message is not important for this walkthrough- click OK to continue.

                   v.            On the File menu select New Project.

                 vi.            The template just created above should be visible in the Templates pane.  The template name, default project name, and description were all specified on the first page of the Project Template Wizard.

                vii.            Ensure that Visual C# is the selected language under the Project types pane, select the template icon from the Template pane, and then select OK to open a new template project in the VSTA IDE.

              viii.            Select the file ThisApplication.cs from the Project Explorer.

                 ix.            The file name and partial class name were specified on the second page of the Project Template Wizard.

Note- If you selected a CSharp project, you will have a partial class with three methods, ThisApplicaiton_Startup, ThisApplicaiton_Shutdown, and InternalStartup.  The InternalStartup adds event handling so that ThisApplication_Startup is called when the application starts and ThisApplication_Shutdown is called when the application shutsdown.  If you selected a Visual Basic project, the file ThisApplication will have a partial class with two methods, ThisApplication_StartUp which is called when the application is started and ThisApplication_Shutdown which is called when the application is shut down. 

7.       Create 2 Add-in’s.

                     i.            Open a new Visual C# project template (if one is not already open).

·         Select File, New Project.

·         Select Visual C# from the Project types pane.

·         Select the ShapeAppVB Add-in icon from the Templates pane.

·         Select OK.

                   ii.            Add a reference to System.Windows.Forms (this step is specific to this application).

·         In the Project Explorer right click on the ShapeAppVB_AddIn1 project and select Add Reference.

·         On the .NET tab select System.Windows.Forms.

·         Select OK to add the reference.

Once this reference is added, ShapeAppVB may be run by pressing F5 from the VSTA IDE; however, the add-ins will not load yet.  This is because the host application has not yet been modified to load add-ins.

                  iii.            In the Project Explorer window, double click on ThisApplication.cs to show the code file.

                 iv.            In the ThisApplication_StartUp method, add code to show a message box with the prompt “Add-In 1 Loaded”.

                   v.            Save this file.

·         Under File select Save All.

·         The Save Project window should now appear.

·         Select Save to use the defaults.

                 vi.            Open a new Visual Basic project based off the same template.

·         Select File, New Project.

·         Select Visual Basic from the Project types pane.

·         Select the ShapeAppVB Add-in icon from the Templates pane.

·         Select OK.

                vii.            Several errors will appear but can be ignored.  These errors will be corrected by adding a reference to System.Windows.Forms.

              viii.            Add a reference to System.Windows.Forms.

·         In the Project Explorer right click on the ShapeAppVB_AddIn1 project and select Add Reference.

·         On the .NET tab select System.Windows.Forms.

·         Select OK to add the reference.

Once this reference is added, ShapeAppVB may be run by pressing F5 from the VSTA IDE; however, the add-ins will not load yet.  This is because the host application has not yet been modified to load add-ins.

                 ix.            In the Project Explorer window, double click on ThisApplication.vb to show the code file.

                   x.            In the partial class, ThisApplicaiton, add a subroutine called NewDrawingMessage accepting a sender object and ShapeAppVB.CreatedDrawingEventArgs.  These inputs will cause the method to match the signature of the delegate CreatedDrawingEventHandler in the Events.vb file of ShapeAppVB.

                 xi.            In the NewDrawingMessage method, add code to show a message box with the prompt “New Drawing Created”.

                xii.            In the ThisApplication_StartUp method, add code to add an event handler to the drawing created event, create a new drawing, and add a shape to it.

              xiii.            Ignore the warning that ‘ThisApplicaiton’ is not CLS-compliant.

              xiv.            Save this file.

·         Under File select Save All.

·         The Save Project window should now appear.

·         Select Save to use the defaults.

               xv.            Close the Visual Studio 2005 Tools for Applications window.

8.       Modify the Add-Ins to be loaded by the host application.

                     i.            Find the file InstallAddIn.js that was included in the ShapeAppVB_Samples.zip file.

                   ii.            Copy this file and paste it into the folders created for the add-ins.  These folders should be in “%MyDocuments%\ShapeAppVB\Projects\ShapeAppVB_AddIn#\ShapeAppVB_AddIn#”.

                  iii.            Add the post build event to the CSharp Add-In (should be named ShapeAppVB_AddIn1).

·         Open the project in Visual Studio 2005 or Visual Studio 2005 Tools for Applications.  The project solution should be located in %MyDocuments%\ShapeAppVB\Projects\ShapeAppVB_AddIn1.

·         Bring up the Properties page (right click on the project from the Solution Explorer and select Properties).

·         Select the Build Events tab.

·         In the Post-build event command line enter:

cscript "$(ProjectDir)InstallAddIn.js" "$(TargetPath)" "ShapeAppVB\AppAddins\$(TargetName)"

·         The Run the post-build event drop down should be on “On successful build”.

·         Build the project by pressing Ctrl + Shift + B.

If you receive an error message stating that the script exited with code 1 check that you have copied the file into the correct folder:  “%MyDocuments%\ShapeAppVB\Projects\ShapeAppVB_AddIn#\ShapeAppVB_AddIn#”.  Adding the file should resolve this error.

If you receive an error message stating that the script exited with code 3 check that the post-build event is all on one line and was entered exactly as it appears above

·         There should now be a folder for this add-in in %MyDocuments%\ShapeAppVB\AppAddins for this project.  Within this folder there should be a copy of the dll for this project.

·         Save and close the file.

                 iv.            Add the post build events to the Visual Basic Add-In (should be named ShapeAppVB_AddIn2).

·         Open the project in Visual Studio 2005 NOT Visual Studio 2005 Tools for Applications.  The project solution should be located in %MyDocuments%\ShapeAppVB\Projects\ShapeAppVB_AddIn2.

·         Bring up the Properties page (right click on the project from the Solution Explorer and select Properties).

·         Select the Compile tab.

·         Select the “Build Events…”button.  This button NOT included in Visual Studio 2005 Tools for Applications- this is why this step must be performed from Visual Studio 2005.

·         The Build Events window should now appear.

·         In the Post-build event command line enter:

cscript "$(ProjectDir)InstallAddIn.js" "$(TargetPath)" "ShapeAppVB\AppAddins\$(TargetName)"

·         The Run the post-build event drop down should be on “On successful build”.

·         Select OK.

·         Build the project by pressing Ctrl + Shift + B.

*If you receive an error message stating that the script exited with code 1 check that you have copied the file into the correct folder:  “%MyDocuments%\ShapeAppVB\Projects\ShapeAppVB_AddIn#\ShapeAppVB_AddIn#”.  Adding the file should resolve this error.

If you receive an error message stating that the script exited with code 3 check that the post-build event is all on one line and was entered exactly as it appears above

·         There should now be a folder for this add-in in %MyDocuments%\ShapeAppVB\AppAddins\ for this project.  Within this folder there should be a copy of the dll for this project.

·         Save and close the file.

Create the TypeInfrastructureManager

11.   Add (or replace) a function GetHostObject as an IRemoteObjectContract that implements IHostItemProviderContract.GetHostItem and accepts the strings objectType and cookie as input.  This function should return a RemoteObjectAdapter, called adapter, which is set to a new RemoteObjectAdapter that takes in the type of ShapeAppVB.Applicaiton, the class variable application_value, and the type TypeInfrastructureManager, if the parameter objectType matches the full name of the ShapeAppVB.Application.  If the parameter objectType doesn’t match the full name of the ShapeAppVB.Application an ArugumentOutOfRangeException should be thrown.

12.    Add or finish the three methods that may have been auto generated in step IX.7.  These methods are required implementations of several abstract ContractAdapterBase methods and are not important for this walkthrough. 

                     i.            The RemoteToString function should return Me.ToString.

                   ii.            The GetRemoteHashCode function should return Me.GetHashCode.

                  iii.            The RemoteEquals function should return false if the input parameter (of type System.AddIn.Contract.IContract) contract is null and by default.  If it is false that the contract passed in is out of the app domain, then results of the contract as a HostItemProivder equaling Me should be returned.

XII)   Add code to load add-ins using the add-in management API

1.       Add the Extension.vb file to the Integration folder.

                     i.            In the Solution Explorer for the ShapeAppVB solution in Visual Studio 2005, right click on the Integration folder under the ShapeAppVB project.

                   ii.            Select Add then Class.

                  iii.            In the Add New Item – ShapeAppVB window select Code File from the Templates pane.

                 iv.            Name the file Extension.vb.

                   v.            Select Add to add the file to the project.

2.       Add the following import statements to the blank Extension.vb file:

Imports System

Imports Microsoft.VisualStudio.Tools.Applications.Contract

3.       Declare the class as public with the name Extension. 

4.       Add the following private fields to the class. 

                     i.            application_value- An instance of the Application type defined in ShapeAppVB.

                   ii.            addInContext- A context, which is a collection of add-ins, that can access the portion of the ShapeAppVB object model that is exposed through the Application type.

                  iii.            addInCollection- A subcollection of add-ins contained in the addInContext field.

                 iv.            itemProvider-  An instance of the HostItemProvider for ShapeAppVB.

                   v.            addInPath- A string that specifies the folder in which ShapeAppVB looks for add-ins to load.

                 vi.            tim_value- A TypeInfrastructureManager that will contain type maps for the object model of ShapeAppVB.

5.       Add a constructer with friend scope that will call the method InitializeTypeInfrastructureManager which has not been implemented yet. 

6.       Add a friend readonly property called TypeInfrastructureManager that returns the tim_value.

7.       Add a friend method called Connect that takes an Application, app_in,  as input.  This method will be called when the ShapeAppVB application starts.  It will perform the following tasks: 

                     i.            Initialize the application_value to the application passed in.

                   ii.            Initialize the itemProvider to a New HostItemProvider passing in the application_value and the property TypeInfrastructureManager.

                  iii.            Initialize the addInPath to %MyDocuments%\ShapeAppVB\AppAddIns.

                 iv.            Call the method to load add-ins.

8.       Add a public method called LoadAddIns to find and load add-ins by searching through the addInPath specified in the Connect method for dll files with the same name as their parent folder.      

9.       Create a private method called InitalizeTIM.  In this method, create a 1D string array in which the full path and name of the TypeInfrastructureManager.dll is stored in the 0 position, and the method within TypeInfrastructureManager, CreateTypeInfrastructureManager, is stored in the 1 position.  Pass this string array to the method CreateTIM which will be added next. 

10.   Create a private method called CreateTIM.  This method should take in the string array created in InitalizeTIM and attempt to load the assembly.  Once the assembly is loaded, the method should attempt to invoke the CreateTypeInfrastructureManager method from each type from the exported types to get a TypeInfrastructureManager to return.  If the method CreateTypeInfrastructureManager cannot be invoked to get a TypeInfrastructureManager, then return nothing. 

11.    Update the Main method in the Program.vb file to create an instance of the Extension class and connect to it. 

Test the Updated Host Application

I)          Build the updated host application by pressing Ctrl + Shift + B and ensure there are no build errors.

II)      Press F5 to run the updated application.

1.       A message box indicating that the 1st add-in was loaded should appear.  Select OK.

2.       A message box indicating that a New Drawing was Created should appear.  Select OK.

3.       The ShapeAppVB application should appear with a drawing containing a circle.

4.       Create another new drawing by selecting New from the File menu in the ShapeAppVB application.

5.       A message box indicating that a new drawing was created should appear.  This message will appear every time a new drawing is created.

6.       Close the application.