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.
What does this do? This ensures that the application builds without errors and creates the file ShapeAppVB.exe in C:\ShapeAppSamples\ShapeAppVB\ShapeAppVB\bin\Debug for use in ProxyGen.
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.
What does this do? This creates the folder and project that the proxy file will be placed in once it is generated. Signing the assembly with a strong name allows it to be placed in the Global Assembly Cache (GAC), which is necessary for creating project templates. Changing the build path keeps all the dll files in one location for organizational ease.
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.
|
cd "C:\Program Files\Visual Studio 2005 Tools for Applications SDK\2007.02\VisualStudioToolsForApplications\Tools\ProxyGen\x86" |
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.
|
ProxyGen.exe /l:"C:\ShapeAppSamples\ShapeAppVB\ShapeAppVB\bin\Debug\ShapeAppVB.exe" /c:" C:\ShapeAppSamples\ShapeAppVB\ShapeAppVBProxy\Proxy.cs" /o:" C:\ShapeAppSamples\ShapeAppVB\ShapeAppVBProxy\ShapeAppVBOM.xml" /f |
iv. Leave the command prompt open.
What does this do? It uses the library (“/l:”) ShapeAppVB.exe as the bases for the proxy. It creates (“/c:”) the code file Proxy.cs for use later as the proxy and outputs (“/o:”) the descriptor file ShapeAppVBOM.xml. This descriptor file describes the Object Model found in the library. The “/f” forces these files to be overwritten if they already exist.
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.
What does this do? The isAddInEntryPoint attribute is similar to the appobject IDL attribute required by VBA to determine the Application Class. It specifies that the type ShapeAppVB.Application is a host item and identifies it as the entry point into the object model.
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.
|
ProxyGen.exe /c:" C:\ShapeAppSamples\ShapeAppVB\ShapeAppVBProxy\Proxy.cs" /i:" C:\ShapeAppSamples\ShapeAppVB\ShapeAppVBProxy\ShapeAppVBOM.xml" /f |
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.
What does this do? It uses the descriptor file ShapeAppVBOM.xml as input (“/i:”) for the proxy file Proxy.cs to create (“/c:”). The “/f” forces these files to be overwritten if they already exist. In the Proxy file you can see that all the partial classes inherit “global::Microsoft.VisualStudio.Tools.Applications.IProxy”, the entry point also inherits “global::Microsoft.VisualStudio.Tools.Applications.Contract.IEntryPointContract”. If a class is not designated as an entry point with this inheritance and supporting code, the ProjectGen tool will reject the dll stating that it was not correctly generated and will not allow a project template to be generated.
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.
What does this do? This creates the Proxy.dll file that will be use in ProjectGen to create project templates. The references are added so that the auto generated code in the proxy file will compile. The references for System.Drawing and System.Windows.Forms are specific to this project, the others are always needed.
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.
What does this do? This creates registry entries for the ShapeAppVB application. Some of the entries specified in the VSTAHostConfig registry hive are carried over to the VSTAHost hive. The folder ShapeAppVB is created in the VSTAHost hive when the setup command is run from the command prompt.
Create Project Templates
VI) Add the Proxy dll to the Global Assembly Cache.
1. <