Summit Software

.NET 4 and VSTA redistribution

Gary — Fri, 22 Oct 2010 18:19:00 GMT

With the advent of .NET 4 and related questions about VSTA's compatibility, we tested to confirm the following:

Redistribution of VSTA 2.0 (with your application) requires .Net 3.5 SP1 to be installed on the target machine.

Starting with a clean Windows computer and only .NET 4.0 installed, run vsta20.exe to install VSTA 2.0 on the computer... no luck:

Redistribution of VSTA 1.0 (with your application) requires .Net 2.0 to be installed on the target machine.

Starting with a clean Windows computer and only .NET 4.0 installed, run vsta_aide.exe to install VSTA 1.0 on the computer... no luck:

This means that your application installer should continue to follow VSTA SDK deployment guidelines and include the correct version of the .NET framework as a pre-requisite. For instance, here are the prerequisites to deploy VSTA 2.0 with an application:

Prerequisites

The following components must be installed on the target computer before the Visual Studio Tools for Applications installer package is started:

Microsoft .NET Framework 3.5.
MSXML6. You can download the installation package from Microsoft Core XML Services (MSXML) 6.0.

Supporting the “new” Operator in VSTA Add-Ins

Melody — Wed, 20 Oct 2010 15:02:00 GMT

It is possible to support the “new” operator in VSTA add-ins. Integration styles which do not use a full proxy, such as NoRuntime and ProxyShim, can easily support this feature. All that is required is public constructor methods in the host application. In the ShapeAppDyanmicProgrammingModelCSharp sample an additional code change is required in order to ensure all host items created in the add-in using the “new” operator are hooked-up prior to building (for more information on this please see the blog ShapeAppDynamicProgrammingModelCSharp_ProxyShim Sample). This is possible because these styles of integration do not use a full proxy, which generally cannot support the new operator and must instead use factory methods. One exception to this rule is for structs and custom exceptions in VSTA v 2 add-ins. Because structs and custom exceptions are reimplemented in the proxy their public constructors are available for VSTA v 2 add-ins. For more information on the different styles of integration, please see the blog Integration Styles and the Benefits: SDK, NoRuntime, and ProxyShim.

Below are code samples which show how to create a new Drawing object for the ShapeAppCSharp samples in the SDK, NoRuntime, and ProxyShim style integrations:

NoRuntime and ProxyShim:

Both integration styles can use public constructor methods, in this example a public constructor for the Drawing class was added by changing the existing private constructor to public. Note that the factory method may still be used.
//create a new Drawing using a public constructor

Drawing d = new Drawing(this.Application, "Drawing4");

'create a new drawing using a public constructor

Dim d As Drawing = New Drawing(Me.Application, "Drawing4")

SDK Factory Method:

This code utilizes the factory method Application.NewDrawing (this is from the VSTA v 1 samples but applies to VSTA v 2 as well).

//create a new drawing using the factory method

Drawing d = this.NewDrawing();

'create a new drawing using the factory method

Dim d As Drawing = Me.NewDrawing()

SDK Structs and Custom Exceptions (VSTA v 2 only):

Because structs and custom exceptions are reimplemented in the proxy layer, their public constructors are available.

//factory methods, these are static methods in the application class

Color cFM = Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.

Application.CreateColor(System.Drawing.Color.Green.ToArgb());

Point pFM = Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.

Application.CreatePoint(25, 25);

Size sFM = Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.

Application.CreateSize(25, 25);

//public constructos for structs and custom exceptions

Color cPC = new Color(System.Drawing.Color.Green);

Point pPC = new Point(25,25);

Size sPC = new Size(25, 25);

LocationInvalidException liePC= new LocationInvalidException("invalid location");

SizeInvalidException siePC = new SizeInvalidException("invalid size");

'factory methods, these are static methods in the application class

Dim cFM As Color = Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp. _

Application.CreateColor(System.Drawing.Color.Green.ToArgb())

Dim pFM As Point = Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp. _

Application.CreatePoint(25, 25)

Dim sFM As Size = Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp. _

Application.CreateSize(25, 25)

'public constructos for structs and custom exceptions

Dim cPC As Color = New Color(System.Drawing.Color.Green)

Dim pPC As Point = New Point(25, 25)

Dim sPC As Size = New Size(25, 25)

Dim liePC As LocationInvalidException = New LocationInvalidException("invalid location")

Dim siePC As SizeInvalidException = New SizeInvalidException("invalid size")

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.

Integration Styles and the Benefits: SDK, NoRuntime, and ProxyShim

Melody — Thu, 14 Oct 2010 17:38:00 GMT

For VSTA integrations, there are a variety of ways in which the host can load and interact with add-ins. Three styles of interest are SDK, NoRuntime, and ProxyShim. Each style of integration has many pros and cons to consider before deciding on which type is best for a particular host.

SDK style:

This is the style of integration which uses the VSTA runtime and pipeline to load and execute add-ins which reference the host only through a proxy. Add-Ins use an IEntryPoint or IMultipleEntryPoint interface.

Pros: This style of integration offers all of the benefits of the VSTA runtime such as the security and isolation options of loading add-ins into separate app domains, add-in discovery and loading through the VSTA pipeline, as well as trust level options for loading add-ins. The use of a proxy allows the benefits of versioning and use of an Object Model which allows for hiding public items in the host application. Add-ins refer to the host through “this.” or “.me” calls. An EventHelper can be used which prevents exceptions thrown in add-ins from affecting the host application. Dynamic Programming Model add-ins are possible with this style of integration. VSTA v 1 SDK style add-ins can be upgraded to VSTA v 2 SDK style add-ins.

Cons: A full proxy is required for SDK style integrations. Use of a full proxy eliminates support for generics and the new operator. As well, structs and custom exceptions must be redefined in the proxy, and nested classes require manual changes to the proxy. There is a memory usage bug which causes memory not be released once an add-in is unloaded. During debugging, objects on the host side cannot be viewed in windows such as locals and immediate, instead they show up as a transparent proxy with no valid data in the properties. The loading and execution of add-ins is slowed by traversing proxy layer.

NoRuntime:

In a NoRuntime style integration neither the host nor add-ins reference the VSTA runtime. Instead the add-ins reference the host directly and do not use a proxy. Add-ins are loaded through Assembly.Load calls instead of through the VSTA pipeline. Add-ins use the IAddIn interface instead of IEntryPoint or IMultipleEntryPoint.

Pros: This style of integration uses a direct reference to the host application; therefore, generics and the new operator are supported. Structs and custom exceptions do not need to be redefined in a proxy layer. As well, nested types are support with no code changes or effort. During debugging there are no issues with viewing host objects in windows like locals and immediate. Add-ins are loaded and executed quickly because they are not slowed by a proxy layer. The memory usage footprint for unloaded add-ins is less than in SDK style integrations.

Cons: NoRuntime style add-ins require a code file in each add-in to be used in place of the auto-generated designer file (this file can be hidden). The runtime benefits for security, isolation, and versioning are lost. Add-ins must be loaded in the same app domain as the host. It is not possible to hide public items in the host because the add-ins use a direct reference instead of an Object Model defined in a proxy layer. Exceptions thrown in add-ins can affect the host application. Add-ins cannot refer to the host through “this.” or “.me” calls, instead a “this.app” or “me.app” style call must be used with a local variable. It is not possible to use the Dynamic Programming Model with this style of integration. VSTA v 1 SDK style add-ins cannot be upgraded to VSTA v 2 NoRuntime style add-ins; however, they can be upgraded to ProxyShim style add-ins and loaded in the same manner (with the same code) as NoRuntime style integration add-ins.

ProxyShim:

The ProxyShim style integration is a hybrid between the SDK style and NoRuntime style integrations. Both the host and add-ins reference the VSTA runtime, but add-ins are loaded through Assembly.Load calls instead using the VSTA runtime or pipeline. ProxyShim style add-ins use both the IAddIn and IEntryPoint or IMultipleEntryPoint interfaces. These interfaces are defined in an additional code file in the add-in and in a very small proxy which contains definitions only for entry point types.

Pros: Like NoRuntime style add-ins, ProxyShim style add-ins use a direct reference to the host application and can therefore support generics and the new operator. Neither structs nor custom exceptions need to be redefined in a proxy layer. As well, nested types are supported with few to no code changes depending on their involvement with entry point types. During debugging there are no issues with viewing host objects in windows like locals and immediate. Add-ins are loaded and executed quickly because they traverse only a minimal proxy layer. The memory usage footprint for unloaded add-ins is less than in SDK style integrations. Add-ins reference the host through “.this” or “.me” calls. VSTA v 1 SDK style add-ins can be upgraded to VSTA v 2 ProxyShim style add-ins through an upgrade helper. It is possible to support Dynamic Programming Model add-ins with this style of integration and with an improvement over the SDK style DPM (for more information on this please see the blog Referencing Host Items in a DPM Project from the Host Item Container). ProxyShim add-ins can be loaded in the same manner as NoRuntime add-ins; therefore, both types of add-ins can be used by the same host with a single LoadAddIn method.

Cons: Like NoRuntime style add-ins, each add-ins requires a code file to be used in place of the auto-generated designer file. The runtime benefits for security, isolation, and versioning are lost. Add-ins must be loaded in the same app domain as the host. Except for the entry point type, it is not possible to hide public items in the host because the add-ins use a direct reference instead of an Object Model defined in a proxy layer (the proxy used in ProxyShim style integrations defines only entry point types). Exceptions thrown in add-ins can affect the host application.

Is VSTA 2.0 supported under Windows 7 and Visual Studio 2010?

Gary — Thu, 07 Oct 2010 17:01:00 GMT

I’ll preface my answers about support for VSTA in Windows 7 and Visual Studio 2010 with a quick synopsis of VSTA 2.0 platform-related elements.

VSTA 2.0 is based on VS2008 and .NET 3.5 SP1. It supports 32-bit and 64-bit platforms.

· The VSTA integrated development environment creates projects similar to VS2008 that target .NET 3.5 SP1 exclusively.

· The VSTA IDE supports VB and C# languages and compilers for .NET 3.5 SP1 exclusively.

· VSTA’s integrated debugger supports versions of the .NET framework that run on CLR 2 -- .NET 3.5 SP1 or previous framework versions.

· The VSTA runtime is built on System.AddIn, introduced in .NET 3.5. Use of the runtime adds considerable complexity and is not recommended for most use cases.

Windows 7 support: VSTA is fully supported under Windows 7 (both 64 and 32-bit).

Visual Studio 2010 support: VSTA is supported under VS2010 in a limited way, described as follows:

· For the most compatible VSTA/VS2010 scenario, build your application and integrate VSTA 2.0 with VS2010, selecting .NET 3.5 SP1 as the ‘Target framework’. This approach will allow you to use fully utilize VSTA’s design time and runtime capabilities.

· The CLR 4.0 will run .NET assemblies built with earlier versions of the .NET framework, including .NET 3.5 assemblies created by VSTA.

Therefore, if you wish to use VSTA to automate your application built with .NET 4.0 as the target framework:

o You can execute VSTA scripts to automate the application, but these scripts must use an application automation layer assembly built on .NET 3.5 SP1 or earlier. VSTA scripts (add-in assemblies) cannot load assemblies built for the .NET 4.0 platform.

o At design time, VSTA projects (created with VS 2008 or VSTA 2.0) cannot set reference to or load assemblies built for the .NET 4.0 platform. “The referenced component ‘<assembly name>’ could not be found.” As already mentioned, using an automation layer built with .NET 3.5 SP1 means that your application’s object model or automation layer cannot contain types or features that are new with .NET 4.0. VSTA’s support of VB and C# languages does not reflect .NET 4.0 changes.

o Both VS 2008 IDE and the VSTA 2.0 IDE will not debug a .NET 4.0 application as the start-up application. Instead an error is thrown when starting the project: “The debugger’s protocol is incompatible with the debuggee“. I assume that the problem is caused with host app targeting .NET 4.0 & CLR 4.0 -- since VS2008 only supports up to .NET 3.5, the debugger is unable to correctly attach to a 4.0 managed process (or it doesn’t support .NET 4.0 debugger protocols).

o I’ve encountered a reflection problem when gathering type information (Type t; t.GetMethods();) that only occurs when a .NET 4.0 host application interrogates a VSTA assembly (built on .NET 3.5).

o VS2010 will not open or convert VSTA 2.0 projects (and vice-versa).

Practically speaking, then, integrating VSTA 2.0 with an application built for .NET 4.0 is limited to VSTA script execution. The VSTA script must be created and debugged in a .NET 3.5 context.

Microsoft continues to invest in VSTA as the .NET solution for end user scripting. Presently, Microsoft has not disclosed a timeframe for VSTA support of .NET 4.0.

UPDATE:

Testing on a clean computer with only .NET framework version 4.0 installed demonstrates that your application installer must continue to follow VSTA deployment guidelines and include the correct, previous version of the .NET framework as an installer pre-requisite.

Referencing Host Items in a DPM Project from the Host Item Container

Melody — Thu, 30 Sep 2010 15:24:00 GMT

In Dynamic Programming Model (DPM) style integrations there are three levels of correspondence between a DPM add-in and the host:

1) “Host Item Container”: This is the entry point type which contains the host items and has its own code file in a DPM add-in project. This type and its associated code file would persist even if all host items were removed. For example: a document which contains drawings.

2) Host Items: These are items which receive their own code files in a DPM style integration and are associated with a specific item in the host. If the host item is removed, the associated host item code file is removed from the add-in project. If a new host item is added, an associated host item code file is added to the add-in project. If a host item is renamed, the display name of the associated host item is updated in the add-in project. For example: drawings within a document.

3) Host Objects: These are objects which receive their own variable names within a host item code file in a DPM add-in project. For example: shapes within a drawing.

In the SDK sample ShapeAppDynamicProgrammingModelCSharp a document is used as the host item container and its associated code file is “ThisDocument.xx ” (".cs" or ".vb"). Drawings contained within the document are host items and have code files which match their original name such as “Drawing1.xx”. Shapes within drawings are host objects within host items such as “Circle1” in "Drawing1". These variables are declared and instantiated in the hidden designer file of the associated host item code file. For example: if Drawing1 contained a circle, then Drawing1.designer.xx would have code to declare and instantiate the host object Circle1. Note: to see the hidden designer files, select the "Show All Files" option in the Project Explorer pane and expand the node for a code file (see screen shot below).

Screen shot: Hidden designer file

While host objects have a variable name associated with them that can be accessed through their host items, in the SDK sample, host items do not. Therefore you could use code from within a host item to reference a host object by its variable name, but you cannot use similar code in the host item container to reference a host item.

For example: Here are the start-up methods from the SDK sample for both a host item (Drawing1_Startup) and a host item container (ThisDocument_Startup). The host item can refer on of its hosts object by a variable name; however, a host item container cannot refer to a host item by a variable name in this fashion for SDK style integrations.

private void Drawing1_Startup(object sender, System.EventArgs e)
{
    //refer to a host object by its variable name
    this.Circle1.Color =
        Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.
        Application.CreateColor(System.Drawing.Color.Black.ToArgb());
}

private void ThisDocument_Startup(object sender, EventArgs e)
{
    //CANNOT refer to a host item through a variable name
    // using an SDK style integration
    this.Drawing1.Circle1.Color =
       Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.
        Application.CreateColor(System.Drawing.Color.Black.ToArgb());
}

While it is not possible to reference host items in the same way as it is possible to reference host objects in a standard SDK style integration, it is possible to do this in ProxyShim style integration. This is demonstrated in the Summit sample ShapeAppDynamicProgrammingModelCSharp_ProxyShim which is, like other NoRuntime samples, available upon request after filling out the information form.

For more information on the SDK Dynamic Programming Model style integration see the online MSDN documentation .

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);
}

Add-in Management Options

Melody — Tue, 24 Aug 2010 18:50:00 GMT

There are many different ways to manage add-ins. Below are some common add-in management styles which can be used alone, combined, or used side by side.

1) Basic: all interactions between the host and add-ins are executed in the Startup and Shutdown methods of the add-in. This is demonstrated in the ShapeAppBasicCSharp SDK sample.

Pros: Easy.

Cons: Not very flexible. Repeatedly loading and unloading add-in can cause increase in memory usage.

2) On Demand: interactions between the host and add-ins occur when the host calls into methods in the add-ins.

Pros: Code executed only when needed.

Cons: Requires more management code and invoke calls to execute a method in the add-in are time consuming. Repeatedly loading and unloading add-in can cause increase in memory usage.

3) Macro: a single add-in project is loaded and displayed in the DTE and methods may be created during execution of the host either by the end user adding code or through macro recording with the host. Host then calls into “macro” methods within the add-in project to be run or debugged into.

Pros: Can create, debug, and run code on the fly. Allows for macro recording and offers a VBA like experience.

Cons: Requires more management code, a design time integration, and macro recording code. Invoke calls to execute a method in the add-in are time consuming. Repeatedly loading and unloading add-in can cause increase in memory usage.

4) Event Oriented: add-ins hook into host events and execute code when a host event is fired.

Pros: Easy. Responding to events in the host is less time consuming than invoke calls.

Cons: Must unhook all events prior to unloading the add-in. Repeatedly loading and unloading add-in can cause increase in memory usage.

5) Service Oriented: add-ins register services with a host which can be used by other add-ins. This is based off a blog by Sandeep Bhatia.

Pros: Very flexible.

Cons: Requires some management code and shifts some of the complexity from the host to the add-ins and separate assemblies.

6) Super Add-in: a single add-in contains multiple units of functionality (where each unit could be isolated in an individual add-in). The host makes calls into the add-in to hookup or unhook individual units of functionality.

Pros: No increase in memory usage due to repeatedly loading and unloading add-ins because only one add-in is loaded.

Cons: Requires more management code and invoke calls are time consuming.

With any of the above styles the add-ins can be loaded and unloaded different ways:

1) Host Centric: The add-ins are loaded at the beginning of host application execution and are unloaded when the host terminates. This is demonstrated in the ShapeAppBasicCSharp SDK sample.

2) Document Centric: The add-ins are loaded when a specific document is opened, and unloaded when the document closes. This is demonstrated in the ShapeAppDynamicProgrammingModelCSharp SDK sample. Note that non-DPM add-ins can also be used in document centric ways as was shown in the VSTA v 1 SDK samples with the drawing entry point.

3) On Demand: Add-ins are loaded and unloaded during execution of the host application as needed or requested by the user. This is demonstrated in the ShapeAppMacroRecordingCSharp SDK sample when the macro add-in is unloaded and reloaded during the macro project build cycle. This can be host or document oriented.

Any of the above styles of add-in management may also be used with different styles of integration:

1) SDK: A proxy is used and the VSTA pipeline is used for interactions between the add-ins and host. This style of integration is used in all SDK samples

2) NoRuntime: No proxy is used, instead the add-ins reference the host directly and the VSTA runtime is not referenced or used. This style of integration is used in the Microsoft ShapeAppMacroRecordingCSharp-NoRuntime sample available from Summit upon request (must fill out information form).

3) NoRuntimeProxyShim: A proxy shim, which defines only the entry point types, is used along with a direct reference to the host. The VSTA runtime is referenced, but not used. This style of integration is used in the ShapeAppMacroRecordingCSharp-NoRuntime-ProxyShim sample which is available from Summit upon request (must fill out information form).

Using a Registry Entry to Specify the DebugInfoExeName

Melody — Thu, 29 Jul 2010 16:49:00 GMT

When a VSTA add-in is run or debugged from a stand alone or destructive scenario, the life of the host application is tied to the debugging or running session. In order to start the host application the VSTA add-in must know the location of the exe to run. This information is specified in the project file, in the element DebugInfoExeName. This element can accept either a path to the exe, or a registry entry to search for the value. This can be specified through ProjectGen, changed manually in the project template, or set programmatically by the host. The ShapeApp SDK samples use a registry entry (see code below) so that the path to the exe can be easily changed without editing individual add-ins or manipulating and re-registering project templates. This can be very useful for several reasons, including allowing for a more flexible install instead of requiring the host exe to be at a particular path.

For more information regarding the project templates please see:
     Creating Project Templates (Visual Studio Tools for Applications)
     Project Template Generation Tool (Projectgen.exe)
     Descriptor Schema for Projectgen.exe
     Creating Project Templates Using the Project Template Generation Tool (Projectgen.exe)

Binding Redirects

Melody — Tue, 27 Jul 2010 15:21:00 GMT

As mentioned in Gary's blog Dependent Assembly Binding Redirect (by version), it is possible to use a configuration file to change which version of an assembly to use. This can be very helpful in "tight versioning" scenarios (see blog Proxy Versioning Options for Project Templates ) where a specific version of a proxy is used. Here are some considerations for this:

In order to use a binding redirect the reference must have the SpecificVersion property set to True.

< Reference Include = "ShapeAppCSharpProxy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b2943f7cfe902115, processorArchitecture=MSIL" >
< SpecificVersion > True</SpecificVersion >
</ Reference >

Generally the binding redirect can be specified in the application level configuration file AppName.exe.config (see Gary's blog ); however, there is a known bug with this for VSTA v 1 add-ins after Visual Studio 2008 SP1 is installed. The workaround is to specify the binding redirect in the machine level configuration file Machine.config. This file can be updated through the Microsoft .NET Framework 2.0 Configuration utility or programmatically with admin privileges- see code below.

private void EnsureMachineConfig()
{
    //open the config file
    Configuration MachineConfig = ConfigurationManager.OpenMachineConfiguration();

    //Ge thte runtime section
    ConfigurationSection runtimeSection = MachineConfig.Sections["runtime"]; //case sensitive
    string content = runtimeSection.SectionInformation.GetRawXml();

    //check if the proxy is already being re-directed
    if (!content.Contains("ShapeAppCSharpProxy"))
    {
        //add the entry
        content = content.Replace(
            "</assemblyBinding>",
                "<dependentAssembly>" +
                    "<assemblyIdentity name=\"ShapeAppCSharpProxy\" culture=\"Neutral\" publicKeyToken=\"b2943f7cfe902115\"/>" +
                    "<bindingRedirect oldVersion=\"1.0.0.0\" newVersion=\"2.0.0.0\"/>"+
                "</dependentAssembly>"+
            "</assemblyBinding>");
        //save the changes
        runtimeSection.SectionInformation.SetRawXml(content);
        MachineConfig.Save();
    }
}

For VSTA v 2 Visual Basic add-ins only one version of a proxy can be registered on a machine at any time due to the unique name requirment(see blog Proxy Assembly Registration- Unique Name Required ). For C# add-ins multiple versions of the same proxy can coexist.

Related Forum Post: Dependent Assembly Binding Redirect (by version)

File Name and Path Length Limits

Melody — Thu, 15 Jul 2010 19:00:00 GMT

Windows imposes limits on the lengths of path and file names maxing out around 260 characters. For all Visual Studio projects, including VSTA projects, these limits are further reduced to accommodate for the entire file structure of the project. For instance, the project solution "Test" located at C:\Test\Test.sln which has a fully qualified path name of only 16 characters, needs to accommodate many sub-directories and files including files like C:\Test\Test\obj\Debug\Test.Properties.Resources.resources which has a fully qualified path name of 58 characters. In order to accommodate these files, the limit for Visual Studio and VSTA projects is further reduced by an additional 80 characters bringing the limit to about 180.

For more information on these limits please see the bug report: EnvDTE80.Solution2.AddFromTemplate - Reports path too long incorrectly.

Alternatives to Invoking to Run a Method in an Add-in

Melody — Fri, 14 May 2010 14:49:00 GMT

In scenarios where a method or macro within an add-in needs to be run several times in a short time span, for example 60 times a second, invoking the method may not be the best option. The invoke call, as seen in the ShapeAppMacroRecordingCSharp sample, is too slow to for the level of performance required in these high stress scenarios. A good alternative to this is firing an event in the host and catching it in the add-in. Particularly in NoRuntime style integrations this approach achieves higher performance. Another workaround is to call into the add-in once and pass the number of times to run the method as a parameter. While this will take some coding overhead in the add-in it does achieve very high performance and is ideal for high stress scenarios where the number of times a method needs to be run is known. Don’t limit the performance of your host by sticking to the SDK samples.

Microsoft releases Security Bulletin MS10-031 - Critical

dschneid — Tue, 11 May 2010 18:13:00 GMT

Microsoft has released Security Bulletin MS10-031 which resolves a privately reported vulnerability in Microsoft Visual Basic for Applications (VBA).

The complete Security Bulletin can be found here

Summit has made the updated version of the Visual Basic for Applications SDK that addresses the vulnerability described in this bulletin available here for independent software vendors (ISVs)

From the Security Bulletin...

Vulnerability in Microsoft Visual Basic for Applications Could Allow Remote Code Execution (978213)

This security update resolves a privately reported vulnerability in Microsoft Visual Basic for Applications. The vulnerability could allow remote code execution if a host application opens and passes a specially crafted file to the Visual Basic for Applications runtime. If a user is logged on with administrative user rights, an attacker who successfully exploited this vulnerability could take complete control of an affected system. An attacker could then install programs; view, change, or delete data; or create new accounts with full user rights. Users whose accounts are configured to have fewer user rights on the system could be less impacted than users who operate with administrative user rights.

This security update is rated Critical for all supported versions of Microsoft Visual Basic for Applications SDK and third-party applications that use Microsoft Visual Basic for Applications. This security update is also rated Important for all supported editions of Microsoft Office XP, Microsoft Office 2003, and the 2007 Microsoft Office System. For more information, see the subsection, Affected and Non-Affected Software, in this section.

The update addresses the vulnerability by modifying the way that Visual Basic for Applications searches for ActiveX Controls embedded in documents. For more information about the vulnerability, see the Frequently Asked Questions (FAQ) subsection for the specific vulnerability entry under the next section, Vulnerability Information.

Recommendation. Microsoft recommends that customers apply the update immediately.

Developer Tools

Developer Tools	Maximum Security Impact	Aggregate Severity Rating	Bulletins Replaced by this Update
Microsoft Visual Basic for Applications^[1] (KB974945)	Remote Code Execution	Critical	MS06-047
Microsoft Visual Basic for Applications SDK^[2][3]	Remote Code Execution	Critical	MS06-047

^[3]The updated version of the Visual Basic for Applications SDK that addresses the vulnerability described in this bulletin is available for independent software vendors (ISVs) from the Summit Software Company. For more information, see the next section, Frequently Asked Questions (FAQ) Related to This Security Update.