Melody's VSTA Blog

Add-in Management Options

2010-08-24T18:50:00Z

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).

Binding Redirects

2010-07-27T15:21:00Z

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)

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

2010-05-14T14:49:00Z

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.

NoRuntime ProxyShim Style Integration

2010-05-07T17:52:00Z

The ShapeAppCSharpMacroRecordingCSharp-NoRuntime sample (not included in SDK, please contact info@summsoft.com for more information) has many benefits over the normal SDK style integration. These benefits include less memory usage (up to a factor of 10), faster load/unload and processing time for add-ins, as well as a simpler integration experience. Coupled with a “proxy shim” which defines only entry point types, this style of integration offers add-ins the same direct access to the host object model as the SDK style integration. Summit has developed tools to upgrade traditional VSTA v 1 and convert VSTA v 2 SDK integration style add-ins to NoRuntime ProxyShim style integration add-ins without changing any core or user visible add-in code.

If you are interested in more information on the NoRuntime sample or the Summit tools to upgrade from VSTA v 1 or convert from VSTA v2 add-ins to this style of integration please contact us at info@summsoft.com.

Communicating with a COM host through a VstaIntegration library

2010-04-22T13:47:00Z

When using a VstaIntegration library with some COM hosts, such as the MyAppVB6 sample, there are two ways to communicate:
1) Through public methods and properties.
2) Through public events.

Some instances where raising a public event from the VstaIntegration library and catching it in the COM host is appropriate include the IExternalDebugHost methods in the VstaRuntimeIntegration class: OnBeforeDebugStarting, OnDebugStart, and OnDebugStop methods.

In the typical .Net integration it is easy to simply add code to these methods (which are called by the VSTA design time during debugging events) to allow the host to do any necessary actions. However, for some integrations where the host application is unknown to the VstaIntegration library, raising an event to alert the host is the way to go.

The code below demonstrates this with the OnDebugStop method.
The basic steps to do this are:

1) In the VstaIntegration library the VstaDesignTimeIntegarion class exposes a public event OnDebugStopping.
2) The host application monitors this event. In this case the host is a VB6 host so it also declares the variable for this class as "with events" and hooks into the event by using the naming convention (variableName_eventName) for the method to react to the event.
3) The event is raised in the VstaIntegaration code.

'1) expose a public event
Public Event OnDebugStoppingEvent()

''' <summary>
''' Called when debugging is stoped.
''' </summary>
Public Sub OnDebugStopping() Implements Microsoft.VisualStudio.Tools.Applications.DesignTime.IExternalDebugHost.OnDebugStopping

    If (Not Me.mIsDebugging Or Me.mIsShuttingDown) Then
        Return
    End If

'3) raise the OnDebugStoppingEvent
RaiseEvent OnDebugStoppingEvent()

Me.UnloadCurrentMacroAddin()

    ' Do not reload the macro if a new macro is being recorded.
    If Me.mReloadInProc Then
        Me.LoadMacros(Nothing)
    End If

Me.mReloadInProc = True
Me.mIsDebugging = False

End Sub

'2 for VB6) declare with events to catch debugger stopping events
Public WithEvents IdeIntegration As VSTA2_Integration.VSTADesignTimeIntegration

'2) monitor and catch the event by using the naming convention variableName_EventName for the method name.
Sub IdeIntegration_OnDebugStoppingEvent ()

MsgBox("do clean up here")

End Sub

How To Stop a Macro Method During Execution

2010-03-25T19:51:00Z

In order to stop a “macro” method during execution the macro method must be invoked on a separate thread. This is because macro methods invoked on the same thread as the host will block the host. In the ShapeAppCSharp SDK samples macro methods are called on a separate thread if the VSTA IDE is in the debugging state. It is necessary to change all macro method invocations to a separate thread in order to stop them .

Once all macro methods are invoked in separate threads, the easiest way to interrupt the execution of the macro method is to load and unload the macro assembly. To do this, you must catch the AppDomainUnloaded exception in the ExecuteMacroInternal method.

/// <summary>

/// Execute the first public instance method with name

/// <paramref name="macroName"/> which takes no parameters.

/// </summary>

/// <param name="macroName">Name of the macro to execute.</param>

internal void ExecuteMacro(string macroName)

{

//SDK warning- no issues adding shapes, but maybe other UI issues?

// If the macro calls host API that interacts with host UI, the call needs to happen on the main UI thread.

// However, during out-of-process debugging, if we execute macro on the main UI thread, the main UI thread may be blocked

// and cannot process any reentrant method calls.

// Here we spawn a separate thread so that the main UI thread can service other reentrant method calls.

//all macros called on new thread in order not to block the host during execution, so that macros can be stopped.

Thread t = new Thread(() =>

{

ExecuteMacroInternal(macroName);

});

t.SetApartmentState(Thread.CurrentThread.GetApartmentState());

t.Start();

// Do not call t.Join(); Otherwise it'll block and the host will be frozen.

}

/// <summary>

/// Execute the first public instance method with name

/// <paramref name="macroName"/> which takes no parameters.

/// </summary>

/// <param name="macroName">Name of the macro to execute.</param>

internal void ExecuteMacroInternal(string macroName)

{

// If no Macros loaded

if (this.application.VstaRuntimeIntegration.MacroAddIn == null)

return;

IExtendedEntryPoint entryPoint =

this.application.VstaRuntimeIntegration.MacroAddIn as IExtendedEntryPoint;

System.Diagnostics.Debug.Assert(entryPoint != null);

if (entryPoint == null)

return;

object obj = entryPoint.GetEntryPointObject();

Type t = obj.GetType();

try

{

t.InvokeMember(macroName, BindingFlags.Public |

BindingFlags.Instance | BindingFlags.InvokeMethod, null, obj, null);

return;

}

catch (System.Runtime.Remoting.RemotingException ex)

{

// Swallow remoting exception.

System.Diagnostics.Debug.WriteLine(ex.ToString());

}

catch (AppDomainUnloadedException macroStopUnloadEx)

{

// Swallow remoting exception.

System.Diagnostics.Debug.WriteLine(macroStopUnloadEx.ToString());

}

catch (Exception e)

{

System.Windows.Forms.MessageBox.Show("Error executing macro\n" + e.Message,

"ShapeAppCSharp", MessageBoxButtons.OK, MessageBoxIcon.Error);

}

// Didn't find a method to invoke, so show a message box.

System.Windows.Forms.MessageBox.Show("Unable to execute macro: " + macroName,

"ShapeAppCSharp", MessageBoxButtons.OK, MessageBoxIcon.Error);

}

internal void StopMacro_UnloadLoad()

{

//IF the macro project is debugging, stop the debugger to force unload/load

if (this.application.VstaDesignTimeIntegration.isDebugging)

{

this.application.VstaDesignTimeIntegration.StopDebugging(false);

}

else //not debugging- unload and reload the add-in

{

this.application.VstaRuntimeIntegration.UnloadCurrentMacroAddin(false);

this.application.VstaRuntimeIntegration.LoadMacrosInProcess();

}

How to Determine if a Project isDirty

2010-03-19T17:04:00Z

As previously noted the isDirty property of a project is for “Microsoft Internal Use Only” and does not actually return valid information. Instead you can determine this by querying for unsaved ProjectItems. The property MacroProjectSaved below demonstrates how to do this. Additional code is included to show how to ask a user if they would like to save the macro project when they exit the IDE if the project has unsaved items (some of this code is repeated from previous blogs).

//determines if there are unsaved project items in the macro project

private bool MacroProjectSaved

{

get

{

if (this.macroProject.Saved)

{

int unsavedProjItemCount =

(from EnvDTE.ProjectItem projItem in

this.macroProject.ProjectItems

where !projItem.Saved

select projItem).Count();

return unsavedProjItemCount == 0;

}

else

{

return false;

}

private void EnsureIDE()

{
//save this variable in the class scope to prevent unwanted garbage collection

//get and subscribe to the File.Exit event prior to execution

EnvDTE.CommandEvents exitCommand =

dte.Events.get_CommandEvents

("{5EFC7975-14BC-11CF-9B2B-00AA00573819}", 229);

exitCommand.BeforeExecute +=

new EnvDTE._dispCommandEvents_BeforeExecuteEventHandler

(exitCommand_BeforeExecute);

}

//checks if the user would like to save the project before exiting if the project is dirty

void exitCommand_BeforeExecute(string Guid, int ID, object CustomIn, object CustomOut, ref bool CancelDefault)

{

//Project.IsDirty is always false, so use the below property MacroProjectSaved

if (!this.MacroProjectSaved)

{

//prompt the user to save the project

EnvDTE.vsPromptResult promptResult =

this.dte.ItemOperations.PromptToSave;

if (promptResult == EnvDTE.vsPromptResult.vsPromptResultYes)

this.MacroProject.Save(this.macroProject.FileName);

}

How to: Prompt the User to Save Unsaved Files

2009-06-19T15:14:00Z

A useful function the DTE has a built in is to prompt the user to save any unsaved files. It is a good idea to make this call in when shutting down the DTE, for example in the disconnect method of the VstaDesignTimeIntegration class.

EnvDTE.vsPromptResult promptResult = this.dte.ItemOperations.PromptToSave;

Below is a modified VstaDesignTimeIntegration.Disconnect method from the ShapeAppMacroRecordingCSharp SDK sample with this call added. The prompt will appear whether or not the DTE is visible

internal void Disconnect()
{
//prompt the user to save any unsaved files
EnvDTE.vsPromptResult promptResult = this.dte.ItemOperations.PromptToSave;

this.isShuttingDown = true;

StopDebugging(true);

    // Unload external process
    try
    {
        if (this.macroAddInProcess != null)
        {
            this.macroAddInProcess.ShuttingDown -= MacroAddInProcessExiting;
            this.macroAddInProcess.Shutdown();
            this.macroAddInProcess = null;
        }
    }
    catch (Exception ex)
    {
        // Swallow the exception. We don't want to crash if the process has already been destroyed.
        System.Diagnostics.Debug.WriteLine(ex.ToString());
    }
}

Frequent Events and Garbage Collection

2009-06-17T14:46:00Z

When an event will be fired many times it is a good practice to do periodic garbage collection. When a VSTA add-in hooks into an event which is fired many times this becomes even more important because the memory usage for the host process will grow very high without periodic garbage collection.

The charts below demonstrate that when a VSTA add-in is hooked into an event the memory usage grows. This is case even if the VSTA add-in does not perform any actions when the event is fired (see the "Empty VSTA Event Hooked-up" line in Chart 1). If the VSTA add-in does perform actions when the event is fired the memory usage will grow even faster (see the "VSTA Event Hooked-up" line in Chart 1). When GC.Collect is called periodically this increase in memory usage is almost completely negated; notice in Chart 1 the base line "No VSTA Event Hooked-up" is at the same memory usage levels as the lines where garbage collection is called periodically ("VSTA Event Hooked-up & Host call GC every 50 event fires" and "VSTA Event Hooked-up & Host call GC every 500 event fires"). These three lines, the base and lines where periodic garbage collection is done, are displayed again in Chart 2 to show how close the memory usage levels are.

Chart 1- Memory Usage Levels With and Without Periodic Garbage Collection

Chart 2- Memory Usage Levels With Periodic Garbage Collection

This applies to both VSTA v 1 and VSTA v 2.

VSTA Configuration Entries: ItemTemplatesLocation versus VSItemTemplatesLocation

2009-05-29T15:55:00Z

The ItemTemplatesLocation entry in the VSTA host configuration hive is used to specify the location of item templates which will only be available through the VSTA host they are registered under. This is different than the VSItemTemplatesLocation entry which is used to specify the location of item templates which will be available through Visual Studio 2008 and all VSTA hosts.

To use the ItemTemplatesLocation entry,

1) Delete the context hive for the host. This must be done for the changes to take affect even if the ItemTemplatesLocation entry was not used previously.

2) Add the ItemTemplatesLocation entry and value to the configuration hive.

3) Run vsta setup for the host. This will extract the item templates to the VSTA item templates cache under C:\Documents and Settings\All Users\Application Data\Microsoft\VSTAHost\<HostID>\9.0\ItemTemplatesCache

The item templates stored in the ItemTemplatesLocation will now appear under the root node in the Add New Item Wizard and will not be available for other hosts or Visual Studio projects.

The VSItemTemplatesLocation entry requires the following steps to function properly:

1) Add the VSItemTemplatesLocation entry and value to the configuration hive.

2) Run vsta setup for the host. This will move the item templates from the location specified in the VSItemTemplatesLocation to the Visual Studio 2008 item templates folder under a subfolder matching the hosted: %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE\ItemTemplates\Host ID.

3) Run devenv setup. Once vsta setup has moved the templates from the VSItemTemplatesLocation to the Visual Studio item templates storage folder you must run devenv setup to extract the item templates to the Visual Studio and VSTA item templates caches.

The item templates will appear in a category which matches the HostID under the Add New Item wizard.

For more information on this, see the on-line documentation on Host Configuration Registry Key Settings

ItemTemplatesLocation

If you create custom item templates for Visual Studio Tools for Applications projects, use this entry to provide a path to those templates. These items will appear in the Add New Item dialog box of the Visual Studio Tools for Applications IDE.

When you install Visual Studio Tools for Applications or run vsta.exe using the /setup switch, Visual Studio Tools for Applications does the following:

Copies the value of ItemTemplatesLocation to the UserFolder entry of the following key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSTAHost\host ID\9.0\VSTemplate\Item.
Extracts the .zip files from the path that was copied to the UserFolder entry and places the files in %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE\ItemTemplatesCache. CORRECTION: the item template is not extracted to this location, but instead to C:\Documents and Settings\All Users\Application Data\Microsoft\VSTAHost\<HostID>\9.0\ItemTemplatesCache

VSItemTemplatesLocation

If you create custom item templates for Visual Studio 2008 projects, use this entry to provide a path to those templates. These items will appear in the Add New Item dialog box of Visual Studio.

When you install Visual Studio Tools for Applications or run vsta.exe using the /setup switch, Visual Studio Tools for Applications copies the contents of the directory specified by the VSItemTemplatesLocation entry to %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE\ItemTemplates\Host ID.

You must then regenerate the Visual Studio 2008 template cache so it includes the new templates. You can accomplish this by running devenv.exe using the /setup switch. Devenv.exe is usually located at %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE, but it can be installed in another location if the user overrides the default location. If you need to regenerate the template cache programmatically, you can locate devenv.exe by reading the InstallDir registry entry at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0. For more information, see Devenv Command Line Switches.

The Host Item Node in VSTA Projects

2009-05-26T16:39:00Z

Within a VSTA project there is a Host Item Node. This displays in the Project Explorer as a subfolder within the VSTA project and contains the main code file as well as any DPM files. By default the folder's name is the HostID and the icon is the open or closed folder icon. These settings can be changed in the project template under the Host node in the ProjectExtensions section.

VSTA host item specific code files are stored here so that they may be accessed through IVstaHostAdapter.ProjectHostItems. The SDK samples demonstrate this in the Macro Recording and Dynamic Programming Model samples (see code below).

<!-- This section defines properties that apply to HostItems.

Host - Properties of the folder node in the project.

Name - The display name of the folder node.

GeneratedCodeNamespace - Namespace of code files contained in the folder node.

Used by the Properties window in Project Explorer.

IconIndex - 0-based index in the IconImageList of the icon for this node.

OpenFolderIconIndex - 0-based index in the IconImageList of the open folder icon for this node.

-->

<Host

Name="ShapeAppCSharp AddIn Folder"

GeneratedCodeNamespace="$safeprojectname$"

IconIndex=""

OpenFolderIconIndex="">

<HostItem

Name="AppAddIn"

Code="AppAddIn.cs"

CanonicalName="AppAddIn"

Blueprint="AppAddIn.Designer.xml"

GeneratedCode="AppAddIn.designer.cs"

IconIndex="" />

</Host>

Macro Recording Sample:

internal void SaveMacro(System.CodeDom.CodeMemberMethod method)

{

if (this.macroProject == null)

{

if (!ShowIde(false))

return;

}

IVstaHostAdapter hostAdapter = (IVstaHostAdapter)this.macroProject.get_Extender("VSTAHostAdapter2007");

string hostItemFileName = hostAdapter.ProjectHostItems[0].CodeFilePath;

string hostItemClassName = hostAdapter.ProjectHostItems[0].ProgrammingModelHostItem.Identifier;

EnvDTE.ProjectItem hostItemProjectItem =

this.macroProject.ProjectItems.Item(Path.GetFileName(hostItemFileName));

EnvDTE.CodeClass hostItemClass = FindClass(hostItemClassName, hostItemProjectItem.FileCodeModel.CodeElements);

method.Name = GenerateNewMacroName(hostItemClass);

hostItemProjectItem.Open("{7651A701-06E5-11D1-8EBD-00A0C90F26EA}");

hostAdapter.ProjectHostItems[0].AddMethod(method);

hostItemProjectItem.Save(null);

this.macroProject.DTE.Solution.SolutionBuild.Build(true);

}

Dynamic Programming Model Sample

private IVstaProjectHostItem AddProjectHostItemInternal(string itemName, string templateName, string itemEntryPoint)

{

foreach (IVstaProjectHostItem existingItem in this.hostAdapter.ProjectHostItems)

{

if (existingItem.ProgrammingModelHostItem.Cookie == itemName)

return null; // Do not add existing one.

}

// Make sure the template is not read-only.

string languageFolder = null;

string languageExtension = null;

if (this.language == SupportedLanguage.CSharp)

{

languageFolder = "CSharp";

languageExtension = ".cs";

}

else

{

languageFolder = "VisualBasic";

languageExtension = ".vb";

}

string templatePath = this.hostItemTemplatesPath + @"\" + languageFolder + @"\" + templateName + languageExtension;

FileInfo fileInfo = new FileInfo(templatePath);

bool isReadOnly = fileInfo.IsReadOnly;

fileInfo.IsReadOnly = false;

IVstaProjectHostItem projectHostItem = null;

try

{

projectHostItem = hostAdapter.ProjectHostItems.AddProjectHostItem(

itemName,

"Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp." + itemEntryPoint,

"Microsoft.VisualStudio.Tools.Applications.Runtime.IEntryPoint",

itemName,

this.hostItemTemplatesPath + @"\" + languageFolder + @"\" + templateName);

this.project.Save(this.project.FileName);

}

finally

{

fileInfo.IsReadOnly = isReadOnly;

}

if (projectHostItem != null)

return projectHostItem;

else

throw new InvalidOperationException("Fail to add project host item.");

}

Saving DTE and other COM Event Hook-ups

2009-04-29T15:00:00Z

To avoid losing an event hook-up from a COM source it is necessary to hold a local reference to the source of the event to avoid unwanted garbage collection. This is a concern for VSTA hosts hooking into DTE events as well as VSTA add-ins which use a direct reference to a COM host instead of a proxy.

For example, in the SDK the DTE source events are each saved in a local variable and hooked into from these variables. If you attempt to hook into the events without saving event sources the hook-ups can be lost.

To test if an event hookup will preset, call GC.Collect in the event sink and re-fire. If the event is hit again the hookup should persist.

Example of how to hook into DTE events from a host:
When events sources are saved, event hookups will continue to work after garbage collection.
private EnvDTE.BuildEvents buildEvents;
private void HookupDteEvents_GOOD()
{
    // Save a copy of the event sync locations so they don't get
    // garbage collected.
    this.buildEvents = this.dte.Events.BuildEvents;

this.buildEvents.OnBuildBegin += new
EnvDTE._dispBuildEvents_OnBuildBeginEventHandler(buildEvents_OnBuildBegin);

}

void buildEvents_OnBuildBegin(EnvDTE.vsBuildScope Scope,
EnvDTE.vsBuildAction Action)

{

//Call GC.Collect to test if the event hookup will persist

System.Windows.Forms.MessageBox.Show(

"Call GC.Collect after firing event to test hook-up");

GC.Collect();

}

Example of how NOT to hook into DTE events from a host:
When events sources are not saved, event hookups will not continue to work after garbage collection.
private void HookupDteEvents_BAD()
{
    // DON’T DO THIS
    // Hook into the event through the dte w/o saving source
    this.dte.Events.BuildEvents.OnBuildBegin +=new
        EnvDTE._dispBuildEvents_OnBuildBeginEventHandler(buildEvents_OnBuildBegin);

}

void buildEvents_OnBuildBegin(EnvDTE.vsBuildScope Scope,
EnvDTE.vsBuildAction Action)
{

//Call GC.Collect to test if the event hookup will persist

System.Windows.Forms.MessageBox.Show(

"Call GC.Collect after firing event to test hook-up");

GC.Collect();

}

Example of how to hook into host events from an add-in using a direct reference to a COM host:
When events sources are saved, event hookups will continue to work after garbage collection. From MyAppVB6 sample.
private void AppAddIn_Startup(object sender, EventArgs e)
{
this.Document.KeyPress += new
__Document_KeyPressEventHandler(Document_KeyPress);

doc = this.Document;

doc.KeyPress += new
__Document_KeyPressEventHandler(doc_KeyPress);

    //if the local variable is saved, hooking into this.Document will work
    //this.Document.KeyPress += new
    //      __Document_KeyPressEventHandler(Document_KeyPress);

}

Document doc;
void doc_KeyPress(ref short KeyCode)
{

System.Windows.Forms.MessageBox.Show(
"Hooking into this.Document with saving it won't work");

GC.Collect();
}

Example of how NOT to hook into host events from an add-in using a direct reference to a COM host:
When events sources are not saved, event hookups will not continue to work after garbage collection. From MyAppVB6 sample.
private void AppAddIn_Startup(object sender, EventArgs e)
{
this.Document.KeyPress += new
__Document_KeyPressEventHandler(Document_KeyPress);
}

void Document_KeyPress(ref short KeyCode)
{

System.Windows.Forms.MessageBox.Show(
"Hooking into this.Document w/o saving it won't work");

GC.Collect();
}

VSTA v 2 Proxy Names- Unique Names for Proxy Versions

2009-04-28T15:00:00Z

For VSTA v 2 Visual Basic add-ins, unique version specific proxy names are required for registration in the VSTA pipeline. Also, each host should use host specific names for all proxies.

If multiple versions of a proxy will be used by VSTA v 2 Visual Basic add-ins, the different versions of the proxy must each have a unique name. This will avoid a proxy being overwritten in the VSTA pipeline folder by another proxy with the same name but different version number. This is not an issue for C# add-ins because they can resolve the reference to the proxy assembly in the GAC; however, for Visual Basic add-ins this is a requirement.

All proxies should have a host specific name. This will avoid file naming collisions in the VSTA pipeline with other hosts, which can result in a proxy being overwritten in the pipeline and Visual Basic add-ins being unloadable (VSTA v 2). This will also avoid any ambiguity in the GAC (VSTA v 1 and v 2). For example an add-in could reference a proxy with the same name as another proxy present in the GAC and end up referencing the first instance of a proxy in the GAC with the same name instead of the intended proxy (see the section on loose versioning in the Proxy Versioning Options for Project Templates blog).

Example Proxy Names:
BAD- VSTAProxy

GOOD- HostA_VSTAProxy_v1

VSTA Pipeline location:
C:\Program Files\Common Files\Microsoft Shared\VSTA\Pipeline

Proxy assemblies are stored in:
C:\Program Files\Common Files\Microsoft Shared\VSTA\Pipeline\AddInViews

VSTA and Packaging

2009-04-07T17:08:00Z

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

VSTA v 2 in Visual Basic 6.0 sample now available

2009-04-06T18:30:00Z

A new VB6 VSTA v 2 sample is available for download.

Below is from the READ ME.doc included in the sample:

There are many ways to integrate VSTA v 2.0 with a VB6 application. This sample demonstrates an advanced integration option (with seamless non-destructive debugging but no macro management) which closely follows the integration code from the SDK samples.

A COM visible library, VSTA2_Integration, is referenced by the VB6 host application, MyAppVB6. The VSTA2_Integration library exposes the classes VSTARunTimeIntegration and VstaDesignTimeIntegration. The VB6 host first creates and connects to its VSTARunTimeIntegration instance passing in the object to be used as an entry point (see definition below) for add-ins through the VSTARunTimeIntegration.Connect method. Then the VB6 host creates and connects to its VSTADesignTimeIntegration instance passing in the VSTARunTimeIntegration instance through the VSTADesignTimeIntegration.Connect method.

This host object (passed in through the VSTARunTimeIntegration.Connect method) is stored in the internal VSTA2_Integration.HostItemProvider (see definition below) which is passed into the add-ins through the VSTA pipeline. Once the host object is passed through the pipeline, it is stored in the add-in in a hidden code file and accessed through “Me” or “Me.Application” (see section on templates below).

The VSTARunTimeIntegration.Connect method makes calls to load add-ins and the VSTARunTimeIntegration.Disconnect method makes calls to unload add-ins. The VB6 host calls the VSTARunTimeIntegration.Connect method on form load, and VSTARunTimeIntegration.Disconnect on form unload. This can easily be changed so that add-ins can be loaded and unloaded by selecting a button on the host.

The DesignTimeIntegration.Connect method takes in and stores the VSTARunTimeIntegration instance and prepares for IDE management. The DesignTimeIntegration.ShowIDE method displays the IDE with a new or existing VSTA project open. The DesignTimeIntegration.Disconnect method disposes of the IDE. The VB6 host calls the DesignTimeIntegration.Connect on form load and the DesignTimeIntegration.Disconnect on form unload. It is not advisable to change this. The ShowIDE method is called through a button on the VB6 host.

This sample does not use a proxy or HostTypeMapProvider, instead a “proxy shim" is included in the add-in to provide a MyAppVB6 entry point. This class is defined in the hidden AppAddIn.designer2.xx file included with the project templates.

Two sets of templates are included with this sample. The “MyAppVB6_VSTA2_Template_Robust.zip” templates allow the add-in to access the host object through “Me” or “this”. The “MyAppVB6_VSTA2_Template.zip” templates allow the add-in to access the host object through “Me.Application” or “this.Application”. For the robust templates, the hidden file AppAddIn.designer2.xx contains code which re-implements/exposes some or all of the entry point type from the VB6 host. The only benefit to this additional code is it allows the host object to be accessed more directly through “Me” or “this” instead less directly through “Me.Application” or “this.Application”. Which type of template to use is a design decision.