Melody's VSTA Blog

How to: Prompt the User to Save Unsaved Files

Melody — Fri, 19 Jun 2009 15:14:00 GMT

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

Melody — Wed, 17 Jun 2009 14:46:00 GMT

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

Melody — Fri, 29 May 2009 15:55:00 GMT

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

Melody — Tue, 26 May 2009 16:39:00 GMT

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

Melody — Wed, 29 Apr 2009 15:00:00 GMT

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

Melody — Tue, 28 Apr 2009 15:00:00 GMT

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

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

VSTA v 2 in Visual Basic 6.0 sample now available

Melody — Mon, 06 Apr 2009 18:30:00 GMT

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.

Proxy Assembly Registration- Unique Name Required

Melody — Mon, 26 Jan 2009 20:53:00 GMT

VSTA v 2.0 add-ins use two mechanisms to associate add-ins with proxy assemblies. These include the Global Assembly Cache (GAC) and the VSTA pipeline. Each has separate considerations to take into account when naming your proxy assembly.

The Global Assembly Cache (GAC) and Add-in Projects
The proxy assembly should be registered in the GAC so that add-in projects can resolve the reference without requiring a local copy or absolute path. It is possible to get around this by modifying the project templates to use a hint path, but ProjectGen will complain if the proxy assembly in not registered here. Considerations, including naming schemes, for how add-in projects resolve the reference to the proxy assembly registered in the GAC have been covered in a previous blog, Proxy Versioning Options for Project Templates.

The SDK samples register the proxy assembly in the GAC using a post build event and the file InstallInGAC.bat.

The VSTA pipeline and Visual Basic Add-in Assemblies
When Visual Basic add-ins are loaded through the VSTA pipeline, the proxy assembly must be registered with the pipeline. This means that the proxy assembly should be copied to %Common Program Files%\Microsoft Shared\VSTA\Pipeline\AddInViews (see the section on "Additional Requirments for Visual Basic Add-ins" in the MSDN documentation for Creating Proxies). Unlike the GAC, proxies with non-unique names cannot co-exist here; therefore, proxy assemblies must use unique names or they will be overwritten.

If the proxy assembly is not present here, then Visual Basic add-ins will not load. Instead they will throw a file not found a FileNotFoundException when activate is called (see code and exception below). In the case where the proxy assembly is overwritten, the results will vary depending on the compatibility of the proxy assemblies. If the assemblies are completely incompatible then the addInToken.Count will be zero.

The SDK samples register the proxy with the VSTA pipeline by using a post build event and the file InstallForVB.bat which copies the proxy assembly to %Common Program Files%\Microsoft Shared\VSTA\Pipeline\AddInViews and runs AddInUtil –PipelineRoot:”%Pipeline location%” -Rebuild

Note this is not a consideration for C# add-ins.

FileNotFoundException will occur here if the proxy is not in C:\Program Files\Common Files\Microsoft Shared\VSTA\Pipeline\AddInViews when attempting to load a VB add-in
IEntryPoint addIn = addInToken[0].Activate<IEntryPoint> _
(AddInSecurityLevel.FullTrust);

Exception if proxy assembly is not in …VSTA\Pipeline\AddInViews:
System.IO.FileNotFoundException was caught
Message="Could not load file or assembly 'file:///C:\\Program Files\\Common Files\\Microsoft Shared\\VSTA\\Pipeline\\AddInViews\\ShapeAppCSharpProxy.dll' or one of its dependencies. The system cannot find the file specified."
…
at System.AddIn.Hosting.AddInToken.Activate[T](AddInSecurityLevel trustLevel)
at Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.VstaRunTimeIntegration.LoadAddIn(String addInPath, String startUpClass) in C:\ShapeAppSamples\VSTA v 2 RTM\ShapeAppBasicCSharp\integration\basic\VstaRunTimeIntegration.cs:line 161

addInToken.Count will be zero if the proxy was overwritten by an incompatible proxy:

Collection<AddInToken> addInToken = AddInStore.FindAddIn(typeof(IEntryPoint), AddInStoreExtensions.DefaultPipelinePath, addInPath, startUpClass);

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

Code Analysis Suppress Message Attributes in the ShapeAppCSharp Samples

Melody — Mon, 26 Jan 2009 15:58:00 GMT

In the ShapeAppCSharp samples included with the VSTA v 2.0 SDK you may notice most types and methods are marked with a System.Diagnostics.CodeAnalysis.SuppressMessage attribute. These attributes are not involved with the VSTA integration; they are used by the Team Foundation System’s (TFS) code analysis functionality and can be safely removed if not using TFS code analysis (related forum post).

For more information on these attributes, please refer to the MSDN documentation Suppress Warnings Using SuppressMessage Attribute and In Source Suppression Overview.

Excerpt from In Source Suppression Overview:
After reviewing the code, you might determine that the code is correct as is. Or, it might be the case that some violations are low priority and will not be fixed in the current development cycle. Regardless of the reason, it is frequently useful to indicate that the warning is non-applicable in order to let the team members know that the code was reviewed and it was determined that the warning be suppressed. In source suppression is useful because it allows a developer to put that suppresses warning close to the warning itself.

You can use the Error List window to suppress managed code analysis warnings. Suppressing a warning differs from disabling it. When you suppress a warning, it applies only to a particular instance of the violation. Other violations of the same warning will still be reported in the Error List window.

Adding a Hidden File to a Project Template

Melody — Thu, 22 Jan 2009 16:00:00 GMT

In many situations you want to add background code to a project template without exposing it to the end user. An easy way to do this is to add a hidden code file to the template. Here are the 6 steps to do this which are the same for both C# and VB templates:

1) Unzip the existing project template.

2) Add the file to use as the hidden code file to the same folder as all other files in the template (do not put it in a sub folder).

3) Update the vstemplate file to include the hidden file. Use the same syntax as the main code file.

4) Update the xxproj file to include the hidden file. Use similar syntax as the hidden xml designer file.

5) Save and re-zip the updated template, moving the new zip file to the ProjectTemplatesLocation.

6) Run vsta setup for the host.

Attached are sample templates updated with a hidden code file for the ShapeAppCSharp SDK samples. To use these templates, place them in the ProjectTemplatesLocation, run setup, then create a new add-in project based off the templates.

A video covering this sample is also available.

Project Explorer with hidden file (ShowAll turned on):

Step 4- vstemplate update
<TemplateContent>
    <Project
        File="ShapeAppCSharpAppAddInProject.vbproj"
        ReplaceParameters="true">
      
      <ProjectItem
            ReplaceParameters="true"
            TargetFileName="AppAddIn.vb">AppAddIn.vb</ProjectItem>
      
      <ProjectItem
          ReplaceParameters="true"
          TargetFileName="HiddenFile.vb">HiddenFile.vb</ProjectItem>

Step 5- xxproj file update
<ItemGroup>

<None
      Include="AppAddIn.designer.xml">
    <DependentUpon>AppAddIn.vb</DependentUpon>
</None>

<Compile
      Include="HiddenFile.vb">
    <DependentUpon>AppAddIn.vb</DependentUpon>
</Compile>

Examples
VB
Hidden code file:
Partial Public Class AppAddIn
    Default Public ReadOnly Property Item(ByVal index As Integer) As Drawing
        Get
            Return Me.Document.Drawings(index)
        End Get
    End Property
End Class

Add-in using code from hidden code file:
Private Sub AppAddIn_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
Me(0).Shapes.Add(Me.AvailableShapes(1).Clone())
End Sub

C#
Hidden code file
using Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp;

namespace ShapeAppCSharpAppAddIn1{

    public partial class AppAddIn{
        public Drawing this[int index]
        {
            get { return this.Document.Drawings[index]; }
        }
    }
}

Add-in using code from hidden code file:
public partial class AppAddIn{
    private void AppAddIn_Startup(object sender, EventArgs e)
    {
        this[0].Shapes.Add(this.AvailableShapes[1].Clone());
    }
    ...
}

UpgradeHelper Sample Now Available

Melody — Thu, 04 Dec 2008 19:52:00 GMT

A new sample "UpgradeHelper Sample" is available showing how to register and use an UpgradeHelper.

Excerpt:

To support VSTA v 1 projects in VSTA v 2 you need to create and register an UpgradeHelper. This helper is triggered when a VSTA v 1 project is opened in the VSTA v 2 IDE. If VSTA v 1 is installed, VSTA v 1 projects will still open normally in the VSTA v 1 IDE when doubled clicked. Projects must be opened through the VSTA v 2 IDE to trigger the UpgradeHelper and once upgraded will open in the VSTA v 2 IDE when double clicked.

A couple of notes about using an UpgradeHelper:

1) You must use two unique HostID’s in order to use an UpgradeHelper. Using the same HostID for VSTA v 1 and VSTA v 2 will cause the UpgradeHelper not to be triggered. Related topic: How to Update a Host’s Folder in %My Documents%.

2) In the RemovedReferences section use only the name of the reference to removed- including any other information like the version or public key token will result in the reference not being removed.

3) Only valid projects will trigger the UpgradeHelper. Projects missing the AppAddIn.designer.cs file from the list of compilable files will not trigger the UpgradeHelper.

4) To be sure that the correct version of a reference is added, you may want to use the full GAC information for the reference since you cannot specify SpecificVersion=true. Related topic: Proxy Versioning Options for Project Templates. Example: "ShapeAppCSharpProxy, Version=2.0.0.0, Culture=neutral, PublicKeyToken=3c3c0c46dd27dbcf, processorArchitecture=MSIL"

5) VSTA v 1 projects cannot be opened programmatically through VSTA v 2. Using dte.Solution.AddFromFile or dte.Solution.Open will throw an error if the project has not been previously upgraded. We are looking for a workaround for this (add a comment if you know of one please).

6) The UpgradeHelper is triggered at the end of the normal Visual Studio conversion wizard.

7) The VSTA registries required for the UpgradeHelper are a little tricky- you may want to base yours off the included example

New Sample Available: Two Applications Share a HostID Sample

Melody — Tue, 18 Nov 2008 21:31:00 GMT

I posted a new sample today which goes with my previous blog. This sample demonstrates many of the host Application, hostID, proxy and entry point combiniations outlined in the Application, HostID, Proxy, and EntryPoint Associations blog. If there is another combination you are interested in or if you have any questions on the sample, please leave a comment.

Excerpt from the Two Applications Share a HostID Sample:

This sample demonstrates how two applications can share one host ID.

There are two applications which share a common base type library: Applicatoin_A and Application_B share the SharedLib library. Application_B is based on Application_A with additional methods.

Each application has its own entry point type, Applicatoin_A .ApplicationA and Applicatoin_B.ApplicationB, and the shared base type library has an entry point type SharedLib.SharedApplication. Both applications have a HostItemProvider which can return the entry point for its application or the SharedLib.SharedApplication.

Application_A can load and run add-ins written for the entry points ApplicationA and SharedApplication, but not ApplicationB add-ins.

Application_B can load and run add-ins written for the entry points ApplicationB and SharedApplication, but not Application_A add-ins.

Application_A and Application_B can both debug at the same time (using different macro projects) using the same HostID. Application_A uses a macro project based on the ApplicationA_Template. Application_B uses a macro project based on the ApplicationB_Template.

Results:

It is possible to use the same hostID for different applications and debug them concurrently
It is possible for an application to load and run add-ins, so long as the add-in is compatible with the host (the HostItemProvider must return the entry point type of the add-in).

Application, HostID, Proxy, and EntryPoint Associations

Melody — Mon, 17 Nov 2008 21:54:00 GMT

There are a variety of configurations possible between host applications, hostID's, proxies, and entry points. Which configuration to use is a design decision which requires careful consideration, especially if you are deploying multiple applications bundled together or one application targeted at different user groups. Below are some possible configurations to consider.

Scenario 1) 1 Host Application, 1 HostID, 1 Proxy, 1 Entry Point:
This is the simplest and most straight forward scenario. The host application loads add-ins which are all written against the same proxy using the same entry point. The HostItemProvider for this scenario is very simple because there is only one type to return. The add-ins are created based templates using the same hostID, proxy, and entry point. Multiple templates using the same entry point may be used, for example one template could be the "bare bones" variety generated by ProjectGen and another could be more robust including events already hooked up.

Scenario 2) 1 Host Application, 1 HostID, 1 Proxy, Multiple Entry Points:
This setup builds on the first scenario but offers templates using different entry points, for example Application level and Document level templates. The host loads the add-ins using a more complex HostItemProvider to determine which entry point type to return to the add-ins. The add-ins are created based on templates using the same HostID and proxy, but different templates and entry points. Each entry point must have at least one template to be used by add-ins.

Scenario 3) 1 Host Application, 1 HostID, Multiple Proxies, 1 Entry Point:
This setup is similar to the second scenario but offers templates using different proxies, for example a SimpleOM proxy for basic users and a FullOM proxy for power users. The HostItemProvider for this scenario is very simple because there is only one type to return; the difference in the object model exposed is in the proxy and does not affect the HostItemProvider. The add-ins are created based on templates using the same hostId and entry point, but different templates and proxies. Each proxy must have at least one template to be used by add-ins.

Scenario 4) 1 Host Application, 1 HostID, Multiple Proxies, Multiple Entry Points:
This is a somewhat complex setup which offers both different proxies and different entry points which can be used to make a variety of templates, for example a SimpleApplication and AdvancedApplication as well as SimpleDocument and AdvancedDocument templates (SimpleApplication would have "this" or "me" as an Application object and expose only a few parts of the object model, while the AdvancedDocument would have "this" or "me" as an Document object and expose a robust view of the object model). The host application loads the add-ins written against different proxies and entry points. The HostItemProvider would determine which entry point type to return based on the entry point type of the add-in, for example Application or Document, but not Simple or Advanced; therefore, the SimpleApplication and AdvancedApplication add-ins would be handled the same way by the HostItemProvider. The add-ins are created based on templates using the same hostId but different templates using entry points / proxy combination. Each entry point/proxy combination would need its own template to be used by add-ins.

Scenario 5) 1 Host Application, Multiple HostID, 1 Proxy, 1 Entry Point:
This setup is very similar to the first scenario, but uses different hostIDs. Each hostID has its own templates which could be very similar, for example having the hostID as the only difference. The host application loads add-ins which are all written against the same proxy using the same entry point but multiple hostIDs. The HostItemProvider for this scenario is very simple because there is only one type to return. Add-ins are loaded based on entry point types, not hostIDs, so it is possible for one application to load add-ins based on templates registered under different hostIDs so long as the entry point type for the add-in can be resolved in the HostItemProvider. The add-ins are created based templates using the same proxy and entry point, but the templates are registered under different hostID's.

IDE and template considerations for this scenario- Each hostID should use a different ProjectTemplatesLocations because the VSTA IDE is HostID specific; therefore, projects for HostID_A cannot be opened in the IDE for HostID_B. Also, a host application can only register as a debug host for one hostID at a time; multiple IDE's for different HostIDs cannot be displayed or managed by the same application concurrently.

Scenario 6) 1 Host Application, Multiple HostID, Multiple Proxies, Multiple Entry Point:
This complex setup is very similar to the fifth scenario, but using different multiple proxies and entry points like the fourth scenario. Each hostID has its own templates which could be very similar, for example having the hostID as the only difference, or very different, for example using different proxies and entry point combinations. The host application loads add-ins written against different proxies and entry points based on templates registered under different hostIDs. The HostItemProvider would determine which entry point type to return based on the entry point type of the add-in. Add-ins are loaded based on entry point types, not hostIDs, so it is possible for one application to load add-ins based on templates registered under different hostIDs so long as the entry point type for the add-in can be resolved in the HostItemProvider. The add-ins are created based templates using different proxy / entry point combinations and registered under different hostIDs.

Error when a project based on a different hostID is opened in ShapeAppCSharp's IDE:

Scenario 7) Multiple Host Applications, 1 HostID, 1 Proxy, 1 Entry Point:
This is a simple scenario which can be used by applications which share base types, including the base type which will be an entry point type (for example two applications which use the same Document type as the entry point). The host applications load add-ins which are all written against the same proxy using the same entry point. The HostItemProvider for this scenario is very simple because there is only one type to return. The add-ins are created based templates using the same hostID, proxy, and entry point. Multiple templates using the same entry point may be used, for example one template could be the "bare bones" variety generated by ProjectGen and another could be more robust including events already hooked up.

IDE and template considerations for this scenario- Multiple applications can concurrently display, manage, and debug IDE's for the same hostID (ex: run two instances of the ShapeAppMacroRecordingCSharp sample at the same time). Therefore, applications can share a hostID without "locking" the other application out of debugging.

Because both applications use the same HostID, they will share the same IDE and registry settings like ProjectTemplatesLocation, AppName, and UserFilesFolderName. Therefore, the IDE cannot be customized through the default settings file to be different for each host application. Also, all templates for the hostID will appear as choices in the IDE. It is possible to refine this by storing the templates in subfolders under the ProjectTemplatesLocation. For example the ProjectTemplatesLocation could be C:\MyApp\Templates with the sub folders VisualBasic and CSharp, and within these folders the template could be divided in folders like C:\MyApp\Templates\{VisualBasic, CSharp}\{App_A, App_B}; the templates would appear as choices under the sub folders.

Project template storage and new project pane for templates stored as described above:

Monitoring and Controlling the IDE- Catching the File.Exit and other events

Melody — Thu, 13 Nov 2008 20:35:00 GMT

You may wish to monitor a user’s actions in the IDE and respond to or cancel them. I found a great article and sample which shows how to catch any and all events. One common request that this could be used to address is responding to the user exiting out of the IDE.

When the IDE is launched from the host, exiting the IDE really hides it instead of closing it, leaving the vsta.exe process running, and the user is not prompted to save changes. Below is some code added to the ShapeAppMacroRecordingCSharp sample which catches the File.Exit event, prompts the user to save the project, and quits the IDE bringing down the vsta.exe process. An additional method is also included which catches all events, this is very useful for determining the GUID and ID of a specific event you are interested in.

This workaround is based on an article by Carlos J. Quintero, HOWTO: Capturing commands events from Visual Studio .NET add-ins and a sample from CodeProject, Add-in to attach ASP.NET debugger.

private void EnsureIDE()
{ /*unchanged code omitted*/

//get and subscribe to all events prior to execution
EnvDTE.CommandEvents commandEvents = dte.Events.get_CommandEvents("{00000000-0000-0000-0000-000000000000}", 0);

commandEvents.BeforeExecute += new EnvDTE._dispCommandEvents_BeforeExecuteEventHandler(commandEvents_BeforeExecute);

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

void exitCommand_BeforeExecute(string Guid, int ID, object CustomIn, object CustomOut, ref bool CancelDefault)
{
   //Project.IsDirty is always false, so use .Saved which starts true
   if (this.macroProject.Saved == true)
   {
      //prompt the user to save the project
      DialogResult answer = MessageBox.Show("Do you want to save changes to " + this.macroProject.Name + "?", "ShapeAppCSharp", MessageBoxButtons.YesNo);

      if (answer == DialogResult.Yes)
      {
         this.macroProject.Save(null);
      }

     //change the saved state
      this.macroProject.Saved = false;
   }

//quit the IDE
this.dte.Quit();
}

void commandEvents_BeforeExecute(string Guid, int ID, object CustomIn, object CustomOut, ref bool CancelDefault)
{
EnvDTE.Command objCommand = default(EnvDTE.Command);
string sCommandName = null;

//break here to check out any commands you are interested in
objCommand = dte.Commands.Item(Guid, ID);

   if ((objCommand != null))
   {
      sCommandName = objCommand.Name;

      if (sCommandName.Equals("Something.WorthWatching"))
      {
         //do something
      }
   }
}

Visual Basic:

AddHandler Me.mDTE.Events.CommandEvents("{5EFC7975-14BC-11CF-9B2B-00AA00573819}", 229).BeforeExecute, AddressOf exitCommand_BeforeExecute

Private Sub exitCommand_BeforeExecute(ByVal Guid As String, ByVal ID As Integer, ByVal CustomIn As Object, ByVal CustomOut As Object, ByRef CancelDefault As Boolean)

'Project.IsDirty is alwyas false, so use .Saved which starts true

If Me.macroProject.Saved Then

'prompt the user to save the project

Dim answer As System.Windows.Forms.DialogResult = System.Windows.Forms.MessageBox.Show("Do you want to save changes to " + Me.macroProject.Name + "?", HostId, System.Windows.Forms.MessageBoxButtons.YesNo)

If answer = System.Windows.Forms.DialogResult.Yes Then

Me.macroProject.Save(Nothing)

End If

'change the saved state

Me.macroProject.Saved = False

End If

'quit the IDE

Me.mDTE.Quit()

End Sub