Office Development with Visual Studio

VSTO Developer Center is now part of the Office Developer Center

VSTOTeam — Tue, 02 Aug 2011 17:35:11 GMT

In order to provide a more integrated experience for folks building custom solutions on the Office platform, we’ve merged the content from the VSTO Developer Center into the Office Developer Center. You’ll still find great learning content there including:

Getting Started with Office Development with Visual Studio (VSTO)

Excel Solutions

Write code to work with data and customize the user interface.

Outlook Solutions

Work with objects and data and customize the Outlook user interface.

Word Solutions

Manipulate documents, work with data, and customize the Word user interface.

Deploying Office Solutions

Learn to deploy Office customizations built with Visual Studio.

Happy Learning!
- The VSTO Team

Migrating VSTO 2005/2008 InfoPath Projects to InfoPath 2010

VSTOTeam — Fri, 22 Apr 2011 15:54:29 GMT

If you missed it, last week the InfoPath team posted about how to migrate your InfoPath projects from Visual Studio Tools for Office 2005 or Visual Studio Tools for Office 2008 (VSTO) into InfoPath 2010 using Visual Studio Tools for Applications (VSTA).

Check it out here: Working with VSTO 2008 Projects in InfoPath 2010

The Phases of the ClickOnce Trust Prompt (Mary Lee)

VSTOTeam — Tue, 11 Jan 2011 17:37:59 GMT

Signing your Office solutions with a certificate is a mandatory step, but there are several optional steps that can change the way the certificate is presented to the end user or customer.

This example uses a Visual Studio generated test certificate, but the dialog box is similar to what you would see if you are using a purchased code-signing certificate. These steps are listed in the How to: Add a Trusted Publisher to a Client Computer for ClickOnce Applications topic in the MSDN Library and assumes that the ClickOnce Trust Prompt and inclusion list are enabled as outlined in How to: Configure Inclusion List Security

Phase 1. If the certificate used to sign the Office solution is not added to the Root or the TrustedPublisher stores, the Publisher is shown as Unknown Publisher and there is a yellow shield presented in the Microsoft Office Customization Installer dialog box.

Phase 2. If the certificate used to sign the Office solution is in the Root store, but not the Trusted Publisher list, the Publisher is shown as Redmond\marylee and there is a green shield.

The step used to add the certificate to the Root store is the following: certmgr.exe -add good.cer -c -s -r localMachine Root

Phase 3. If the certificate used to sign the add-in is in the Root list and the Trusted Publisher list, you only see that the add-in was installed successfully.

The step used to add the certificate to the TrustedPublisher store is the following: certmgr.exe -add good.cer -c -s -r localMachine TrustedPublisher

If you have questions, visit the VSTO forum to search for answers or post new questions.

Mary Lee, Programming Writer.

Performance Improvements Coming Soon to a Service Pack Near You (Stephen Peters)

VSTOTeam — Tue, 30 Nov 2010 19:08:00 GMT

With the SP1 work winding down, I thought that I’d take a moment and discuss three new performance improvements that are going into VSTO for SP1. We have listened to your feedback and understand that startup time is a major issue, and so we have focused on attempts to make the VSTO runtime load faster.

In this article, I will be delving into these features and how you can take advantage of them. The most important feature is Fast Path loading, which is a loading path for the runtime which is as fast and as lean as possible. In addition, we updated the form region and ribbon discovery process so reflection is not required in most cases. Plus, I will also share a few of the numbers we gathered during this effort so that you can get a before and after picture.

VSTO Fast Path

The Fast Path is a new way to load and launch VSTO addins that is much faster than the current launch path. However, it achieves this speed by bypassing a few of the steps that would normally happen during addin launch. The following conditions must be met in order to use the fast path:

The addin (or document) manifest must be installed under %ProgramFiles% or %ProgramW6432%.
The addin must be registered as |vstolocal in the registry.

When the fast path is in use, the following steps will be skipped:

Schema validation on the manifests
Any automatic update checking
Security checks – the digital signatures of the manifests will not be validated.

Notice that the requirement that the add-in is deployed into the secure location on the user machine allows us to relax the security verifications done at runtime without compromising the security of the machine. Relaxing these expensive checks is what contributed the most to the improvements in startup time.

In order to take advantage of Fast Path loading, an addin has to be deployed via an MSI. As a consequence, these addins also will not be able to automatically check for updates.

Ribbon Aware Manifests

As mentioned in a previous blog post, VSTO reflects over the addin assembly in order to find Ribbon extensions. On particularly large assemblies, this can be quite time consuming. While there have been manual workarounds for this behavior in the past, we are now including Ribbon extension types directly into the VSTO manifest. If there are no Ribbon extensions, then an empty list is placed in the manifest, which will tell the VSTO runtime that reflection is not necessary.

In order to take advantage of this improvement, the addin must be built (or rebuilt) with Visual Studio 10.0 SP1, and the addin must be loaded with the SP1 version of the VSTO Runtime. The addin must also be targeting .Net 4.0. If you attempt to load an SP1 addin with a RTM runtime, or if you load an RTM addin with the SP1 runtime, all of the ribbon objects will still be discovered and loaded; the runtime will just have to use reflection to find them.

Of course, if your code already overrides CreateRibbonObjects or CreateRibbonExtensibilityObject as mentioned in the above blog entry, then this optimization does not apply to you. The reason why this was implemented is because many people are not aware of this optimization, and we want to ensure that we are as performant as possible by default with as little manual optimization as possible.

To better visualize the new ribbon xml, here are two examples of its intended use:

<vstov4:appAddIn application="Excel" loadBehavior="3" keyName="ExcelAddIn14">
  <vstov4:friendlyName>ExcelAddIn14</vstov4:friendlyName>
  <vstov4:description>ExcelAddIn14</vstov4:description>
  <vstov4.1:ribbonTypes xmlns:vstov4.1="urn:schemas-microsoft-com:vsto.v4.1">
    <vstov4.1:ribbonType name="ExcelAddIn14.Ribbon1, ExcelAddIn14, 
        Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  </vstov4.1:ribbonTypes>
</vstov4:appAddIn>

That addin had one ribbon type, and the class is called ExcelAddIn14.Ribbon1, and it is part of the ExcelAddIn14.dll assembly.

Here is one with no ribbons:

<vstov4:appAddIn application="Excel" loadBehavior="3" keyName="ExcelAddIn15">
  <vstov4:friendlyName>ExcelAddIn15</vstov4:friendlyName>
  <vstov4:description>ExcelAddIn15</vstov4:description>
  <vstov4.1:ribbonTypes xmlns:vstov4.1="urn:schemas-microsoft-com:vsto.v4.1" />
</vstov4:appAddIn>

The empty ribbonTypes list serves to tell the SP1 runtime that doing the reflection is unnecessary. This will save a lot of time during VSTO startup.

VSTO Form Region discovery

When loading an Outlook addin that has Form Regions, the VSTO Runtime uses reflection to discover Form Region factories and match them up with Form Regions registered with the addin. This had the potential to inflict a serious performance hit, especially if the addin assembly contained a lot of different types.

To eliminate this performance hit, the name of the factory is now being included in the addin manifest. Now when Outlook requests the factory from the addin, the addin knows immediately which class to instantiate and doesn’t need to reflect over every type in the assembly to find the appropriate class. If you look in the new SP1 manifest, you can see the new information:

<vstov4:formRegion 
    name="Outlook_OFR_MSI.EmptyFormRegion" 
    vstov4.1:class="Outlook_OFR_MSI.EmptyFormRegion+EmptyFormRegionFactory" 
    xmlns:vstov4.1="urn:schemas-microsoft-com:vsto.v4.1">

Like the Ribbon aware manifest above, the SP1 runtime is capable of loading an addin with Form Regions that was built with the RTM version of VS, and the RTM runtime can load an SP1 addin. You just won’t be able to take advantage of this improvement.

Numbers

Below are some of the numbers that we tracked on startup time during this effort. These numbers were collected on a machine in a ‘cold’ state (everything in memory flushed out to disk, superfetch disabled) in order to give us the most consistent results during our work. In addition, there are no other applications running at the time that Outlook was launched, and all addins except for the one that we were testing was disabled.

There four startup times of interest are as follows:

Outlook application baseline – an empty mail account, no addins loaded
Outlook simple addin – a simple .Net 4.0 addin. In SP1, it would take advantage of the fastpath as well as the ribbon improvements (since the VSTO runtime was no longer looking for Ribbons)
Outlook Ribbon addin – this is similar to the above one, only now we see the time it takes to instantiate a simple Ribbon extension.
Outlook WPF Form Region – this is the simple addin plus the time to load (but not show) a Form Region with a WPF control on it. This takes advantage of all of the improvements listed in this article.

	Outlook + VSTO RTM		Outlook + VSTO SP1		Improvement
Scenario	Time	%	Time	%	% of App baseline
Outlook application baseline	3762	100.00%	3762	100.00%	N/A
Outlook simple addin	10215	271.53%	7952	211.38%	60%
Outlook Ribbon addin	10973	291.68%	8424	223.92%	68%
Outlook WPF Form Region	12231	325.12%	8192	217.76%	107%

As you can see, there are many performance improvements to the VSTO Runtime coming in Visual Studio 2010 SP1. Not only that, but many tweaks that used to require extra work (such as working around Ribbon reflection) are now available out of the box with no interaction on the user’s part. This will help you deliver VSTO addins that are faster to your end-users.

UPDATE: Visual Studio SP1 Beta is now available!

Microsoft Help Viewer 1.1 - Updates Planned for Visual Studio 2010 SP1 (Kathleen McGrath)

VSTOTeam — Wed, 03 Nov 2010 23:37:01 GMT

Paul O’Rear, a Program Manager on the Library Experience team, describes the changes to the Microsoft Help Viewer planned for Visual Studio 2010 SP1. He demonstrates the new functionality of the viewer in an early build of Help Viewer 1.1.

See Microsoft Help Viewer – Updates Planned for Visual Studio 2010 SP1

You can learn more in The Story of Help in Visual Studio 2010

--Kathleen

Installing Office 2007/VSTO 3.0 Solutions on Computers with Office 2010 (Mary Lee)

VSTOTeam — Wed, 06 Oct 2010 00:35:17 GMT

You have probably been reading and hearing about Microsoft Office 2010 for some months. Now, you may be wondering how much work is necessary to install your existing Office 2007/VSTO 3.0 solutions on customer computers that have Office 2010. Perhaps you’re thinking about migrating the Windows Installer Setup projects or ClickOnce deploymen projects? The answer is that you don’t need to change anything. If you have Office 2007 add-ins that were created for the VSTO 3.0 runtime, the registry keys for Office 2010 add-ins created for the VSTO 2010 runtime are exactly the same. For Office 2007 document-level projects, the custom document properties are also the same in Office 2010. The same deployment project used to install Office 2007 solutions should work on Office 2010 as well.

In fact, deployment becomes even easier for two reasons: fewer prerequisites to include and fewer custom actions to run.

Less need to deploy the VSTO runtime. The VSTO 2010 runtime with the .NET Framework 3.5 extensions is already included in Microsoft Office 2010. For more information, see http://blogs.msdn.com/b/vsto/archive/2010/05/13/when-do-i-need-to-deploy-the-vsto-runtime.aspx.
Less need for the inclusion list. VSTO add-ins installed to the Program Files directory are considered trusted without creating an inclusion list entry for each solution and each user. For more information, see http://blogs.msdn.com/b/vsto/archive/2010/03/10/changes-in-the-security-model-for-office-solutions.aspx.

MSDN Library resources include the following topics:

If you have any questions, search for answers or post questions in the Visual Studio Tools for Office forum at http://social.msdn.microsoft.com/Forums/en-US/vsto/threads.

Mary Lee, Programming Writer.

Office 2010 PIA BootStrapper Released (Beth Massi, Lily Ma)

VSTOTeam — Sat, 11 Sep 2010 00:26:59 GMT

Today we released the Microsoft Office 2010 Primary Interop Assemblies (PIA) Bootstrapper Installer which adds the Microsoft Office 2010 Primary Interop Assemblies to the Prerequisites Dialog Box in Visual Studio 2010 or Visual Studio 2008. Then when you deploy with ClickOnce or Windows Installer, you can select this option to deploy the Microsoft Office 2010 PIAs to end-user computers.

Download it here: Microsoft Office 2010 Primary Interop Assemblies (PIA) Bootstrapper Installer

Make sure to read the instructions on the download page in order to properly set up the bootstrapper to appear in Visual Studio. Now when you create Office 2010 solutions with Visual Studio 2010 you can select to deploy this prerequisite component with your solution to your end users.

For more information on developing Office solutions with Visual Studio please visit the Office Development with Visual Studio Developer Center.

Enjoy,
-Beth Massi, Visual Studio Community

Deploying Microsoft Office Solutions by Using Visual Studio 2010 and Windows Installer (Mary Lee, Saurabh Bhatia)

VSTOTeam — Thu, 19 Aug 2010 18:25:57 GMT

In Visual Studio 2010, you can use the ClickOnce and Windows Installer deployment technologies to deploy Office solutions that target both Microsoft Office 2007 and Microsoft Office 2010. The main advantage of using Windows Installer to deploy your Office solutions is to install application-level add-ins to AllUsers, rather than the current user only.

There are detailed steps for creating a Windows Installer (.msi) file for Office 2007 and Office 2010 solutions at http://msdn.microsoft.com/en-us/vsto/ff937654.aspx and code samples at http://code.msdn.microsoft.com/VSTO2010MSI.

For information about the registry keys for deploying to AllUsers, see http://msdn.microsoft.com/en-us/library/bb386106.aspx.

For developers using Windows Installer XML, there is some useful information at http://stackoverflow.com/questions/532447/how-do-you-use-wix-to-deploy-vsto-3-0-addins. The steps are similar for Office solutions in Visual Studio 2010.

If you have any questions about the steps, search for answers or post questions in the Visual Studio Tools for Office forum at http://social.msdn.microsoft.com/Forums/en-US/vsto/threads.

Mary Lee, Programming Writer.

Saurabh Bhatia, Program Manager.

Channel 9 Interview: Office Add-in (VSTO) Performance Tips & Tricks (Beth Massi, Stephen Peters)

VSTOTeam — Thu, 24 Jun 2010 16:33:00 GMT

In this interview, I sit down with Stephen Peters, a developer on the Office client tools team in Visual Studio. Steve shows us a couple of tricks for how you can squeeze the best performance out of Office solutions built with Visual Studio (VSTO). He also shows how to finely control the way your custom ribbons load, as well as how to eliminate references to the Utilities assembly. Check it out:

Channel 9 Interview: Office Add-in (VSTO) Performance Tips & Tricks

For more information, see his blog post:
VSTO Performance: Ribbon Reflection

Enjoy,
-Beth Massi, Visual Studio Community

Sharing a Ribbon Customization Between Office Projects in Visual Studio 2010 (McLean Schofield)

VSTOTeam — Wed, 23 Jun 2010 18:49:37 GMT

A customer on the VSTO forums recently noticed that the steps we blogged about for sharing a single Ribbon customization between multiple projects in Visual Studio 2008 no longer works in Visual Studio 2010. When following the instructions in the blog post, you get an error when you try to open the Ribbon code file in the class library project. This is because of some changes to the way the Ribbon designer was implemented in Visual Studio 2010. The upshot is that you can no longer open the Ribbon designer outside of Office projects. In addition, because Office projects that target the .NET Framework 4 have a different programming model in Visual Studio 2010, the instructions in the old blog post will also result in other errors in projects that target the .NET Framework 4.

This blog post tells you how to share a single Ribbon customization (created by using the Ribbon designer) between multiple Office projects in Visual Studio 2010. Disclaimer – what I am about to show you in this blog post is not supported, and has not been officially tested by the product team in any way.

Targeting the .NET Framework 3.5

If your Office projects target the .NET Framework 3.5, then the instructions in the old blog post still apply, with just one change. Rather than design your Ribbon customization in the class library project, now you must design it in an Office project, because of the change to the implementation of the Ribbon designer noted above. Here are the modified instructions.

In Visual Studio, open (or create) an Office project that targets the .NET Framework 3.5, and that targets an Office application that supports the Ribbon.
Add a Ribbon (Visual Designer) item to the project.
Design your Ribbon customization. Be sure to set the Modifiers property to Public for any controls/tabs/groups that you want to be able to access in other Office projects. Also be sure to set the RibbonType property of the Ribbon to all Ribbon types you want to support in other Office projects that consume the shared Ribbon. For example, if you want to use the Ribbon customization in Excel and Word projects, set RibbonType to Microsoft.Excel.Workbook and Microsoft.Word.Document.
Save your changes.
Create a class library project that targets the .NET Framework 3.5. Add the following reference:
- Microsoft.Office.Tools.Common.v9.0
Add the existing Ribbon code file to the class library project. The code-behind file (for example, Ribbon1.Designer.cs) will be copied over automatically.
Optionally, open the Ribbon file and the code-behind file in the editor and change the namespaces for the Ribbon class in the main Ribbon file and code-behind file (for example, to SharedRibbonLibrary or some other namespace that identifies your component). Be sure to open the files in the editor by right-clicking them and choosing View Code. Do not double-click the files; this will attempt to open the Ribbon designer, and will result in a designer error.
Build the class library project.
In a new/different Office project that targets the .NET Framework 3.5, add a reference to the class library project.

In the ThisAddIn, ThisDocument, or ThisWorkbook class in the Office project, override CreateRibbonObjects as follows (the following code assumes you changed the namespace of the shared Ribbon to SharedRibbonLibrary).

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new Microsoft.Office.Tools.Ribbon.RibbonManager(
        new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] { 
            new SharedRibbonLibrary.Ribbon1() });
}

Add the following class to the project. This code lets you access the shared Ribbon customization by using Globals.Ribbons in your code.

partial class ThisRibbonCollection : Microsoft.Office.Tools.Ribbon.RibbonReadOnlyCollection
{
    internal SharedRibbonLibrary.Ribbon1 Ribbon1
    {
        get { return this.GetRibbon<SharedRibbonLibrary.Ribbon1>(); }
    }
}

Now you can use Globals.Ribbons.Ribbon1 to access public items exposed by the shared Ribbon. For example:

private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    Globals.Ribbons.Ribbon1.button1.Click += new EventHandler<Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs>(button1_Click);
}

void button1_Click(object sender, Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs e)
{
    System.Windows.Forms.MessageBox.Show("it works!");
}

Targeting the .NET Framework 4

If your Office projects target the .NET Framework 4, you’ll need to make a number of other changes to the Ribbon code. Here are the full instructions.

In Visual Studio, open (or create) an Office project that targets the .NET Framework 4, and that targets an Office application that supports the Ribbon.
Add a Ribbon (Visual Designer) item to the project.
Design your Ribbon customization. Be sure to set the Modifiers property to Public for any controls/tabs/groups that you want to be able to access in other Office projects. Also be sure to set the RibbonType property of the Ribbon to all Ribbon types you want to support in other Office projects that consume the shared Ribbon. For example, if you want to use the Ribbon customization in Excel and Word projects, set RibbonType to Microsoft.Excel.Workbook and Microsoft.Word.Document.
Save your changes.
Create a class library project that targets the .NET Framework 4. Add the following references:
- Microsoft.Office.Tools
- Microsoft.Office.Tools.Common
- Microsoft.Office.Tools.Common.v4.0.Utilities
Add the existing Ribbon code file to the class library project. The code-behind file (for example, Ribbon1.Designer.cs) will be copied over automatically.
Open the Ribbon file and code-behind file in the code editor by right-clicking them and choosing View Code. Do not double-click the files; this will attempt to open the Ribbon designer, and will result in a designer error.

In the Ribbon code-behind file, change the constructor to the following.

public Ribbon1(Microsoft.Office.Tools.Ribbon.RibbonFactory factory)

    : base(factory)

{

    InitializeComponent();

}

In Ribbon code-behind file, remove the ThisRibbonCollection class definition at the bottom of the file.
Optionally, change the namespaces for the Ribbon class in the main Ribbon file and code-behind file (for example, to SharedRibbonLibrary or some other namespace that identifies your component).
Build the class library project.
In a new/different Office project that targets the .NET Framework 4, add a reference to the class library project.

protected override Microsoft.Office.Tools.Ribbon.IRibbonExtension[] CreateRibbonObjects()

{

    return new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { new        

        SharedRibbonLibrary.Ribbon1(Globals.Factory.GetRibbonFactory()) };

}

Add the following class to the project. This code lets you access the shared Ribbon customization by using Globals.Ribbons in your code.

partial class ThisRibbonCollection : Microsoft.Office.Tools.Ribbon.RibbonReadOnlyCollection

{

    internal SharedRibbonLibrary.Ribbon1 Ribbon1

    {

        get { return this.GetRibbon<SharedRibbonLibrary.Ribbon1>(); }

    }

}

Now you can use Globals.Ribbons.Ribbon1 to access public items exposed by the shared Ribbon. For example:

private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    Globals.Ribbons.Ribbon1.button1.Click += new Microsoft.Office.Tools.Ribbon.RibbonControlEventHandler(button1_Click);
}

void button1_Click(object sender, Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs e)
{
    System.Windows.Forms.MessageBox.Show("it works!");
}

Open XML Package Editor Power Tool for Visual Studio 2010 (Navneet Gupta)

VSTOTeam — Tue, 22 Jun 2010 19:20:00 GMT

We are happy to announce that today we are releasing the Open XML Package Editor Power Tool for Visual Studio 2010 on Visual Studio Gallery. This Power Tool is a Visual Studio add-in that provides an easy way to parse and edit Open Packaging Conventions files, including Word, Excel and PowerPoint documents. This Power Tool enables you to do the following tasks:

Open any Open XML Package file or XPS Package file directly in Visual Studio 2010.
Browse the contents of Package files in a tree view.
Open any XML part directly in Visual Studio's rich XML editor.
Add or remove parts and relationships directly in the user interface.
Import and export part contents to and from files.
Detect when a Package file that is opened in Visual Studio is modified externally. The Power Tool prompts user to reload the file without having to close any open XML part editors.
Create new Office Packages from a set of templates using Visual Studio's File > New dialog.

This Power Tool was originally shipped for Visual Studio 2008 as part of VSTO Power Tools v1.0.0.0. This new version for Visual Studio 2010 contains all the original features from the previous version and it works the same.

Figure 1 shows the tree view that is provided when you open an Open XML Package file in Visual Studio.

Figure 1 – Open XML Package treeview in Visual Studio

When you double-click on any XML part in the file that is open in the tree view, that part is opened in the standard Visual Studio XML editor, as shown in Figure 2.

Figure 2 - XML part open in the Visual Studio XML editor

The Open XML Package Editor Power Tool for Visual Studio 2010 is available for download at Visual Studio Gallery

Troubleshoot VSTO Add-In Load Failures (Navneet Gupta)

VSTOTeam — Mon, 21 Jun 2010 22:05:00 GMT

We have helped many developers in troubleshooting VSTO add-in load failures. Hamed has written a very nice blog post explaining the basic steps to troubleshoot VSTO add-in load failures. Even if you have not faced this issue yet, I recommend reading the post because it contains basic information about Office add-ins that developers should know.

Although every scenario is unique to itself; there are some common diagnostic steps that are repeated for every investigation. This PowerShell script complements Hamed’s blog and automates the troubleshooting steps; you may find it useful.

Creating an Add-in for Office 2007 and Office 2010 that "Lights Up" on Office 2010 (McLean Schofield)

VSTOTeam — Fri, 04 Jun 2010 16:46:00 GMT

Managed Office add-ins traditionally have been able to run in the targeted application (the version of the application whose PIAs the add-in references) and in later versions of the application. Therefore, if you need to create a single VSTO add-in that can be run in multiple versions of an application, the typical guidance is to develop the add-in by using a project template for the oldest version of Office that you want to support. For example, if your add-in needs to work with Office 2003 and Office 2007, you should create an Excel 2003 add-in (by using VSTO 2005 SE with Visual Studio 2005, or by using Visual Studio 2008).

However, this strategy has several inconveniences:

If you want to test/debug/run the add-in on your development computer, you must have the earliest version of Office you are targeting installed. Since side-by-side installations of Office are not supported on the development computer for VSTO development,if you're targeting an older version of Office this means that you cannot use the current version of Office on your development computer (for example, if you need to do some non-development work in Office).
Your add-in is limited to using only those features that are available in the earliest version of Office that you are targeting. You can work around this by creating a different add-in for each version of the application you are targeting and refactoring any common business logic into a shared assembly, or by using more advanced (and unsupported) methods, but this adds to the complexity of the development and deployment process.

With Visual Studio 2010, this scenario gets better. If you target the .NET Framework 4, you can now create a single add-in that targets both Office 2007 and Office 2010, and uses features that are available only to Office 2010 (this is the “lights up” part of the title of this blog). This is possible by virtue of the new embedded interop types feature in Visual Studio 2010 (also sometimes referred to as no-PIA or by the related /link compiler option). When you compile an add-in project that targets the .NET Framework 4, by default* the type information for all the PIA types referenced in the add-in code is embedded in the add-in assembly. At run time, this type information is used to resolve calls to the underlying COM type, rather than relying on type information in the PIAs.

The most commonly touted benefit of this feature is that because the add-in is no longer tightly coupled with the PIAs at compile time, the PIAs are no longer necessary on end user computers. However, this also means that you can now create an add-in that targets Office 2010, and the add-in will also run in Office 2007. The one caveat is this: when the add-in is loaded in Office 2007, it can use only those types/members that are available in Office 2007. You can achieve this by using the Application.Version property, and writing conditional code that uses an Office 2010-specific type/member only if the add-in is loaded in Office 2010. If the add-in is loaded in Office 2007, your code can do something else.

The following example demonstrates this technique in a Word 2010 add-in project that targets the .NET Framework 4. If the add-in is loaded in Word 2010, the code adds a check box content control (this is a new type of content control that was introduced in Word 2010) to the beginning of the active document. If the add-in is loaded in Word 2007, then it instead adds a Windows Forms check box, since this type of control can be added to a document in either version of Word.

if (Globals.ThisAddIn.Application.ActiveDocument != null)
{
    Word.Document activeDoc = Globals.ThisAddIn.Application.ActiveDocument;
    activeDoc.Paragraphs[1].Range.InsertParagraphBefore();

    string majorVersionString = Globals.ThisAddIn.Application.Version.Split(new char[] { '.' })[0];
    int majorVersion = Convert.ToInt32(majorVersionString);

    if (majorVersion >= 14)
    {
        // Add a check box content control.  
        Word.ContentControl checkBoxContentControl1 = activeDoc.ContentControls.Add(
            Word.WdContentControlType.wdContentControlCheckBox, activeDoc.Paragraphs[1].Range); 
        checkBoxContentControl1.Checked = true;
    }
    else if (majorVersion >= 12)
    {
         // Add a Windows Forms check box. This code requires a reference to Microsoft.Office.Tools.v4.0.Utilities
        Microsoft.Office.Tools.Word.Document vstoDoc = Globals.Factory.GetVstoObject(activeDoc);
        Microsoft.Office.Tools.Word.Controls.CheckBox checkBox1 = vstoDoc.Controls.AddCheckBox(
            vstoDoc.Paragraphs[1].Range, 15, 15, "checkBox1");
        checkBox1.Checked = true;
    }
}

Here’s another example that demonstrates this technique in an Outlook 2010 add-in that targets the .NET Framework 4. When the PageChange event of an Inspector is raised, this code uses the new ActivateTab method in Office 2010 to activate a custom Ribbon tab if the user navigated to a custom form region page. This code assumes the add-in project has a Ribbon (Visual Designer) item named Ribbon1 that defines a custom tab named MyCustomTab, and a Form Region item (of type Separate) named MyCustomFormRegion.

void Inspector_PageChange(ref string ActivePageName)
{
    string majorVersionString = Globals.ThisAddIn.Application.Version.Split(new char[]{'.'})[0];
    int majorVersion = Convert.ToInt32(majorVersionString);

    if (majorVersion >= 14)
    {
        Outlook.Inspector inspector = Globals.ThisAddIn.Application.ActiveInspector();
        Microsoft.Office.Tools.Ribbon.RibbonTab tabToActivate = Globals.Ribbons[inspector].Ribbon1.MyCustomTab;

        if (string.Equals(ActivePageName, "MyCustomFormRegion"))
        {
            tabToActivate.RibbonUI.ActivateTab(tabToActivate.ControlId.ToString());
        }
    }
}

Note that different Office applications apparently return differently formatted Application.Version strings. For example, on my computer Word 2010 returns “14.0”, but Outlook 2010 returns “14.0.0.4374”. To deal with these differences in a consistent way, the code above uses String.Split to extract the “major” version number out of this string (the number before the first period).

*This is the default behavior in projects that target the .NET Framework 4. If you change the Embed Interop Types property of a PIA reference in your project from True to False, the type information for that PIA is no longer embedded, and the add-in will be effectively bound to the specific PIA (or a later version) that is referenced. In other words, a Word 2010 add-in cannot be loaded in Word 2007, etc.

______________

McLean Schofield

VSTO Performance: Ribbon Reflection (Stephen Peters)

VSTOTeam — Thu, 03 Jun 2010 16:18:44 GMT

It is very easy to customize the Ribbon in your VSTO extension. All you need to do is to add a Ribbon (Visual Designer) to your solution, and it will appear when your solution is run without needing to do any more work. Behind the scenes, the VSTO runtime reflects through your entire addin assembly looking for Ribbon extensions to instantiate. This reflection can cause a significant performance hit, especially on larger solutions.

During an addin’s startup, the VSTO Runtime needs to discover and instantiate any user-created Ribbon extensions. The runtime does this by calling CreateRibbonExtensibilityObject, which is implemented by VSTO in the addin base class. It will then call CreateRibbonObjects, another method on the addin base class. This implementation of CreateRibbonObjects will reflect over every type in the addin assembly looking for classes that implement Microsoft.Office.Tools.Ribbon.IRibbonExtension (4.0) or Microsoft.Office.Tools.Ribbon.OfficeRibbon (3.5), instantiating each one, and then returns these in an array.

The performance hit comes from the reflection that happens in CreateRibbonObjects. For simple VSTO addins, this isn’t very significant. But if you link in a large library, then the reflector will pull in any types referenced in your assembly, and any types that those types reference, and so forth. This can result in having to spend a lot of time reading these types from disk, and it is completely unavoidable.

In order to avoid this, we can override either of these two methods so that the default implementation of CreateRibbonObjects is not called. If the addin has no ribbons, then it’s best to override CreateRibbonExtensibilityObject in order to execute as little code as possible.

protected override Office.IRibbonExtensibility 
    CreateRibbonExtensibilityObject()
{
    return null;
}

If your addin includes a Ribbon, then it’s better to override CreateRibbonObjects. Note that if you are creating an addin for .Net 3.5, you’ll need to return OfficeRibbon[] instead of IRibbonExtension[].

using Microsoft.Office.Tools.Ribbon;

protected override IRibbonExtension[] CreateRibbonObjects()
{
    return new IRibbonExtension[] { new Ribbon1(), new Ribbon2() };
}

In our perf lab, we ran some benchmarks using the method described in this blog entry to generate the numbers. Of interest were two tests involving an Outlook addin that had a Form Region with a single WPF control, before and after removing the Ribbon reflection. The results were that removing reflection saved over a second off of the cold startup time. So if you have larger VSTO solutions you may want to try to this technique to speed up performance.

Fixing Compile and Run Time Errors after Retargeting VSTO Projects to the .NET Framework 4 (McLean Schofield)

VSTOTeam — Wed, 02 Jun 2010 22:24:00 GMT

Now that Visual Studio 2010 is released, some of you might be itching to upgrade your existing VSTO projects so that you can take advantage of the new features in the .NET Framework 4 that improve the Office development experience. Or, you might have already started using Visual Studio 2010 to develop a VSTO project targets the .NET Framework 3.5, and now you want to switch over to the .NET Framework 4. The purpose of this post is to shed some light on scenarios where retargeting a VSTO project to the .NET Framework 4 can cause compile or run time errors in your project, and how to resolve these errors.

Retargeting a VSTO project to the .NET Framework 4 is pretty straightforward. If you created your project in Visual Studio 2010, you can retarget the project in the project properties by following the instructions here. If you are upgrading an existing project to Visual Studio 2010, you can choose to have the upgraded project target the .NET Framework 4 if the .NET Framework 3.5 is not installed on the computer; otherwise, you can always retarget it in the project properties later. For more information, see the “Retargeting During Project Upgrade” section in this blog post.

After you retarget your VSTO project, in many cases your work is done and you can jump right in and start writing code. However, for some projects – including any project that uses the Ribbon designer, any Outlook project that has a form region, and Excel and Word projects that use certain features such as smart tags and the GetVstoObject/HasVstoObject methods – you will get compile errors after you retarget the project, or the add-in might no longer run. In these scenarios, you must make some additional changes to your code. For the full list of scenarios that require code changes along with examples of the required changes, see the following MSDN articles:

For step-by-step tutorials and “How do I?” videos that demonstrate several specific retargeting scenarios, see the following links:

Background

When the VSTO team implemented support for the new “embedded interop types” feature (also sometimes referred to as “no-PIA”) of the .NET Framework 4, they had to also make some changes to the programming model of certain VSTO runtime features. For example, because the embedded interop types feature works only with interfaces, most types in the portion of the VSTO runtime that supports the .NET Framework 4 are now interfaces rather than classes. These and other changes have a trickle-down effect on some of the generated code and developer-written code in VSTO projects, and therefore require some manual code changes after you retarget a project.

If you’re interested in reading more about the embedded interop types feature in the .NET Framework 4 and the changes to the design of the Visual Studio 2010 Tools for Office runtime to support this feature, the following MSDN articles and blog posts.

Blog posts:

MSDN articles:

When Do I Need to Deploy the VSTO Runtime? (Mary Lee)

VSTOTeam — Thu, 13 May 2010 15:43:49 GMT

Aaron wrote a great article about the VSTO runtime components earlier, which explained the Office extensions for .NET Framework 3.5 and Office extensions for .NET Framework 4. He also explained that starting in Microsoft Office 2010, the Visual Studio 2010 Tools for Office runtime is included and does not need to be deployed alongside your Office solution – BUT – (currently) only if you are targeting the .NET Framework 3.5.

If you are targeting the .NET Framework 4, the Visual Studio 2010 Tools for Runtime must be selected in the Prerequisites Dialog Box and installed on end-user computers. This is because the Office extensions for .NET Framework 4 are not included in the Visual Studio 2010 Tools for Office runtime that is included in Microsoft Office 2010 Beta or RTM.

Mary Lee, Programming Writer.

Deploying the *.Utilities assemblies by using Windows Installer (Mary Lee)

VSTOTeam — Wed, 05 May 2010 21:52:51 GMT

Office solutions for .NET Framework 4 have dependencies on files that are distributed in the Visual Studio 2010 Tools for Office runtime, but there are also files outside of the runtime that are required for Office solutions to run on end-user computers.

These files are the following:

Microsoft.Office.Tools.Common.v4.0.Utilities.dll
Microsoft.Office.Tools.Excel.v4.0.Utilities.dll
Microsoft.Office.Tools.Outlook.v4.0.Utilities.dll
Microsoft.Office.Tools.Word.v4.0.Utilities.dll

For some information about these Utilities assemblies, see Assemblies in the Visual Studio Tools for Office Runtime. For even more information, see Design of VSTO 2010 runtime.

Once you add a Setup project to your Visual Studio solution and add the project output of the Office solution, the next step is usually to exclude all the detected dependencies. However, you may find that your Office solution does not run on end-user computers. This is because the *.Utilities assemblies must be deployed to the end-user computer or the functionality provided by the interfaces defined in these assemblies must be re-implemented in your own assembly.

To workaround this problem, make sure to not exclude the Utilities assemblies after the file is detected as a dependency.

All the other files are part of the Visual Studio 2010 Tools for Office runtime, so you do not need to deploy them with your Setup project.

Check out the deployment FAQ at http://social.msdn.microsoft.com/Forums/en-US/vsto/thread/1666d2b0-a4d0-41e8-ad86-5eab3542de1e. If you have additional questions about deployment, search for or post questions in the forum at http://social.msdn.microsoft.com/Forums/en-US/vsto/threads.

Mary Lee, Programming Writer.

Handling Sort and Filter Events in Excel (Navneet Gupta)

VSTOTeam — Mon, 03 May 2010 21:28:41 GMT

Recently I helped two customers that were trying to solve this problem. They wanted to get notifications whenever Excel sorted or filtered data. This is not as easy as it sounds because Excel does not raise any events for sorting and filtering.

I found two possible solutions, one of which requires much less coding but does not cover every possible scenario and another which requires a bit more code but covers all the scenarios we could think of. I thought I’d share my findings with you here in this post.

Waiting for the Calculate Event

Any changes in data/formulas in Excel sheet results in a Sheet_Change event immediately followed by Sheet_Calculate event. Sort and Filter raises just the Sheet_Calculate event. This means that all you need to do is handle this event and write a bit of code.

So this would seem to solve our problem; wait for Sheet_Calculate event and see if it follows any Sheet_Change event and we are done. I was super excited after knowing this and thought that I found the solution. But I soon realized that if the user has turned on Manual Calculation mode then the Sheet_Calculate event is not fired until the user calculates manually. Also there isn’t a way to differentiate between Sort and Filter. In order to do that, we need to write a bit more code.

Repurposing Commands

What does this mean and how is it going to solve our problem?

Almost every action in Excel (or any other Office App) that the user can perform via the UI is a command. For example, saving a file is the FileSave command in the Excel object model. We can program Office applications to call a function we write for a given command. That way we can execute our custom code and then continue with the default behaviour.

There are many useful articles and blogs on MSDN that talk about repurposing commands. References to the related articles are summarized below.

In this post I am focusing on repurposing commands in Office 2007 and Office 2010, but we can repurpose commands in Office 2003 as well, although the method will be slightly different.. If you are interested in how to repurpose commands in Office 2003 take a look at this post.

I am assuming here that you have a basic understanding of customizing the Office Ribbon using Visual Studio. The MSDN series below goes into great depth for customizing the Fluent Ribbons (although these were written for Office 2007, they equally apply to Office 2010).

· Customizing the 2007 Office Fluent Ribbon for Developers (Part 1 of 3)

· Customizing the 2007 Office Fluent Ribbon for Developers (Part 2 of 3)

· Customizing the 2007 Office Fluent Ribbon for Developers (Part 3 of 3)

To repurpose a command, we will create a CustomUI in ribbon.xml and specify the commands we want to repurpose, then we will write functions to handle the command.

Ingredients

We will need the Control ID and Control Type of the commands we want to repurpose.

Control IDs

We will need control IDs of the commands to write the custon UI. The Microsoft Office team has documented all the Control IDs for every Office application; they can be downloaded for Office 2007 and Office 2010. This article explains how you can find them from VBA.

For a given command the control IDs are same across various versions of Microsoft Office. There can be multiple UI elements that can perform the same action and usually there is a separate control ID for each UI element.

Control Types

We will need the control type for the control IDs as well. The control type is used to find out the signature of the function used to repurpose a particular command. Declaring our function with wrong signature will not trigger any exceptions, Office will just not call our function and continue silently. Table 4 this article explains the relationship between control types and function signatures. In this scenario we will be repurposing the button and toggleButton control types. Here are the function signatures for them.

button

onAction – repurposed

C#: void OnAction(IRibbonControl control, ref bool CancelDefault)

VBA: Sub OnAction(control As IRibbonControl, byRef CancelDefault)

C++: HRESULT OnAction([in] IRibbonControl *pControl, [in,out] VARIANT _BOOL *fCancelDefault)

Visual Basic: Sub OnAction(control As IRibbonControl, byRef CancelDefault)

toggleButton

onAction - repurposed

C#: void OnAction(IRibbonControl control, bool pressed, ref bool cancelDefault)

VBA: Sub OnAction(control As IRibbonControl, pressed As Boolean, byRef cancelDefault)

C++: HRESULT OnAction([in] IRibbonControl *pControl, [in] VARIANT_BOOL *pvarfPressed, [in,out] VARIANT _BOOL *fCancelDefault)

Visual Basic: Sub OnAction(control As IRibbonControl, pressed As Boolean, byRef CancelDefault)

Below are the Control IDs for sort and filter commands.

Control ID	Control Type
Filter	toggleButton
AdvancedFilterDialog	Button
FilterReapply	Button
SortDialog	button
SortAscendingExcel	button
SortDescendingExcel	button

The Recipe

1. Add a Ribbon(XML) Item to the Project by right clicking on the Project in Solution Explorer and selecting Add Item …

2. Double click the Ribbon1.xml in Solution Explorer to Open it.

3. Remove the <ribbon> element and all of its child elements from Ribbon1.xml

4. The CustomUI schema provides <commands> elements to specify commands in Office Fluent UI.

The command element needs two attributes idMso and onAction attribute. idMso is the Control ID and onAction is the function that needs to be called when this command executes.

Below is the sample xml for various Sort and Filter commands.

<?xml version="1.0" encoding="UTF-8"?>

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="Ribbon_Load">

  <commands>

    <!--Repurpose Sort Commands-->

    <command idMso="SortAscendingExcel" onAction="CustomSortAscendingExcel"/>

    <command idMso="SortDescendingExcel" onAction="CustomSortDescendingExcel"/>

    <command idMso="SortCustomExcel" onAction="CustomSortCustomExcel"/>

    <command idMso="SortDialog" onAction="CustomSortDialog"/>

    <!-- Repurpose Filter Commands -->

    <command idMso="Filter" onAction="CustomFilter"/>

    <command idMso="AdvancedFilterDialog" onAction="CustomAdvancedFilterDialog"/>

    <command idMso="FilterReaply" onAction="CustomFilterReaply"/>

  </commands>

</customUI>

5. The only thing remaining is to write the function implementation. Below is sample implementation of onAction handlers for Sort commands.

Implementing every onAction in a separate function helps a lot during debugging. You can move common code into a separate function though. If you set the cancel parameter of the called function to false, Excel will execute the default implementation of that command after calling your function. This way you can just hook into user actions to know that user has executed the command and let Excel do the actual work. You write these functions in the Ribbon1 code-behind file. For instance, in C# the code would be:

       public void CustomSortAscendingExcel(IRibbonControl control, ref bool cancel)

            Microsoft.Office.Interop.Excel.Range rngSelection = null;

            rngSelection = Globals.ThisWorkbook.Application.Selection as Microsoft.Office.Interop.Excel.Range;

            if (null != rngSelection)

               //TODO: Custom Logic here

        public void CustomSortDescendingExcel(IRibbonControl control, ref bool cancel)

            Microsoft.Office.Interop.Excel.Range rngSelection = null;

            rngSelection = Globals.ThisWorkbook.Application.Selection as Microsoft.Office.Interop.Excel.Range;

            if (null != rngSelection)

                //TODO: Custom Logic here

        public void CustomSortCustomExcel(IRibbonControl control, ref bool cancel)

            Microsoft.Office.Interop.Excel.Range rngSelection = null;

            rngSelection = Globals.ThisWorkbook.Application.Selection as Microsoft.Office.Interop.Excel.Range;

            if (null != rngSelection)

                //Perform sort

                Globals.ThisWorkbook.Application.Dialogs[Microsoft.Office.Interop.Excel.XlBuiltInDialog.xlDialogSort].Show();

                rngSelection.Select();

        public void CustomSortDialog(IRibbonControl control, ref bool cancel)

            Microsoft.Office.Interop.Excel.Range rngSelection = null;

            rngSelection = Globals.ThisWorkbook.Application.Selection as Microsoft.Office.Interop.Excel.Range;

            if (null != rngSelection)

                //Perform sort

                Globals.ThisWorkbook.Application.Dialogs[Microsoft.Office.Interop.Excel.XlBuiltInDialog.xlDialogSort].Show();

                rngSelection.Select();

I hope that this post will help you in repurposing commands in Office., In the beginning repurposing looks very difficult to do but once you have everything required to repurpose a command it is a piece of cake. Also note that Excel will call your function whenever a command executes until your customization is loaded. Repurposing is not limited to Excel you can apply it to any Office application.

References

For more information see:

· Temporarily Repurpose Commands on the Office Fluent Ribbon

· Office 2007 Control IDs

· Office 2010 Control IDs

· Find Control IDs from VBA

· Customizing the 2007 Office Fluent Ribbon for Developers (Part 1 of 3)

· Customizing the 2007 Office Fluent Ribbon for Developers (Part 2 of 3)

· Customizing the 2007 Office Fluent Ribbon for Developers (Part 3 of 3)

Why Should I Upgrade from .Net Framework 3.5 to .Net Framework 4 ? (Navneet Gupta)

VSTOTeam — Fri, 23 Apr 2010 18:50:00 GMT

I was chatting with some of my friends about Visual Studio 2010 and .Net Framework 4 and they asked me why should they move their application to .Net Framework 4, I am answering the question here for everybody to benefit. Frankly speaking there is no definitive answer; it is like there is no single pill that can cure all the problems. It all depends upon the application features and customer scenario.

Here is the summary of major advantages of targeting .Net Framework 4 and other reasons why you may decide to stick to .Net Framework 3.5 for time being. I am writing this post keeping in mind the VSTO developers but most of this applies to any managed application.

.Net Framework 4 comes with lots of cool features and many of them were developed keeping an Office developer in mind. Check out this article for all the new features in .Net Framework 4.

Here is the list which I feel will interest the Office developers the most.

Deploying pre-requisites for Office customizations have been a major pain point for many VSTO developers. Two new features in .Net Framework 4 address deployment of pre-requisites very well.

Size of .Net Framework

The size of the .Net Framework redistributable is greatly reduced, the table below summarizes the difference between .Net Framework 3.5 SP1 and .Net Framework 4.

	3.5 SP1	4.0 RTM
32 bit Client Profile	Online: 28 MB Offline: 255MB	28.8 MB
32 + 64 bit Client Profile	N/A	41 MB
32 bit Full	N/A	35.3 MB
32 + 64 bit Full	N/A	48.1 MB
32 + ia64 bit Full	N/A	51.7 MB
32 + 64 + ia64 bit Full	231 MB	N/A

Here is the above data in chart format.

As it is very clear from above table and chart that the size is greatly reduced for the redistributables. The web installers for .Net Framework 4 are under 1 MB in size (they require active internet connection to download the bits).

This is great enhancement; almost all Office applications will only require .Net Framework 4 Client profile. This article explains .Net Framework 4 Client profile. This blog shads more light on .Net Framework 4 Client Profile.

The .NET Framework 4 Client Profile does not include the following features. You must install the .NET Framework 4 to use these features in your application:

· ASP.NET

· Advanced Windows Communication Foundation (WCF) functionality

· .NET Framework Data Provider for Oracle

· MSBuild for compiling

Type Embedding and Type Equivalence

Another major concern related to deployment of Office customizations was deployment of Primary Interop Assemblies (PIAs). Before .NET Framework 4 if the customization only used some of the interfaces and methods from the Interop Assemblies, the complete set of the Primary Interop Assemblies still had to be deployed. .Net Framework 4 addresses this in very elegant way. The C# and VB compilers provide a /link switch that embeds the types referenced from the Primary Interop Assemblies into the application assembly itself. , Type Equivalence in the CLR can understand these embedded types and link them to the appropriate types at runtime. With this the customization does not require deployment of the Primary Interop Assemblies on end-user computers.

For more information about Type Embedding and Type Equivalence refer these blog posts.

The Pain of deploying Primary Interop Assemblies

Walkthrough: Embedding Type Information from Microsoft Office Assemblies (C# and Visual Basic)

VSTO Runtime Improvements

There have been some major improvements in VSTO Runtime 4.0 for the customizations that target .Net Framework 4. These enhancements were possible because of Type Embedding and Type Equivalence features of the compilers and CLR.

At a high level the VSTO Runtime has three major components; Unmanaged Components, Office Runtime 3.5 Extensions and Office Runtime 4.0 Extensions. Office Runtime 3.5 Extensions are used by the Office customizations that target .Net Framework 3.5 and Office Runtime 4.0 Extensions are used by the Office Customizations that target .Net Framework 4. This blog post explains the runtime extensions in detail.

The Office runtime 3.5 Extensions use the Managed AddIn Framework (MAF) to load the customization and to establish a communication link between the host application and the customization. MAF provides lots of benefits in terms of flexibility and version control, but it comes with some performance bottlenecks and implementation related design issues because of long chain of assemblies in MAF Pipeline.

Office runtime 4.0 extensions were developed using Type Embedding and Type Equivalence and we do not require MAF anymore, this improves customization loading time and our ability to provide future enhancements to the runtime at much lower cost. This blog post explains the design of the VSTO runtime in detail.

In addition to these features, there are other enhancements you will benefit from like In-Process Side by Side and Improvements to NGen in .NET Framework 4.

Hopefully by now you are sold on targeting your solutions to .Net Framework 4 .

There are also some changes that come with Windows 7 and Office 2010 that may affect your decision. Windows 7 now comes pre-loaded with .Net Framework 3.5 SP1; it benefits the developers who create customizations that target .Net Framework 3.5 SP1 because this pre-requisite is taken care of with its inclusion in the operating system. Additionally, the Office Runtime 3.5 extensions are bundled with Office 2010, and they are automatically activated if the users have .Net Framework 3.5 SP1 installed on their machines, check this blog post for details.

Hopefully this information will help you in making a more informed decision for targeting the appropriate .Net Framework version for your application.

Update: I was helping a customer with one of their Excel AddIn project and that reminded me another benefit of moving the VSTO Excel customization to .Net Framework 4.

All VSTO Excel solutions that target .Net Framework 3.5 SP1 or earlier use a locale proxy to solve a bug in Excel (http://support.microsoft.com/kb/320369) , this proxy adds performance overhead for each Interop call to Excel. Check out How VSTO solves the Excel LCID or Locale issue in the June CTP build for details.

VSTO Excel Customizations that target .Net Framework 4 do not need the local proxy and this improves the performance.

Upgrading VSTO Projects to use with Visual Studio 2010 (Navneet Gupta)

VSTOTeam — Thu, 15 Apr 2010 17:13:00 GMT

The first thing that you notice after opening your existing projects in Visual Studio 2010 is the very familiar Visual Studio Conversion wizard. Internally we call it Project Migration wizard. Personally I love this wizard because of its simplicity, my converted projects are only few clicks away. In this post I’ll walk through this wizard and tell you what’s happening behind the scenes.

Introduction

There is very useful information shown on the first page of the wizard. This information is very similar to what was on Visual Studio 2008 version. I have the screen shot below and I can bet that most of you will not read the entire statement. I have been using Visual Studio since Visual Studio 6.0 and never read this myself until I joined this team and started owning Project Migration J. Personally I would have written this as bulleted list. Here is my version of the information.

1. You see this wizard if this project was created in previous versions of VS, or if you upgraded your copy of Microsoft Office.

* The second part of above statement is very interesting in VSTO scenarios, I will elaborate that later.

2. Once you convert this project to Visual Studio 2010, you may not be able to use it with earlier versions of Visual Studio, better take backups J

3. We will checkout the project files automatically if the project is under source control and provided this machine is configured properly to use source control.

4. If the project is not under source control remove the read only attribute from the files and folders.

Backup

The second step in the wizard gives us a chance to backup existing source files. We highly recommend taking a backup so that’s why we select the option by default. If you click Finish on the previous page, we would take the backup by default. By default we create a folder named “Backup” under the project directory and store the backup there.

Confirm

The next step of upgrade process will tell you what we are going to do with your project. Again here is my bulleted list of what is written there.

1. We will checkout the files automatically, please make sure that the source control is configured properly on the machine.

2. We will upgrade the project to the currently installed version of Office. If you do not want to upgrade this uncheck “Always upgrade to installed version of Office” option on the “Office Tools” section of the Tools | Options dialog.

· Note that you can upgrade the Add-Ins even if you do not have any version of Microsoft Office installed on the machine.

· VSTO in Visual Studio 2010 does not support Office 2003 so we upgrade to Office 2007 format by default.

Update: Please note that it is still possible to create Office 2003 Shared AddIns in Visual Studio 2010, Misha has a nice blog about the COM Shim wizard being upgraded to use with VS 2010

http://blogs.msdn.com/mshneer/archive/2010/03/19/com-shim-wizards-for-vs-2010.aspx

Done

Once you click Finish we start upgrading the project to Visual Studio 2010 format. Once this is converted, you will get the final page of this wizard. If there were any errors during upgrade the conversion log checkbox will be checked by default.

If you do not have .Net Framework 3.5 SP1 installed on the machine the project migration will go through an extra step which I will explain later in “Retargeting During Project Upgrade” section below.

If you check the checkbox then the Conversion Report will display as shown below. It is clear from the report below that we touch only the .sln and .csproj/.vbproj files during project upgrade.

Retargeting During Project Upgrade

If the machine does not have .Net Framework 3.5 SP1 installed, the Project Migration wizard will ask you to either download .Net Framework 3.5 SP1 or to retarget the project to .Net Framework 4.

If you choose to download .Net Framework 3.5 SP1 the solution and project file will be upgraded to Visual Studio 2010 compatible format and the project will be unloaded in the Solution Explorer. After downloading .Net Framework 3.5 SP1 you can right click on the project in Solution Explorer and select Reload Project.

Please keep few things in mind when you choose to retarget the project to .Net Framework 4, this is a big decision; it comes with lots of power and with power comes lots of responsibilities. The major benefit of switching to .Net Framework 4 for VSTO solutions is the use of Type Embedding in VSTO Runtime. Once you retarget the solution to .Net Framework 4 all the referenced Primary Interop Assemblies will be embedded into the customization assembly and the end users will no longer need to install Microsoft Office Primary Interop Assemblies on their machines to run this customization.

There is a nice MSDN article which explains this, so be sure to go through it before deciding to switch to .Net Framework 4. Be aware that you may need to change some code as we have changed the programming model a bit. Take a look at some of the How Do I videos we have on the VSTO Dev Center that explain how to migrate projects.

Note: If you are upgrading a document level customization that targets Office 2003 you may need to install Visual Studio for Office Runtime Second Edition on developer machine before upgrading the project due to a known compatibility break we found while designing Visual Studio for Office Runtime 3.0 during the Visual Studio 2008 timeframe. Check “Upgrading Microsoft Office 2003 Projects” section of this article for more details.

So I hope that this post helps explain what is happening behind the scenes when you migrate your Office solutions to Visual Studio 2010.

You may find following articles useful while migrating projects to Visual Studio 2010.

Upgrading and Migrating Office Solutions

Migrating Office Solutions to the .NET Framework 4

Project Upgrade, Options Dialog Box

Have fun.

Using Team Build with VSTO – Made Easier! (Tobi Kral, Aaron Cathcart)

VSTOTeam — Tue, 13 Apr 2010 21:55:00 GMT

On Monday, the VSTO team released a Whitepaper documenting how to get your VSTO customizations building in a Team Build environment. No longer will you need to install Visual Studio on your build machine in order to accommodate building VSTO projects. You can view the Whitepaper here:

How to Build Visual Studio 2010 Office Development Projects with TFS Team Build 2010

As the whitepaper describes, configuring a build machine to build VSTO projects requires installing some prerequisites and making sure certain resources are in place. There's nothing particularly difficult about the steps, but there are enough assemblies and registry keys that have to be added to the build machine that it's pretty easy to miss one or two when doing it manually. (Really, we're speaking from experience on this one.) To streamline the process, we've found it helpful to use some scripts to take care of the nit-picky detail work.

There are two scripts we've been using, one to gather the required resources, and one to copy everything to the appropriate location on the build machine. There are sample scripts linked below, but first we'll quickly run through how the two scripts work.

CreateVSTOPayload.bat: This is the script that gathers the resources, and it needs to be run on a computer that has Visual Studio 2010 Professional (or better) installed. When executed, the script will create a "Payload" directory and copy the assemblies and target files to it.

InstallVSTOPayload.bat: This is the script that, when executed on the build machine, will install the resources gathered by CreateVSTOPayload. For the script to work, it requires the "Payload" directory created above as well as a couple of registry files (we have registry files published next to this batch script). Since the script is adding things to protected locations, it is necessary to run it from an elevated command prompt.

Sample Scripts
You can find the sample scripts up on Code Gallery here: http://code.msdn.microsoft.com/vstoteambuildscripts

While these scripts have been working for us, please note that it’s possible you’ll need to do a little tweaking.

Note: For the reg files on Code Gallery if you are using a 64-bit build machine you will need to use the Wow6432Node subkey. For example replace all instances of HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft with HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft.

Visual Studio 2010 RTM! New Resources, Samples, Videos, + more (Beth Massi)

VSTOTeam — Mon, 12 Apr 2010 21:32:00 GMT

Whooo hooooo! It’s been ~2 years in the making but Visual Studio 2010 has been released! This is my first full product cycle since I started Microsoft and oh what a ride! I’ve been watching live interviews from the Vegas launch event all day on Channel 9.

I’m really pumped about all the awesome resources that we’ve put together for you for launch and I’m looking forward to continuing to share my knowledge on how to build awesome business applications with Visual Studio 2010. It’s going to be a really fun year! Here are some of the plentiful resources to check out…

Developer Center

We’ve updated the VSTO Dev Center on MSDN with a variety of resources to help you get started learning all the new stuff that VS2010 has to offer. First off, we’ve been integrating Visual Studio 2010 content into all the pages. Here you’ll find the most up-to-date samples, videos, articles and news:

Office Development with Visual Studio (VSTO)

Visual Studio

SharePoint

.. more developer centers

For instance check out the new downloads and samples pages on VSTO Dev Center, and the new How Do I videos on Visual Studio and VSTO. The Dev Centers are your one-stop shop for all content like….

Product Downloads

Check out this link to download the Visual Studio 2010 Pro/Ultimate trial editions:

Visual Studio 2010 Pro & Ultimate Trial Downloads

Samples

We’ve updated all these samples online for Visual Studio 2010’s release and have added a bunch more like:

Office Development in Visual Studio 2010

Visual Studio 2010 and .NET Framework 4 Training Kit

SharePoint Development in Visual Studio 2010

… more samples

Articles

We also have a few MSDN Library technical articles published to get you started on some language, IDE and build features in VS as well as some notable MSDN Magazine articles on new features you can sink your teeth into.

Better Coding: Better Coding with Visual Studio 2010

IntelliTrace: Debugging Applications with IntelliTrace

How to Build Visual Studio 2010 Office Development Projects with TFS Team Build 2010

… more MSDN articles

Videos

“How Do I” Videos
Check out the new quick training videos on Visual Studio, VB, C#, Office and SharePoint:

Office Development with Visual Studio 2010 (VSTO)

Visual Studio 2010 IDE Series

SharePoint Development with Visual Studio 2010

Channel 9 Videos
Watch these interviews and demos on Visual Studio and new features:

Launch Demo: Sam Gazitt: SharePoint and Office Development with Visual Studio 2010

How We Do It: Building the Visual Studio Product Line

Overview of SharePoint Development in Visual Studio 2010

…more VS2010 on Channel 9, more of my interviews on Channel 9 (more coming soon!)

Blogs

Here are some of my favorite blogs that contain essential resources on Visual Studio 2010:

Visual Studio Platform Team Blog

Office Development with Visual Studio Team Blog

Visual Studio Data Team Blog

SharePoint Team Blog

Jason Zander

Check the Blogs, Dev Centers and Channel 9 for more content in the weeks to come, we’re still making updates and producing new content. Now that Visual Studio is launched, we’re just getting started here on MSDN! Have feedback and questions? Discuss Visual Studio and related technologies on the MSDN Forums.

I want to thank everyone in Visual Studio and DevDiv here at Microsoft and especially the BizApps team for a wonderful and exciting product! Visual Studio just keeps getting better and better.

Enjoy,
-Beth Massi, Visual Studio Community

Deploying COM Add-ins for 64-bit Office using Visual Studio (Saaid Khan for Nathan Halstead)

VSTOTeam — Fri, 09 Apr 2010 21:02:05 GMT

Nathan Halstead is a Program Manager on the Visual Studio Team. He is responsible for various aspects of Visual Studio extensibility, and is an avid ice hockey enthusiast. On occasion, he’s been known to guest author technical articles on various Microsoft blogs and forums. My only contribution to this blog is posting it here :). Here is what Nathan has to say:

Later this year, Microsoft will release the next version of its Office productivity suite – Office 2010. The 2010 release will be offered in both 32 and 64-bit flavors. The new 64-bit flavor of Office is especially useful for enabling computationally rich applications requiring larger amounts of system resources. However, the move to 64-bit poses some additional challenges for add-in developers who want to target both the 32 and 64-bit versions of Office.

For the past few releases, Visual Studio has shipped with several templates for creating add-ins for Office. If you are planning to build extensions for Office, and have not already done so, I strongly encourage you to take a look at the Visual Studio Tools for Office (VSTO) templates, which offer visual designers and managed APIs for developing and testing your Microsoft Office extensions.

If you can’t or don’t want to use the VSTO templates, Visual Studio also offers a bare-bones template for developing COM-based add-ins for Office called the “Shared Add-in” template. This template generates a solution which includes a basic implementation Office’s IDTExtensibility2 interface, and a lightweight MSI project for deploying the add-in. For the past several years, this bare-bones template has been sufficient for getting started with Office extensibility. If, however, you want to use it to target 64-bit Office, there are a few issues you might encounter that you should be aware of. This article will briefly walk you through these issues and explain how to work around them.

Creating a new Shared Add-in

To create a new Shared Add-in, select the project template from the new project dialog. For the purposes of this example, we will be creating a globally registered C# based add-in using Visual Studio 2008. To do this, launch Visual Studio with Administrator privileges (to ensure the build process has permissions to the HKCR registry hive) and select a new Shared Add-in under “Other Project Types -> Extensibility”:

A wizard will appear to guide you through the creation of your Add-in. Note that if you did not launch Visual Studio with Administrator privileges, the option to globally register your add-in will be disabled:

When you’ve finished the wizard, your solution will be generated, and configured for proper x86 deployment.

Registering the add-in with 64-bit Office for debugging

When the Shared Add-In Wizard finishes generating the solution, it automatically registers your add-in with the Office applications specified in the wizard. This ensures that debugging can work without running your setup application. If you selected the “My add-in should be available to all users…” option in the wizard, it registers your add-in to the 32-bit global registry location viewable in Regedit as [HKLM\Software\Wow6432Node\Microsoft\Office\<App>\AddIns\<AddInName>].

However, 64-bit Office cannot see registration information in this location. To load your add-in automatically, this registration information will need to be copied to 64 bit registry locations for 64-bit Office to see. To do this, copy all of the registry keys under [HKLM\Software\Wow6432Node\Microsoft\Office\<App>\AddIns\<AddInName>] to [HKLM\Software\Microsoft\Office\<App>\AddIns\<AddInName>].

For example, you would copy the following keys for Word registration:

From

[HKLM\SOFTWARE\Wow6432Node\

Microsoft\Office\Word\Addins\MyAddin1.Connect]

"FriendlyName"="Name"

"Description"="Description"

"LoadBehavior"=dword:00000003

[HKLM\SOFTWARE\Microsoft\Office\Word\

Addins\MyAddin1.Connect]

"FriendlyName"="Name"

"Description"="Description"

"LoadBehavior"=dword:00000003

Retargeting for x64 deployment

With your new solution in hand, the next step is to update its installer to follow 64-bit Windows deployment conventions. To do this, select the Setup project in the Solution Explorer, and update the project’s TargetPlatform property to x64 in the Properties window.

If you are using Visual Studio 2010, this is the only change that should be needed for your deployment project. Your installer will now be able to properly register your add-in with 64-bit versions of Office!

However, if you are using Visual Studio 2008, a bug in the deployment project system prevents the proper registration of 64-bit COM components. To work around this limitation, follow the instructions listed in the listed in the Troubleshooting Windows Installer Deployments topic on MSDN. See the Cannot load 64-bit self-registering DLL’s section, which describes in detail how to work around this for your Shared-Add-in assemblies by manually writing the 64-bit registry keys that register your COM assemblies.

Making your entire solution 64-bit

While native C++ applications will need to be updated to explicitly target 64-bit machines, in most cases Office will happily load your.NET add-ins without requiring you to explicitly target an x64 platform. However, there are situations where you will have to update your .NET assembly to be explicitly 64-bit. For example, Misha Shneerson highlights a situation on his blog where you may choose to use unsafe code to preserve icon transparency when rendering Office icons. If you use unsafe code, then you will need to recompile your assembly for the x64 platform.

Before doing this, you should familiarize yourself with some of the work that may be involved to ensure your add-in works properly when running 64-bit. There are a large number of resources available on this topic, but this MSDN article does a good job covering some of the fundamental considerations for .NET applications, and this vintage MSDN Magazine article does a fantastic job for native C++ applications.

If you need to build a 64-bit assembly, you will need to update your project’s build properties to do so. You may do this from within the properties editor for your project. For example, in a C# project, right click, and select properties to open the properties editor:

Navigate to the build tab, and change the Platform Target to x64:

For most Visual Studio projects, a 64-bit binary would be generated when you save and build. However, there is a bug in the VB and C# project systems that causes a build error for Shared Add-in projects. When you attempt to build, you will receive an error that states that your dll “is not a valid assembly.”

The culprit is the “Register for COM interop” project setting on the build tab:

By selecting this checkbox, a build task is automatically generated to register the COM assembly. This is used by the template to make it easier to test your add-in by automatically deploying your assembly on your machine. However, this task uses the 32-bit version of the regasm tool, which throws a “is not a valid assembly” error when run against 64-bit assemblies. The workaround for this issue is described in KB Article 956933, and involves unchecking this option, and creating your own build event to do the 64-bit registration.

A best practice for COM add-ins

With your setup project and your add-in assemblies updated, you will now be able to install and run your COM addin inside 64-bit Office applications! However, if you decide to build your add-in for Office without using VSTO, I would highly recommend using the COM Shim wizard, which will help you isolate your add-in ino a separate app-domain for better resiliency:

· VS 2008 COM Shim Wizard

· VS 2010 COM Shim wizard

· COM Shims and x64 Office

If you have additional recommendations and best-practices you think would be helpful to share, please include these in the comments! Have fun extending Office 2010!

Saaid Khan, Program Manager

Why is FrameworkVersionMismatchException thrown? (Hamed Ahmadi)

VSTOTeam — Tue, 06 Apr 2010 17:38:00 GMT

The “Microsoft.VisualStudio.Tools.Applications.Deployment.FrameworkVersionMismatchException” is thrown due to the specific implementation of how VSTO 2010 runtime loads the appropriate CLR to install a VSTO customization.

This exception is thrown when both .NET Framework 3.5 (CLR 2.0) and .NET Framework 4 (CLR 4) are installed on a machine and a VSTO customization which targets .NET Framework 4 is installed. The exception happens only when the customization is installed and has no impact on the successful installation and loading of the customization despite the fact that you can see an error logged in the event log, like this:

Microsoft.VisualStudio.Tools.Applications.Deployment.FrameworkVersionMismatchException: <compatibleFrameworks xmlns="urn:schemas-microsoft-com:clickonce.v2">

</compatibleFrameworks>

at Microsoft.VisualStudio.Tools.Office.Runtime.SolutionInstaller.Install(ClickOnceAddInDeploymentManager clickOnceAddInDeploymentManager, OfficeAddInDeploymentManager officeDeploymentManager, AddInInformation& info) at Microsoft.VisualStudio.Tools.Office.Runtime.SolutionInstaller.ProcessInstallerOperation(ClickOnceAddInDeploymentManager clickOnceAddInDeploymentManager, OfficeAddInDeploymentManager officeAddInDeploymentManager, AddInInformation& info) at Microsoft.VisualStudio.Tools.Office.Runtime.SolutionInstaller.ProcessInstallerOperation(Boolean uninstall, Boolean silent, Uri manifest, Int32& errorCode, String& errorMessage)

To install a VSTO customization, the native piece of VSTO runtime loads the CLR and lets the managed runtime parse the deployment manifest and install the customization. The target .NET Framework is specified in the deployment manifest (<CompatibleFrameworks> element). Therefore, when loading the CLR, the native VSTO runtime does not know which version of the .NET Framework the customization targets. Before CLR 4, CLR 2.0 was always loaded. Now that VSTO supports multi-targeting, we needed a mechanism to select the correct version of CLR to host.

At a high level, the runtime first attempts to load CLR 2.0 since we anticipated that the majority of developers target .NET Framework 3.5. Once CLR 2.0 is loaded, the managed runtime downloads and parses the deployment manifest. At this moment, if it is found out that the customization targets .NET Framework 4, “FrameworkVersionMismatchException” is thrown by the managed runtime and the compatible Framework is passed along. The native runtime catches the exception and loads CLR 4.

In summary, this exception does not indicate any error and is not the reason why a VSTO customization is not installed or loaded properly. Please follow the instructions in Debugging in Application-Level Projects and Debugging in Document-Level Projects to troubleshoot a VSTO customization. Should you have further questions about your customization, please visit VSTO forum.

Show and Hide Context Menu Items in Outlook 2010 (Norm Estabrook)

VSTOTeam — Fri, 12 Mar 2010 22:31:45 GMT

If you have written code that shows and hides context menu items in Outlook 2007, that code might not behave well in Outlook 2010. That is exactly what happened to this individual who recently posted to the VSTO forum.

The command bar object model (which most folks use to muck around with menus) has been deprecated in Outlook 2010. You can see a list of deprecated objects here - Outlook 2010 Object Model Changes Since Earlier Versions. Note that you can still use command bars, but be warned that “mileage may vary” and “objects in the mirror are closer than they appear”. etc. etc. You get the point.

Nice, so if not the command bar object model, then what? Well, for Outlook 2010 anyway, the answer is Ribbon XML.

In this post, I will show you how to show and hide items in a context menu by using Ribbon XML. The context menu appears when a user right-clicks an Outlook folder.

First, add a Ribbon XML item to your Outlook 2010 project.

Then add the following code to your ThisAddIn class. This example assumes that your Ribbon is called Ribbon1 and that you are using C#:

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()

{

return new Ribbon1();

}

Next, replace the contents of the Ribbon1.xml file with the following:

<?xml version="1.0" encoding="UTF-8"?>

</contextMenu>

</contextMenus>

</customUI>

Just to clarify, "FolderPropertiesContext" is the control identifier of the Properties command in the context menu. You can obtain the complete list of control identifiers here - Office 2010 Help Files: Office Fluent User Interface Control Identifiers. So you can show/hide/enable/disable just about anything you want.

When Outlook is about to display the Properties command, Outlook first consults a cool method that you are going to write called "IsVisible". You can name your method anything you want. You could name it "ShouldIShowThisMethodOrShouldINotShowThisMethod" or "NormsExamplesAreAlwaysVeryCoolandUseful“. Totally up to you. It’s only important that you use the correct method signature.

So let’s write the ”IsVisible” method. Add the following method to the Ribbon1.xml file.

public bool IsVisible(Office.IRibbonControl control)
{
    string foldername = ((Microsoft.Office.Interop.Outlook.Folder)control.Context).Name;
    if (foldername == "Inbox")
    {
        return false;
    }
    return true;
}

This code grabs the context of the control that is passed into the method. In this case, the context is the currently selected folder.

If the user right-clicks the Inbox folder, then we tell Outlook to not show the command by returning false. Otherwise, we tell Outlook to go ahead and make the command visible by returning true.

But wait. There’s more!

After the first couple of times that you right-click a folder, Outlook takes a coffee brake and stops calling your method. Actually, Outlook just caches the state of each control. If you want Outlook to call this method again, you have to “clear” that cache by “invalidating” the control. Here is what I did to make that happen:

First, provide access to the RibbonUI object in your ThisAddIn class. The RibbonUI object enables you to “invalidate” the Properties command of the folder context menu. Add the following code to the ThisAddIn class of your project:

Office.IRibbonUI ribbonUI;
       
public Office.IRibbonUI RibbonUI
{
    get { return ribbonUI; }
    set { ribbonUI = value; }
}

Next, set the RibbonUI property of your ThisAddIn class within the Ribbon_Load event of the Ribbon code file as follows:

public void Ribbon_Load(Office.IRibbonUI ribbonUI)
{
    this.ribbon = ribbonUI;
    Globals.ThisAddIn.RibbonUI = ribbonUI;
}

Finally, in the ThisAddIn class, handle the FolderContextMenuDisplay event of the Application object.

In the event handler of this event, “invalidate” the “FolderPropertiesContext” control.

Outlook.Application app;
private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    app = this.Application;
    app.FolderContextMenuDisplay += new Outlook.ApplicationEvents_11_FolderContextMenuDisplayEventHandler(app_FolderContextMenuDisplay);
 
}

void app_FolderContextMenuDisplay(Office.CommandBar CommandBar, Outlook.MAPIFolder Folder)
{
    RibbonUI.InvalidateControlMso("FolderPropertiesContext");
}

You can find other useful info about how to extend the Outlook user interface here Extending the User Interface in Outlook 2010.