Recently, a forum poster asked us how he could add a submenu item to a built-in menu item in Outlook.  Note that these are not controls that appear on the Ribbon of an Outlook item, but rather the menus that drop down from the top of the Outlook Explorer such as the View menu and the Tools menu.

So one way to do this (In fact the only way that I know of) is to use the example shown in the following MSDN topic - How to: Add Custom Menus and Menu Items to Outlook.

You can’t just use the example as is. You will need to add a line of code to get a handle to a built-in menu. The following example gets a handle to the Junk E-Mail menu that appears off of the Actions menu of the Outlook Explorer window.

Office.CommandBarPopup junkEmailMenu = (Office.CommandBarPopup)
    this.Application.ActiveExplorer().CommandBars.FindControl
    (Office.MsoControlType.msoControlPopup, 31353, missing, missing);

Note the ID number shown in the second parameter to the FindControl method. How on earth did I know that the Junk E-Mail menu is the 31353 menu?  The answer is … Not very easily. In fact to obtain that ID, I wrote a small Outlook add-in that iterates through all menus in Outlook and prints out their corresponding codes.  I figured that I would share this with you in case you ever have a similar scenario.

Two notes about the sample below: First - this is a C# example, so my apologies to VB’ers. Second - this example is meant to be used in a Visual Studio 2008 Outlook (2007 or 2003) add-in project.  These projects automatically include the appropriate using statements that enable you to use the prefix “Office” in place of “Microsoft.Office.Core” when referring to some objects etc.

Ok. Here is the code:

public partial class ThisAddIn
{
    private void ThisAddIn_Startup(object sender, System.EventArgs e)
    {
        Outlook.Application app = this.Application;
        //Create a new txt file to record controls' list

        System.IO.StreamWriter sw = System.IO.File.CreateText
            (@"C:\Outlook Menus.txt");

        //loop through Outlook ActiveExplorer CommandBars to get all CommandBars

        foreach (Office.CommandBarControl cb in app.ActiveExplorer().CommandBars.ActiveMenuBar.Controls)
        {
            PrintMenuItems(cb, sw);
        }

        sw.Close();

    }

    // Recursive method for printing menus and nested menus.
    // Either the menu is a commandbarpopup (contains submenus)
    // Or it is a commandbarbutton (contains no submenus)

    private void PrintMenuItems(object menuItem, System.IO.StreamWriter sw)
    {
        if (menuItem as Office.CommandBarButton == null)
        {
            // This is a menu bar popup control.
            sw.WriteLine((menuItem as Office.CommandBarPopup).Caption +
                "\t" + (menuItem as Office.CommandBarPopup).Id.ToString());

            if ((menuItem as Office.CommandBarPopup).accChildCount > 0)
            {
                for (int j = 1; j <= (menuItem as Office.CommandBarPopup).accChildCount; j++)
                {
                    PrintMenuItems((menuItem as Office.CommandBarPopup).get_accChild(j), sw);
                }
            }
        }
        else
        {
            // Must be a command
            sw.WriteLine("\t" + (menuItem as Office.CommandBarControl).Caption +
                "\t" + (menuItem as Office.CommandBarControl).Id.ToString());
        }

    }

Enjoy!

Norm E.

ClickOnce manifest signing can be a little confusing for someone going through the process the very first time. This is probably because it involves signing multiple files in a particular sequence. Once you understand the process conceptually it becomes fairly easy to follow. In this post, I hope to provide a quick summary of the important thingsyou need to know about manifests and this signing/resigning business.

Let’s start with some background info in case you missed it:

What are these manifests I speak of?

Any application deployed through ClickOnce will have two manifests: a deployment manifest and an application manifest.

Depending on the type of application, the deployment manifest can have the following file extensions:

.application – for any executable application like a Winforms or WPF application

.vsto – for a VSTO based Office customization solutions (which this blog is all about)

.xbap – for a Browser Hosted WPF application

An application manifest will always have the .manifest extension. For example:

.exe.manifest – for any executable including Winforms, WPF and Browser Hosted WPF applications.

.dll.manifest – for VSTO based office customizations.

MSDN has documentation that describes these files and their use in detail but for a one line summary – think of these as “Setup Authoring” for your application that tells the application how to install, update, what the application is called etc.

ClickOnce Application Manifest

ClickOnce Deployment Manifest

Application Manifests for Office Solutions (2007 System)

So why do manifests have to be signed?

The ClickOnce “trust model” is based on signing the ClickOnce manifests with a Certificate. By “trust model,” I mean the process by which ClickOnce and the end user can decide whether to trust an application and allow it to install or not. To sign an application, you need a Certificate - Visual Studio will generate a temporary certificate for you when you publish an application (like MyApplication_Temporary.pfx) and also sign the manifests for you. You can also choose to sign the manifests with a code-signing certificate that you can obtain from a Root Certificate Authority.

These MSDN articles go into details about the certificates and how they are used:

ClickOnce Deployment and Authenticode

Signing ClickOnce Manifests

Starting with .NET 3.5 SP1, signing has become optional for any .exe-based application. So Winforms/WPF/Console applications deployed via Clickonce no longer need to be signed. The downside of course is that there are no guarantees on the integrity of the application. The developer has to make the choice between the tradeoff of securing the application and going through the signing process vs not signing the application at all and relying on some other means of ensuring the application has not being compromised.

Note that VSTO solutions still require that the manifests be signed. Most VSTO scenarios are in the enterprise where best practices require signing of applications. Also since VSTO solutions always run full trust there is a higher risk associated with making signing optional.

Why do they need to be re-signed?

Visual Studio is capable of generating signed manifests. Why get into this whole re-signing business? Re-signing is needed when you are in a situation where you want to change something about the application after it has already been published – and you want to do so without re-building or re-publishing the application from Visual Studio.  You may want to simply sign the application with a different certificate without re-building the application, for example you test the application with a self created test certificate but when you deploy the application to end users it is signed with a code-signing certificate issued by a Certificate Authority. Some of the most common examples that re-quire re-signing are when you want to change a particular file that is part of your application like the .config file, or maybe a simple resource/data file that is deployed along with your application.

The ClickOnce manifests contain hashes to all the files that are being deployed as part of the application. If any of the files change, then the hash for that file breaks and the signing becomes invalid. So you cannot simply replace an individual file in a ClickOnce package without breaking the signing. You will have to update and re-sign the manifests if you want to update a file.

The following figures should help illustrate this better.

A typical ClickOnce deployment package consists of

· Deployment Manifest

· Application Manifest

· Application Files – the exe and dlls associated with the application.

The deployment manifest links to the application manifest along with the hash of the application manifest, so if the application manifest changes the hash will no longer be valid. Similarly the Application manifest links to all the application files along with their hashes.

So consider the situation where one of the application files say the .config file in this case changes after the app has been published.

Since the .config file changed the hash in the Application Manifest will not match up to the new file anymore. Trying to install the application in this state will fail (unless you are using optional signing and hashing of course).

You will have to update and re-sign the application manifest in order to get the deployment to work again.

You can do this using the following mage commandline:

Start the Visual Studio command prompt. Locate the application manifest folder. Typically under “%Publish Folder%\Application Files\MyApplication_Version\Myapplication.exe.manifest”

Use the –update option for the mage command line.

> mage –update Myapplication.exe.manifest –certfile mycert.pfx

The update command will update all the file hashes defined in the application manifest to match those of the files located next to it. For other options on how to use update see MSDN: Manifest Generation and Editing Tool (Mage)

Note: While update the application, you might see some errors about Files not found. This could happen if you using the .deploy extensions for you application files. To avoid this, you must rename the .deploy extensions back to their original extensions and then run the update command with mage. Once you have update the application manifest, you must rename the application files back with he .deploy extension.

Once you have updated the application manifest with mage, all the files it refers to will have the correct hashes. However at this point since the application manifest itself is updated, the hash to the application manifest contained within the deployment manifest will no longer match.

To fix this the deployment manifest needs to be updated with the hash of the new application manifest and re-signed.

The mage command line to do this:

> mage.exe –update Myapplication.application –appmanifest “Application Files\MyApplication_%Version%\Myapplication.exe.manifest” –certfile mycert.pfx

At this point, all the hashes to all the files have been updated and both manifests have been re-signed. So the application is ready to be installed on the end users’ machine without re-building or re-publishing from Visual Studio.

In the above example I chose to show how the resigning process is done through the Mage command line tool. The same process can be done through the MAGEUI tool which provides a GUI for the manifest editing. For simply re-signing your manifests I have always preferred to use the command line. The re-signing process itself can be straightforward once you understand the need for it. Most users forget to either update or sign both manifests and I hope this post illustrates the chaining dependency and why both manifests need to be updated.

Last month I posted this article that described how to prevent your add-in from creating duplicate menu items in Word.  If you have been experimenting with customization contexts, you might have several menu items that appear when you right click a document. The article that I posted shows how to prevent this from happening for your users, but what about removing the items that appear in your instance of Word – the one that you use for testing?

To clear those off, just add a bit of code to the startup event handler of any old Word add-in.  Set the customization context to each possible culprit (template, document, attached template etc.) and then call the Reset method. Be sure to save the template or document after words. 

Note - I wouldn’t recommend that you put this code into an add-in that you send out to users as this code will remove all customizations in each context (Even ones that your add-in has not created!).  However, it is a cool way to clear up left over menu items from the instance of Word that you use for testing.

private void ResetShortcutMenu()
{
    myApplication.CustomizationContext = myApplication.ActiveDocument;

    myApplication.CommandBars["Text"].Reset();
    myApplication.ActiveDocument.Save();

    myApplication.CustomizationContext = myApplication.ActiveDocument.get_AttachedTemplate();

    myApplication.CommandBars["Text"].Reset();
    ((Word.Template)myApplication.ActiveDocument.get_AttachedTemplate()).Save();

    myApplication.CustomizationContext = customTemplate;

    myApplication.CommandBars["Text"].Reset();
    customTemplate.Save();

    myApplication.CustomizationContext = myApplication.NormalTemplate;

    myApplication.CommandBars["Text"].Reset();
    myApplication.NormalTemplate.Save();
}

I just posted another interview on Channel 9. I sit down again with Saurabh Bhatia, a Program Manager on the Office Client team, who is responsible for the ClickOnce publishing functionality in Visual Studio. We chat about trust issues and certificates and he sets me straight on how ClickOnce deployment and application manifests work. He then shows how to resign them outside of Visual Studio using a tool called Mage. This is really handy for folks that need to modify the files within a deployment package, like the application settings (app.config) file, but don't have Visual Studio installed.

Channel 9: Resigning ClickOnce Application and Deployment Manifests with MAGE

Saurabh draws on the whiteboard in this one and since I'm a one (wo)man show I couldn't jump up and zoom in so I redrew it for you all here.

Links from the show:

• Mage
• Office Client (VSTO) Team blog (you are here ;-))
VSTO Developer Center

Enjoy,
-Beth Massi, Visual Studio Community

The latest .NET Rocks! TV video includes an interview with Beth Massi where she shows how to use the VSTO Power Tools!  Also, she introduces some other minor features that you may have heard of: Open XML SDK and LINQ.

Check out Beth’s summary of the video and her demo at her blog: dnrTV: Showing off the Open XML SDK and LINQ.

Mary Lee, Programming Writer.

I thought you Outlook developers would like to read about the future of Exchange on their team blog.  Enjoy!

Thanks to Maarten van Stam for pointing this great article out to me in his Facebook status. 

-Christin Boyd