Melody's VSTA Blog

VSTA Documentation on MSDN

2008-10-10T14:53:00Z

The MSDN site now includes documentation for VSTA v 2.0. The documentation available through the MSDN site is an updated version of the documentation included with the SDK. Updates in the on-line documentation include sections on how to properly expose structs and tips on debugging. This site also provides a Community Content section where users can post helpful tips and workarounds.

Click here to go to VSTA 2.0 on MSDN

Updated EventSample with EntryPoint Generic Event Handling

2008-10-08T19:52:00Z

There is a new sample up demonstrating generic event handling in entry point classes. Click here to download EventSample VB v2.1 – Exposing Generic Events in Entry Point Classes

Excerpt from EventSample VB v2.1 EventHandlerT in EntryPoint Classes.doc:

At this time there is no direct way to expose an EventHandler<T> in the host to VSTA add-ins. This sample uses a workaround which involves using non-generic event handling between the host and proxy, and generic event handling between the proxy and add-in. This is accomplished by raising the non-generic events in the host and adding methods to the proxy to translate the events and event args. The host and proxy must be modified; however, the host item provider and host type map provider do not require any alterations.

This workaround only works for generic events raised by the entry point class the add-in is based on. There is a separate workaround for generic events raised by other classes which is more involved.

This sample is a modified version of the Event Sample VB v 2. To run this sample, extract the zip file and run the included setup file SetupEventSample VB v 2.1.js. Build the solution to move the proxy to the GAC and build the included sample add-in to load the assembly. Both events hooked into the by the add-in will be triggered by entering a message into the input box and selecting “Add”.

The proxy and add-ins use tight versioning, the proxy assembly is marked as version 2.1 and the project templates included use this assembly as version specific. To use the included AutoProxyGen Input.xml file to regenerate the main proxy file, update the file locations (the proxy included will work so this is not necessary). Only one modification was done to the auto-generated proxy file, in the entry point class and it’s base the non-generic events were changed from public to private so that only the generic events are visible to add-ins.

Workaround Components:

Host

1) Define custom event args.

2) Define an EventHandler<T> in the EntryPoint class using the custom event args (must be the entry point the add-in will be based on).

3) Define a delegate using the custom event args. This will be used to communicate between the host and proxy.

4) Define an event based on the delegate defined in 3 above. This will be used to communicate between the host and proxy.

5) Anytime the EventHandler<T> is raised, raise the event based on the delegate, this event will trigger the EventHandler<T> in the proxy/add-in.

Proxy

6) Create the proxy as normal. This will define in the proxy:

a. The custom event args from 1.

b. The delegate using the custom event args from 3.

c. The event based on the delegate from 4 in both the class and the entry point class.

This will skip:

a. The EventHandler<T> (all generics are skipped).

ProxyGen.exe Warning: 21040 : The following event type MainApplication contains generic type information and will not be parsed: cEventHandlerT.

7) Re-implement the custom EventArgs in the proxy while keeping the auto-generated custom EventArgs. Do this by using a different name for the re-implemented custom event args, or nesting them in a class.

8) Expand the partially defined entry point class in the proxy (suggest to do this is a separate code file) adding:

a. A private event EventHandler<T> for the custom event args for internal use by the proxy. Do not define the add and remove methods for this event.

b. A flag for the private event defined above initialized to false.

c. The EventHandler<T> defined in the host skipped by ProxyGen using the re-implemented event args deined in 7 above. Define the add and remove methods for this event. In the Add method, hook the value passed in to the private event defined in 8a above. Then, if the flag defined in 8b is false, hook the auto-generated generic event handler defined in the main proxy file to a new method to be defined in the expanded entry point class (defined below) and set the flag to true. In the remove method, remove the value from the private event defined in 8a above.

d. Add a method which satisfies the signature for the generic event handling, using the original event args. In this method, translate the original event args to the re-implemented event args. Use the re-implemented event args to raise the private event defined in 3a.

9) Expand the partially defined class in the proxy adding the EventHandler<T> (suggest to do this in the same separate code file).

Tools to Automate VSTA 2 Integrations: AutoProxyGen and Templates

2008-10-01T19:48:00Z

We have new downloads up including templates and a new tool AutoProxyGen which automates ProxyGen and can be used in build events.

AutoProxyGen:
This tool automates the process of using ProxyGen and can be used as a build event. AutoProxyGen includes workarounds for ProxyGen bugs including automatically excluding structs and ensuring that items which are not marked as excluded are not excluded. AutoProxyGen includes a basic VSTA integration which can be used for further customizations, such as examining the host for custom attributes to specify entry points and excluded items and correcting the inheritance error which prevents COM hosts from exposing events.

A sample add-in demonstrating how to correct the inheritance error for COM hosts is included, other add-ins are available upon request.

Video: From ProxyGen to AutoProxyGen

Templates:
Templates to help automate VSTA v 2.0 integrations are now available. Run the included setup file to move the templates to the Visual Studio 2008 template caches (may need to restart Visual Studio for templates to work).

Proxy Project- includes all files and post build event necessary to place the proxy assembly in the GAC and rebuild the VSTA pipeline. C# only. (may want to create a new or use existing key.snk file)
Host Item Provider- Use Find&Replace to replace "YourEntryPointType" with the type of the host entry point. Includes necessary references. Item template. VB & C#
VstaRunTimeIntegration- Update the variables in the "Variables to update" section including the host entry point type, start-up class for add-ins, and the folder in %MyDocuments% to find add-ins in. Includes necessary references. Item Template. VB & C#

New EventSample for VSTA v 2 (VB.Net)

2008-09-02T17:43:00Z

Click here to download EventSample VB v 2.0 for VSTA v 2

Overview:

This sample is intended to expose several common tasks in VSTA, including: declaring an object, using and manipulating a form, and handling form events and event args. This sample contains a very simple object, form, application with a basic VSTA integration, and an add-in. An EventHelper is used to prevent any errors in add-in event handling.

To run the sample, extract the files, open and build the EventSample solution, then run the setup file included (double click or use the command “cscript SetupEventSample.js” from a command prompt). Next, open and build the add-in solution included in the Samples folder. Run the EventSample application, which should now automatically find and load the sample add-in included.

The EventSample application records button clicks and input from a text box in a list box. The sample add-in responds to mouse clicks on any of the buttons on the form, to adding input through the add button, clearing the display, and selecting the Open button. Event handling for the Save and Close buttons in the add-in is not implemented.

Included in this sample:

Item	Description
MainForm	Main user form and empty code class.
Program	Starting point in the host application.
MainApplication	Main application class. All application specific code is here.
MainObject	Main object used by the MainApplication class. Consists of a string.
EventArgs	Contains class definitions for custom event used by the MainApplication.
EventHelper	Class taken from ShapeApp samples to manage events from the host application and add-ins.
VstaRunTimeIntegration	Class based on the ShapeApp samples which uses the VSTA pipeline to load and manage add-ins.
HostItemProvider	Class based on the ShapeApp samples which allows add-ins to access the host object model.
HostTypeMapProvider	HTMP file generated by ProxyGen and translated into Visual Basic. Maps the types to canocial names for translation between the host and add-ins.
EventSampleProxy	Proxy file generated by ProxyGen and updated to allow generic event handling.
EventSampleProject1	A sample add-in that interacts with the events of the host application.

How to Update a Host’s Folder in %My Documents%

2008-08-25T16:33:00Z

VSTA hosts use a host specific folder under %My Documents% (or %Documents for Vista) for various purposes. This is where the settings file is stored and is the default save location is for new VSTA projects for the host (unless a different location is specified under the registry entry NewProjectLocation).

Most configuration settings can be updated by deleting the host context hive under the local machine hive (see Note 1 registry location), then running vsta setup for the host. Unlike other registry settings, to update which folder is used in %My Documents% the host context hive under the local user hive (see Note 2 for registry location) must be deleted prior to running vsta setup for the host, and will be populated the next time VSTA is run for the host. This context hive must be deleted if specifying the folder under %My Documents% with either the AppName or UserFilesFolderName registry entries.

The folder under %My Documents% which will be used is determined by the UserFilesFolderName, which specifies which folder under %My Documents% will be used (see Note 3 for examples). If no UserFilesFolderName is specified the AppName is used, which specifies the title to appear in the VSTA IDE title bar. If no AppName is specified, the hostId is used.

This host specific folder under %My Documents% will also be the default save location for new projects unless a different location is specified with the NewProjectLocation entry, which specifies the absolute location of the folder which will be used (not under %My Documents%, see Note 4 for examples).

Note 1- The context registry hive under the local machine registry hive is located at: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSTAHost\<HostId>\9.0

Note 2- The context registry hive under the local user registry hive is located at: HKEY_CURRENT_USER\Software\Microsoft\VSTAHost\<HostId>\9.0

Note 3- The UserFilesFolderName entry specifies which folder under %My Documents% the host will use, not an absolute path.
                Example good: “ShapeAppDocuments”
                Example bad: “C:\ShapeAppDocuments”

Note 4- the NewProjectLocation entry specifies an absolute folder which will be the default save location for new VSTA projects for the host.
                Example good: “C:\ShapeAppDocuments”
                Example bad: “ShapeAppDocuments”

For more information on host registry settings, please refer to MSDN which now features VSTA v 2.0. Click here to go to the Registering a Host Application section.

This applies to VSTA 2005 (v1) and 2008 (v2), the registry hives used above are for VSTA v 2.

Proxy Versioning Options for Project Templates

2008-08-15T16:35:00Z

A common question is how to use versioning for the proxy assembly in add-ins. There are basically three different options. (Download Sample)

1) No Versioning:

Only the name of the assembly is used in the project template and the first assembly in the GAC matching this name will be used. This is how ProjectGen references the proxy in the project template file.

Pros: Will load any proxy present.
Cons: No control over which version of the proxy is loaded. When the intended version is present, but not first in the GAC, it will not load and the project may not build.

2) Tight Versioning:

The name and version of the proxy assembly is used in the project template with the option specific version set to true.

Pros: Correct version will always load if present.
Cons: If correct version is not present, but a compatible version is, the project will not load the compatible version and build.

3) Loose Versioning:

A name and version of the proxy assembly is used in the project template with the option specific version set to false or not set.

Pros: Correct version will load if present. If correct version is not present the first assembly with a matching name in the GAC will load.
Cons: No control over which version is loaded if the correct version is not present.

Here’s some examples which illustrate the differences in versioning.

Assumption- three proxies are in the GAC corresponding to three different versions of the same host:

ShapeAppCSharp Version 1.0.0.0 from VSTA v 1 SDK sample. Using Host v 1.0.0.0.
ShapeAppCSharp Version 2.0.0.0 from VSTA v 2 SDK sample with version of proxy assembly changed to 2.0.0.0. Using Host v 2.0.0.0.
ShapeAppCSharp Version 2.1.0.0 from VSTA v 2 SDK sample with a method added to the Application class (Application.DrawingHasShapes) and the version of the proxy assembly changed to 2.1.0.0. Using Host v 2.1.0.0. The proxy v 2.1.0.0 is compatible v 2.0.0.0 projects.

Test 1: Open a VSTA v 2 project for Host v 2.1.0.0 using the method added (Application.DrawingHasShapes) with the above assemblies in the GAC.

No Versioning- Fail. Project will load the ShapeAppCSharp Version 1.0.0.0 project and not build because this assembly is for the v 1.0.0.0 host which uses VSTA v 1.

Tight Versioning- Pass. Project will load the correct proxy.

Loose Versioning- Pass. Project will load the correct proxy. *Note: if the host which loads this add-in is v 2.0.0.0 the add-in will fail during execution because the method added to v 2.1.0.0 is not present in the host.

Test 2: Open a VSTA v 2 project for Host v 2.0.0.0 with only the v 2.1.0.0 assemblies in the GAC.

No Versioning- Pass. Only proxy present will load and the project will build because the v 2.1.0.0 proxy is compatible with v 2.0.0.0 projects. *Note: if the v1 proxy was still in the GAC this may fail.

Tight Versioning- Fail. The specific version of the proxy is not present, so no proxy assembly will be loaded. *Note by setting the Specific Reference attribute to false in the properties window (in the Project Explorer) the project will change to Loose Versioning and pass.

Loose Versioning- Pass. The compatible v 2.0.0.0 will load. *Note: if the v1 proxy was still in the GAC this may fail.

We offer a sample which shows how to implement Tight Versioning- click here.

Updating Project References Programmatically

2008-08-13T19:10:00Z

A host, or helper application, can programmatically update a reference in a project. One instance where this is useful is when you want to ensure that a specific version of a proxy reference is used.

Below is an updated version of the OpenMacroProject from the ShapeAppMacroRecordingCSharp sample which updates the reference in the project to use second version of the ShapeAppCSharpProxy. The proj file is updated prior to loading to avoid any messages indicating that the project file has been updated and needs to be reloaded.

private void OpenMacroProject()
{
    // See if the project is already loaded.
    foreach (EnvDTE.Project currProject in this.dte.Solution.Projects)
    {
        string projPath = currProject.FileName;
        if (String.Compare(projPath,
                           VstaDesignTimeIntegration.MacroProjectFilePath,
                           StringComparison.OrdinalIgnoreCase) == 0)
        {

            this.macroProject = currProject;

            // Set the post build-event to install the Macro AddIn assembly into the
            // user's Documents folder i.e. "...\Documents\ShapeAppCSharp\MacroAddIns"
            this.macroProject.Properties.Item("PostBuildEvent").Value =
                "cscript \"$(ProjectDir)InstallAddIn.js\" \"$(TargetPath)\" \"ShapeAppCSharp\\MacroAddIns\"";

            RegisterAsDebugHost();
            return;
        }
    }

    //SUMMIT- update the reference
    {
        //namespace for the project file
        XNamespace ns = "http://schemas.microsoft.com/developer/msbuild/2003";

        //load the proj file
        XDocument projDoc = XDocument.Load(VstaDesignTimeIntegration.MacroProjectFilePath);

        //get the node with the reference to update
        var oldRef = (from refs in projDoc.DescendantNodes()
                 where refs.ToString().StartsWith("<Reference") &&
                 refs.ToString().Contains("ShapeAppCSharpProxy")
                 select refs).First();

        //create the new version specific reference
        XElement updRef = new XElement(ns + "Reference",
            new XAttribute("Include", "ShapeAppCSharpProxy, Version=2.0.0.0"),
            new XElement(ns + "SpecificVersion", "true"));

        //update the node
        oldRef code.ReplaceWith(updRef);

        //save the document
        projDoc.Save(VstaDesignTimeIntegration.MacroProjectFilePath);
    }

    // Load the project as it is not currently loaded
    this.macroProject = this.dte.Solution.AddFromFile(
        VstaDesignTimeIntegration.MacroProjectFilePath, true);
    RegisterAsDebugHost();
}

To use this code to correct the side by side evaluation issue (both versions of the ShapeAppCSharp samples use the ShapeAppCSharpProxy) be sure to version the proxy assembly and add the above code.

Bit Lock During Out of Process Debugging Workaround

2008-08-04T14:13:00Z

During out of process debugging occasionally the pdb file becomes locked and prevents builds from finishing successfully. The VstaDesignTimeIntegration.DeleteMacroPdb method, called in OnBuildBegin, is suppose to ensure that this does not happen by cycling until the bits are no longer locked, then deleting them. Unfortunately this does not always work and the project can get stuck in an unbuildable state. Keyvan Nayyeri posted a workaround to a similar issue in add-in programming (the dll file becoming locked) which can be applied to this. He suggests using a pre-build event to move/rename the locked files thus clearing the way for the updated bits to be built.

Keyvan’s workaround:
You can add following lines of code to the pre-build event command line of your project.

if exist "$(TargetPath).locked" del "$(TargetPath).locked"
if exist "$(TargetPath)" if not exist "$(TargetPath).locked" move "$(TargetPath)" "$(TargetPath).locked"

Ways to apply workaround:

Use the above pre-build event modified to move the pdb file instead of the dll.*
Use a modified version of the InstallAddIn.js file used in the post build event in the pre-build event to move the pdb bits.*
In the DeletePdb method move the locked file in the catch block (see code below).

* Keep in mind that like the post build event, the pre build event can be added programmatically.

By using this workaround, the build will no longer fail if the pdb bits become locked. However, if the bits do become locked, debugging will fail.

Related blog: ShapeAppMacroRecordingCSharp- common problems and workarounds
One issue with the DeletePdb bit method is that it catches only the IOException, not the UnauthorizedAccessException which is also thrown.

Code for #3 In the DeletePdb method move the locked file in the catch instead of cycling

private static void DeleteMacroPdb()

{

string projectPath = Path.GetDirectoryName(VstaDesignTimeIntegration.MacroProjectFilePath);

string[] pdbFiles = Directory.GetFiles(projectPath, "*.pdb", SearchOption.AllDirectories);

// Delete all PDB files for the project under \obj\.. and \bin\.. folders.

// If a file is locked, retry to delete that file after 100 milliseconds.

foreach (string pdbFile in pdbFiles)

{

bool done = false;

int retry = 0;

// Retry a maximum of 5 seconds to delete the file.

while (!done && retry <= 50)

{

try

{

File.Delete(pdbFile);

done = true;

}

catch (IOException ex)

{

File.Delete(pdbFile+"old");

File.Move(pdbFile, pdbFile + "old");

Thread.Sleep(100);

retry++;

}

catch (Exception ex)

{

File.Delete(pdbFile + "old");

File.Move(pdbFile, pdbFile + "old");

Thread.Sleep(100);

retry++;

}

Using VSTA to Create Office Documents Through XML

2008-06-17T17:06:00Z

With the introduction of LINQ to XML and the OpenXml formatting of Office 2007 documents it is incredibly easy to use VSTA to import and export data from a host application to an Office document and vice versa. One benefit of using OpenXml (or for Excel straight xml as well) is that this can be performed without installing Office or using the office API's, which allows this processing to be done on servers as well as desktops.

A new sample is available showing how to export ShapeApp shape data into Word and Excel using VSTA v 2 and taking advantage of the easy to use LINQ to XML with Visual Basic.

To download the sample add-ins, click here. To go to the download page, click here.

From the Xml Office AddIn Instructions:

Office 2007 introduced a new storage method for Office document. The new documents are actually packages- they are zip files of xml documents. To explore one of these packages, change the extension to .zip and explore it like any other zip file, or download the package explorer tool from CodePlex to explore and edit the package without unzipping or using Office. This new document packaging format makes it very easy to import or export data between a host and an Office document.

Two add-ins for ShapeAppCSharp (VSTA v 2) are available demonstrating how to save ShapeApp data into a Word or Excel document. The SaveToWord add-in uses the Open Xml Format SDK to add data to the main document (document.xml) of the Word package (System.IO.Packaging could be used instead with minor modifications). The SaveToExcel add-in uses straight Xml instead of OpenXml to get data into Excel because it is far easier to work with straight Xml in Excel. Excel can save and open Xml documents without worrying about packaging. Visual Basic was used to write both add-ins because Visual Basic works better than C# with LINQ to XML.

From the ShapeAppCSharp_SaveToWord add-in:

'This method populates the word document with ShapeAppData

Public Sub SetMainDocumentContent(ByVal part As MainDocumentPart)

Const name As String = "Name: "

Const size As String = "Size: "

Const loc As String = "Location: "

Const color As String = "Color: "

'query the shapes in the first drawing using LINQ to XML

Dim docBodyData = From shape In Me.Document.Drawings(0).Shapes _

Select _

<w:body>

<w:p><w:r><w:t><%= name & shape.Name %></w:t></w:r></w:p>

<w:p><w:r><w:tab/></w:r><w:r><w:t>

<%= size & shape.Size.Height.ToString() & ", " & shape.Size.Width.ToString() %>

</w:t></w:r></w:p>

<w:p><w:r><w:tab/></w:r><w:r><w:t>

<%= loc & shape.Location.X.ToString() & ", " & shape.Location.Y.ToString() %>

</w:t></w:r></w:p>

<w:p><w:r><w:tab/></w:r><w:r><w:t>

<%= color & shape.Color.A.ToString() & ", " & shape.Color.R.ToString() & ", " & _

shape.Color.B.ToString() & ", " & shape.Color.G.ToString() %>

</w:t></w:r></w:p>

</w:body>

'to get the xml stuff from word- create a new doc, add dummy data as a place holder

' in the format you want to export it, then copy the xml from the document.xml part

' of the package. Remove the dummy data and insert the LINQ query.

Dim docXml = <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">

<%= docBodyData %>

</w:document>

'save the xml to the main document part of the word package

Dim stream As StreamWriter = New StreamWriter(part.GetStream(FileMode.Create, FileAccess.Write))

docXml.Save(stream)

End Sub

Resources:

· Open Xml Format SDK

· The PackageExplorer tool from CodePlex. Click on the V3.0.0 RC1 link to start the download.

· The MSDN article "How to: Create an Office Open XML Package by Using the Open XML API"

· The MSN video “How Do I Create Excel Spreadsheets using LINQ to XML?”