Melody's VSTA Blog : DynamicProgrammingModel

ShapeAppDynamicProgrammingModelCSharp_ProxyShim Sample

Melody — Tue, 19 Oct 2010 18:15:00 GMT

Summit now offers the he ShapeAppDynamicProgrammingModelCSharp_ProxyShim sample which is based both the VSTA 2.0 SDK sample ShapeAppDyanmicProgrammingModelCSharp and the Microsoft endorsed ShapeAppMacroRecordingCSharp-NoRuntime sample. This sample references the VSTA runtime and uses the auto-generated designer files for the Dynamic Programming Model (DPM) add-ins; however, the VSTA runtime is not used to load the add-ins. Instead a host type, IAddIn, is used along with AssemblyLoad and a customized ProxyShim to load the DPM add-ins. The ProxyShim references the host application directly and contains type definitions only for the entry point types. These definitions have been modified for use with the IAddIn interface. All changes have been marked with a comment “SUMMIT CHANGE” and explanation. To access this sample, please fill out the information form, then e-mail vstasupport@summsoft.com with your username and request.

Use of IAddIn:
As in the NoRuntime sample, the host application in this sample defines the interface IAddIn to use in much the same way that the VSTA Runtime’s IEntryPoint and IMultipleEntryPoint are used in SDK samples, mainly to start and stop the add-in. For NoRuntime and ProxyShim style integrations an additional file is required in the add-ins which implements the IAddIn interface. In this sample, that code file is called “IAddIn_Implementation” and it contains methods to instantiate all host items as well as the host item container, namely the host item container “ThisDocument.xx” and the host items “Drawing#.xx”. In order to keep the DPM add-in in sync with the host this file is regenerated after any host item additions or removals. Hence, because the file is auto-generated and is regenerated during design time, this file should not be modified.

Improvements over the SDK DPM Sample:
The SDK DPM sample ShapeAppDynamicProgrammingModelCSharp allows for host objects within host items (in this case shapes within a drawing) to be referenced through local variables; however, host items within the host item container (in this case drawings within a document) cannot be referenced in the same manner. Since the ProxyShim style integration is not limited by the VSTA runtime it is possible to reference host items through a named variable within the host item container. See code sample below which contains the startup methods for a host item (Drawing1_Startup) and for the host item container (ThisDocument_Startup).

Private Sub Drawing1_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
     'refer to a host object by its variable name
     Me.Circle1.Size = New Size(25, 25)
End Sub

Private Sub ThisDocument_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
    'CANNOT refer to a host item through a variable name
    ' using an SDK style integration,
    'CAN refer to a host item through a variable name with the
    'ProxyShim style integration
    Me.Drawing1.Circle1.Location = New Point(100, 100)
End Sub

private void Drawing1_Startup(object sender, System.EventArgs e)
{
    //refer to a host object by its variable name
    this.Circle1.Size = new Size(50, 75);
}

private void ThisDocument_Startup(object sender, EventArgs e)
{
    //CANNOT refer to a host item through a variable name
    // using an SDK style integration,
    //CAN refer to a host item through a variable name with the
    //ProxyShim style integration
    this.Drawing1.Circle1.Location = new Point(75, 75);
}

Additionally, like the NoRuntime style integration the ProxyShim style integration supports the “new” operator. To use this feature with the ShapeApp samples, add public constructor methods to the desired classes. For the ShapeAppDynamicProgrammingModelCSharp_ProxyShim sample, the Drawing class was modified changing the constructor from private to public. Another code change was required to the VSTADesignTimeIntegration class; the code to build an existing project when opening was moved from the EnsureIDE method to the end of the Connect method to avoid building prior to hooking-up any host items added with the “new” operator in the add-in. The code sample below demonstrates use of this modification and the “new” operator.

Private Sub ThisDocument_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup

    'calculate a valid drawing name
    Dim name As String = "Drawing" & (Me.Drawings.Count + 1).ToString()

    'create a new drawing and add it to the document
    Dim d As New Drawing(Me.Application, name)
    Me.Drawings.Add(d)

End Sub

private void ThisDocument_Startup(object sender, EventArgs e)
{
    //calculate a valid name for the drawing
    string name = "Drawing" + (this.Drawings.Count + 1).ToString();

    //create the new drawing and add it to this document
    Drawing d = new Drawing(this.Application, name);
    this.Drawings.Add(d);
}

Prerequisites:
To build and run the ShapeAppDynamicProgrammingModelCSharp_ProxyShim sample, you must first install the Microsoft VSTA 2.0 SDK, available from Summit Software . You must also have Visual Studio 2008 or higher installed.

Running the Sample:
Follow these instructions to run the sample.

1) Extract the sample to C:\ShapeAppSamples. If a different location is used, then the references to the host in the DPM add-ins and templates must be updated.

2) Run the included setup file SetupShapeAppDynamicProgrammingModelCSharp_PS.js. This will setup the ShapeAppCSharp host and register both the project templates and the item templates which are required for DPM add-ins.

3) Open and build the ShapeAppDynamicProgrammingModelCSharp_PS solution to create the exe which the DPM ProxyShim and add-ins will reference.

4) Run the sample either through Visual Studio or directly from the exe.

5) In the ShapeApp application, save the document and add a C# or VB DPM add-in project through the customization menu.

6) In the VSTA IDE open the IAddIn_Implementation file which contains a partial class for the host item container (ThisDocument) as well as implementation code for the IAddIn interface and setup code for local variables. Each local variable corresponds to a host item (Drawing1, Drawing2, and Drawing3).

7) In the ShapeApp host application delete Drawing1 and add a new Drawing.

8) In the IAddIn_Implementation file note that the code has been regenerated to stay in sync with the host items. Now local variables should be present for Drawing2, Drawing3, and Drawing4.

9) In the ShapeApp host application add a shape Drawing2. The VSTA runtime will automatically add code to the designer file, Drawing2.designer.xx, to declare a variable to correspond to this host object.

10) In the VSTA IDE select the code file for Drawing2 and add code to manipulate the shape. For example:

Private Sub Drawing2_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
     Me.Circle1.Size = New Size(25, 25)
End Sub

private void Drawing2_Startup(object sender, System.EventArgs e)
{
    //refer to a host object by its variable name
    this.Circle1.Size = new Size(25, 25);
}

11) In the code file for the host item container (ThisDocument.xx), add code to manipulate the shape added to Drawing2 through the local variable for Drawing2. Add code to create a new drawing using the “new” operator and add it to the document. For example:

Private Sub ThisDocument_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
    Me.Drawing2.Circle1.Location = New Point(100, 100)

           'calculate a valid drawing name
          Dim name As String = "Drawing" & (Me.Drawings.Count + 1).ToString()

           'create a new drawing and add it to the document
          Dim d As New Drawing(Me.Application, name)
          Me.Drawings.Add(d)

End Sub

private void ThisDocument_Startup(object sender, EventArgs e)
{
    this.Drawing2.Circle1.Location = new Point(75, 75);

    //calculate a valid name for the drawing
    string name = "Drawing" + (this.Drawings.Count + 1).ToString();

    //create the new drawing and add it to this document
    Drawing d = new Drawing(this.Application, name);
    this.Drawings.Add(d);
}

12) Build the add-in project, then save the document through the host application.

13) Close and re-open the document and to launch the code added above.

DPM Code Files for Renamed Host Items

Melody — Tue, 28 Sep 2010 14:34:00 GMT

For Dynamic Programming Model (DPM) style integrations, when a host item is renamed the corresponding code file in the DPM add-in project maintains its original file name and displays the updated host item name in parentheses next to the file name (see screen shot below). This is accomplished by setting the DisplayName property of the IVstaProjectHostItem (projectHostItem.ProgrammingModelHostItem.DisplayName) for the renamed host item. This is demonstrated in the SDK sample ShapeAppDynamicProgrammingModelCSharp where drawings represent host items.

In order to see this simply save a document, add a VB or C# DPM add-in project through the customization menu, then change a drawing name. In the VSTA IDE the code file for the renamed drawing will appear as described above, with the original drawing name as the file name and the updated name in parentheses next to the file name in the Project Explorer pane.

There is a small glitch with the SDK sample. Once a document with a renamed host item (drawing) is customized (by adding a DPM add-in project), saved, and re-opened, a new file is added to the DPM add-in project with a file name matching the updated host item name. This is caused by using the drawing.Name instead of drawing.Cookie in the AddDrawingProjectHostItem method. Below is updated code which solves this problem.

private void AddDrawingProjectHostItem(ShapeApp.Drawing drawing)
{
    //To avoid problems with renamed host items,
    //use the cookie here instead of name
    //IVstaProjectHostItem projectHostItem =
    // AddProjectHostItemInternal( drawing.Name , "drawing",
    // "DrawingEntryPoint");
    IVstaProjectHostItem projectHostItem =
       AddProjectHostItemInternal( drawing.Cookie , "drawing",
      "DrawingEntryPoint");

    //UNCHANGED CODE REMOVED
}

In order to reproduce this problem and see the fix in action follow these steps:

     1) Run the setup file for the SDK DPM sample ShapeAppDynamicProgrammingModelCSharp.
     2) Save a document.
     3) Add a C# or VB add-in project through the customization menu.
     4) Rename a drawing.
     5) Save and close the project.
     6) Re-open the project and launch the VSTA IDE by reselecting the language used for the DPM add-in customization above.
     7) In the VSTA IDE note that there is now a file matching the renamed drawing as well as the original drawing name.

Now implement the above fix and re-run the repro steps. Notice that no new code file is added with the renamed host item's name.

For more information on the Dynamic Programming Model please see the MSDN documentation . For more information on changing the display name of a host item in a DPM add-in see the How to: Change the Display Name of a Host Item section.

DPM Add-in Project Host Item Code File Names

Melody — Thu, 23 Sep 2010 15:00:00 GMT

For DyanmicProgrammingModel (DPM) add-in projects, the file name of the host item code file generally matches the name of the host item. For example: in the SDK sample ShapeAppDynamicProgrammingModelCSharp the host item “Drawing1” would have a corresponding code file named either “Drawing1.cs” or “Drawing1.vb”. However, there is an exception to this rule. If a host item has been removed, then a new one added with the same name as the host item which has been removed, the DPM code file associated with the newly added host item will be named “HostItem#.xx”. For example: in the SDK sample if “Drawing3” was removed the corresponding code file “Drawing3.vb” would be removed from the DPM add-in project. Then, if a new drawing was added it would be named “Drawing3”; however, the corresponding code file would be “Drawing31.vb”.

This is due to a file which lingers once a host item has been removed. Of the three host item code files associated with each host item, namely HostItem.xx, HostItem.Designer.xml, and HostItem.Designer.xx, only the designer files are actually deleted when a host item is removed. The main, or visible, code file HostItem.xx is not deleted when the host item is. This residual file is removed from the DPM project; however, because the file still exists the new host item’s code file name is automatically appended with a number to avoid a naming collision.

Note: It is possible to use any valid name for the code file of a host item; this is specified in the first parameter “name” of the AddProjectHostItem methods.

//From DesgignTimeIntegration.AddProjectHostItemInternal
projectHostItem =
hostAdapter.ProjectHostItems.AddProjectHostItem(
itemName, //<== specify the host item code file name here
"Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp." + itemEntryPoint,
"Microsoft.VisualStudio.Tools.Applications.Runtime.IEntryPoint",
itemName, //cookie name
this.hostItemTemplatesPath + @"\" + languageFolder + @"\" + templateName);

For more information on the DyanmicProgrammingModel and the associated SDK sample please see the MSDN documentation Dynamically Creating and Modifying Host Items and Host Objects in an Add-in Project

Keeping a DPM Add-in Project in Sync with its Associated Document

Melody — Mon, 20 Sep 2010 14:24:00 GMT

When working with a Dynamic Programming Model (DPM) style integration, it is important to keep the DPM add-in project in sync with the associated host document. There are two items which must be kept in sync: the DPM add-in project host item code files and the host's entry point list. There are several times in which these items needs to be updated including when a host item is added, removed, or renamed. In the SDK sample ShapeAppDynamicProgrammingModelCSharp the add-in project code files are updated; however, the list of entry points managed on the host side is not updated until a successful build of the add-in project. This can cause the add-in project to become out of sync with the host document in some scenarios. For example, if a host item is removed and the document is saved and closed without building the associated DPM add-in project, the result is an error when loading the DPM add-in project when the document is re-opened. Below is part a modified version of the VstaDesignTimeIntegration.cs file of the SDK DPM sample which demonstrates how to keep the entry point list in sync with the host document and add-in project.

Note, in the SDK sample ShapeAppDynamicProgrammingModelCSharp a host item is a Drawing and the entry point list is managed through an xml file (DocName.xml) included in the open xml ".msdx" file of a ShapeAppCSharp Document.

private void OnSuccessfulBuildDone()
{
   //UNCHANGED CODE REMOVED
   //moved to UpdateEntryPointList
    //this.document.VstaRunTimeIntegration.EntryPointNameList.Clear();
   //this.document.VstaRunTimeIntegration.EntryPointNameToCookieMap.Clear();
   //// Need to execute the host operation from the main UI thread.
   //AddEntryPointToDocument("ThisDocument");
   //foreach (Drawing drawing in this.document.Drawings)
   //{
   //    AddEntryPointToDocument(drawing.Cookie);
   //}

//ADDED
UpdateEntryPointList();

//UNCHANGED CODE REMOVED
}

//code taken from OnSuccessfulBuildDone
//needs to be run for any host item add/remove
private void UpdateEntryPointList()
{
    //clear the existing list of entry points
    this.document.VstaRunTimeIntegration.EntryPointNameList.Clear();
    this.document.VstaRunTimeIntegration.EntryPointNameToCookieMap.Clear();

    //Add the document then, each host item to the list of entry points
    AddEntryPointToDocument("ThisDocument");
    foreach (Drawing drawing in this.document.Drawings)
    {
        AddEntryPointToDocument(drawing.Cookie);
    }
}

//Entire method included for clarity
void Drawings_DrawingInserted(object sender, EventArgs e)
{
Drawing drawing = (Drawing)sender;
AddDrawingProjectHostItem(drawing);

//ADDED- Update the entry point list
UpdateEntryPointList();
}

//Entire method included for clarity
void Drawings_DrawingRemoved(object sender, DrawingRemovedEventArgs e)
{
     string cookie = e.RemovedDrawingCookie;
     IVstaProjectHostItem item = this.hostAdapter.ProjectHostItems[cookie];
     if (item != null)
         this.hostAdapter.ProjectHostItems.RemoveProjectHostItem(item);

//ADDED- Update the entry point list
UpdateEntryPointList();
}

//Entire method included for clarity
private void AddEntryPointToDocument(string cookie)
{
    IVstaProjectHostItem projectHostItem = this.hostAdapter.ProjectHostItems[cookie];
    if (projectHostItem == null)
    {
        System.Diagnostics.Debug.Assert(false);
        throw new InvalidOperationException("Cannot find the document ProjectHostItem");
    }
    IVstaHostItem programmingModelHostItem = projectHostItem.ProgrammingModelHostItem;

    string entryPointName = projectHostItem.FullyQualifiedNamespace + "." + programmingModelHostItem.Identifier;
    this.document.VstaRunTimeIntegration.EntryPointNameList.Add(entryPointName);
    this.document.VstaRunTimeIntegration.EntryPointNameToCookieMap.Add(entryPointName, cookie);
}

VSTA and Packaging

Melody — Tue, 07 Apr 2009 17:08:00 GMT

A new sample and video are available which demonstrate packaging a VSTA add-in within a document using System.IO.Packaging. Packaging is also used by Office 2007 documents including the "docx", "docm", "xlsx", and "xlsm" file types. In this sample, both the add-in source code and compiled assembly are packaged into the single file document which can be transferred (ex: e-mailed) and opened by another user who through the single file will have access to the document, compiled add-in and source code- similar to an Office document with a VBA macro project included.

This sample is document-centric, so the add-in is intended only for use with the document it is packaged within. Based on the ShapeAppDynamicProgrammingModelCSharp SDK sample, this sample extends the existing packaging file format of the SDK samples to include the VSTA add-in associated with the document. Benefits of packaging document specific VSTA add-ins within documents include ease of deployment and an intuitive end user experience.

Technical stuff:
The main code changes made to the SDK sample ShapeAppDynamicProgrammingModelCSharp for packaging are in methods involved with saving and opening documents in the document.cs file. The add-in project associated with the document is originally created in the same folder as the document. A copy of the project and add-in are packaged into the document while the originals stay in place. This allows the add-in project to be updated outside of the document, and logic was added to use the original project and add-in if available. If the project or add-in is no longer available then the internal copy is used. The internal copy is updated every time the document is saved. This provides a more dev oriented experience, allowing the add-in project to be modified outside of the document, but may not be optimal for non-dev end users. The add-in project source code and assembly are packaged within the document so the only required file is the single document file.

The ShapeAppDynamicProgrammingModelCSharp sample was also updated to include seamless non-destructive debugging; a side effect of this is the add-in projects cannot be run directly because they search for a running instance of the host instead of starting a new one. Therefore, to run a DPM packaged project, open the document through the host instead of debugging from a standalone VSTA IDE.

Note, this is not ClickOnce deployment, for information on ClickOnce deployment please refer to the SDK section Securing and Deploying Add-Ins.

Links:

Summit: Link to Sample

Summit: Link to Video

MSDN: Add-in Debugging

MSDN: DPM Walkthrough

MSDN: System.IO.Packaging

MSDN: Office Packaging