Visual Studio 2008 Service Pack 1 is not finished yet, but we do have a beta version of the documentation ready for you to read!  You can learn about some of the features that you'll see later this year when we release SP1. 

I recommend starting with reading about a totally new feature that we put into SP1 that allows you to extend Word documents and Excel Workbooks at runtime from an Application-Level Add-in.  Here is the link to the Beta of the documentation:

http://vs2008sp1docs.msdn.microsoft.com/en-us/ms334311.aspx

You'll be able to create objects and respond to events including:

• Host Controls
• ListObjects
• Smart Tags
• Word Content Controls
• and Events such as DocumentBeforeSave

Only some of the new deployment features have been documented so far.  You can read about one of the new deployment features in the Event Logging (2007 System) page in the SP1 documentation here:

http://vs2008sp1docs.msdn.microsoft.com/en-us/ms331997.aspx

Starting in Visual Studio 2008 Service Pack 1 (SP1), you can use the event viewer in Windows to see error messages that are captured by the Visual Studio Tools for Office runtime when you install or uninstall Visual Studio Tools for Office solutions. You can use these messages from the event logger to resolve installation and deployment problems.

The Beta version of the Service Pack is only getting distributed to about a thousand beta testers who have great reputations for submitting clear feedback and bug reports.  I hope this little peek at the documentation will get you excited about what's coming later this summer in Service Pack 1.

-Christin Boyd, Program Manager

When you use ClickOnce in Visual Studio 2008 to deploy your Office solution, you can include prerequisites such as the .NET Framework 3.5, the Visual Studio Tools for Office system 3.0 Runtime, and Windows Installer 3.1.  However, the primary interop assemblies (PIAs) for the 2007 Microsoft Office system are not automatically listed in the Prerequisites dialog box. 

Fortunately, you can add the PIAs to the Prerequisites dialog box. The following procedure adds the 2007 Microsoft Office Primary Interop Assemblies to the Prerequisites Dialog Box. This procedure may look lengthy, but you only have to do it once.

1.  Download the OfficeVSTO2005SEWindowsInstallerV3.msi sample, which is part of the deployment whitepaper at Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer (Part 1 of 2).

2. Install OfficeVSTO2005SEWindowsInstallerV3.msi.

3. Copy the contents of %ProgramFiles%\Microsoft Visual Studio 2005 Tools for Office SE Resources\VSTO2005SE Windows Installer Sample Version 3\packages to %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages

4. Compile the component checker. This step checks if the computer has the correct version of Office installed to match the PIAs that are being installed.

a) Open a Visual Studio command prompt

b) Change directories to %ProgramFiles%\Microsoft Visual Studio 2005 Tools for Office SE Resources\VSTO2005SE Windows Installer Sample Version 3\projects\Checks

c) Type the following command: cl.exe /Oxs /MT /GS ComponentCheck.cpp advapi32.lib

d) Copy ComponentCheck.exe to the %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages\Office2007PIA folder.

5. Download and extract the Office 2007 PIAs from 2007 Microsoft Office System Update: Redistributable Primary Interop Assemblies.

6. Copy the o2007pia.msi file to the %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages\Office2007PIA folder.

7. In VS2008, on the Project menu, click ProjectName Properties.

8. Click the Publish tab.

9. Click the Prerequisites button to open the Prerequisites dialog box.

You should see the PIAs listed in the Prerequisites dialog box like the following image. Because the package.xml file does not define a HomeSite (a location to download the file), you will see a build warning.  Even if you have selected Download prerequisites from the component vendor's web site, the PIAs will go into a directory alongside your solution installer.

If you want to learn more about adding your own entries to the Prerequisites dialog box, see Adding Custom Prerequisites.

Mary Lee, programming writer.

My last post explained some of the differences between VSTO smart tags (that is, smart tags that you implement in a document-level solution for Word or Excel by using VSTO) and COM smart tags (that is, smart tags that you create by implementing COM interfaces provided by the smart tag SDK). If you are using VSTO to create application-level add-ins for Word or Excel, or add-ins for other applications that support smart tags, such as PowerPoint and Outlook, then you must use the smart tag SDK if you want to also create smart tags for these applications. The general recommendation is to create your smart tags in a separate assembly (or unmanaged DLL, if you wish).

At the end of the post, I mentioned that if you go this route, you can still call into the VSTO add-in from the COM smart tag. Any technology that enables you to communicate between application domains, such as .NET remoting or Windows Communication Foundation, should work, with varying degrees of complexity. However, the easiest way to do use built-in APIs provided by VSTO and Office to expose an object in your add-in to the smart tag, and then to call into this object from the smart tag.

Exposing an Object in Your Add-in to the Smart Tag

Starting in VSTO 2005 SE, add-ins have been able to expose functionality to other Office solutions by overriding the RequestComAddInAutomationService method. When your add-in is loaded, the VSTO runtime calls this method to give you an opportunity to return an object that want other Office solutions to use. For example, if your add-in can display a custom task pane that enables end users to navigate data, you can expose this feature to other solutions by defining a class with a method that displays the task pane, and then returning an instance of this class in your override of RequestComAddInAutomationService.

Side-bar: COM add-ins that implement the IDTExtensibility2 interface directly can do the same thing. In the implementation of the OnConnection method, the add-in receives an object that represents the application's view of the add-in as the AddInInst parameter. Although this parameter is typed as an object, for Office add-ins, this object is really a COMAddIn. Inside the OnConnection method, the add-in can set the COMAddIn.Object property to an object it wants to expose. When you override RequestComAddInAutomationService in a VSTO add-in, fundamentally the same thing is going on under the covers, but this is all abstracted away from view.

The following code example demonstrates a simple implementation of RequestComAddInAutomationService. This assumes that my VSTO add-in defines a class called AddInUtilities, which I want other solutions to be able to use.

    Private utilities As AddInUtilities

    Protected Overrides Function RequestComAddInAutomationService() As Object
        If utilities Is Nothing Then
            utilities = New AddInUtilities()
        End If
        Return utilities
    End Function

It is important to understand that you can't return just any object. Your object must be in an instance of a class that is visible to COM, and that exposes the IDispatch interface. One way to meet these requirements is to first define a COM-visible interface that exposes IDispatch. You should define this interface in its own assembly (for example, a class library project), so that the VSTO add-in and the smart tag assembly can both reference the same interface declaration. The following example demonstrates a simple IAddInUtilities interface that defines a method called DisplayData.

    <System.Runtime.InteropServices.ComVisibleAttribute(True)> _
    <System.Runtime.InteropServices.InterfaceType( _
        ComInterfaceType.InterfaceIsIDispatch)> _
    Public Interface IAddInUtilities
        Sub DisplayData()
    End Interface

Then, in your VSTO add-in that references the assembly that declares IAddInUtilities, you can define a COM-visible class that implements the IAddInUtilities interface. The actual code in the DisplayData implementation isn't important for this discussion, so I'll leave it out for clarity.

    <System.Runtime.InteropServices.ComVisibleAttribute(True)> _
    <System.Runtime.InteropServices.ClassInterface( _
        System.Runtime.InteropServices.ClassInterfaceType.None)> _
    Public Class AddInUtilities
        Implements IAddInUtilities

        Public Sub DisplayData() Implements IAddInUtilities.DisplayData

            ' Do stuff here.

        End Sub
    End Class

For more specific details about the requirements for the object you return in RequestComAddInAutomationService, see Calling Code in Application-Level Add-ins from Other Office Solutions. For a walkthrough that demonstrates how to expose an object in a VSTO add-in and then call into the object from VBA code in an Excel workbook, see Walkthrough: Calling Code in an Application-Level Add-in from VBA.

Accessing the Object From a COM Smart Tag

When you create a COM smart tag, you must implement the ISmartTagRecognizer and ISmartTagAction interfaces. Of these, ISmartTagAction defines a specific action that the end user can select when they click your smart tag. This is a likely place to want to call into your VSTO add-in. The question is, how do you do this?

When the user clicks the icon to run an action, your implementation of the ISmartTagAction.InvokeVerb method contains the code that you want to run. The Target parameter of this method is an application-specific object that represents the context in which the smart tag appears. For example, in Excel, the Target parameter is a Range that identifies the cell that the smart tag was attached to.

In your implementation of ISmartTagAction.InvokeVerb, you can cast the Target parameter to the appropriate object in the object model of the application. From there, you can easily traverse the application's object model to get the Application object, then the COMAddIn object for your VSTO add-in, and then finally the Object property that contains the object you exposed in the add-in.

The following example demonstrates a simple implementation of InvokeVerb. If the recognized term is sale, then this method calls a helper method named CallAddIn, and passes the Target parameter to this helper method.

    Public Sub InvokeVerb(ByVal VerbID As Integer, _
        ByVal AppplicationName As String, _
        ByVal Target As Object, ByVal Properties As ISmartTagProperties, _
        ByVal Text As String, ByVal Xml As String) _
        Implements ISmartTagAction.InvokeVerb

        If String.Compare("sale", Text, True) = 0 Then
            Select Case VerbID
                Case 1
                    CallAddIn(Target)
            End Select
        End If
    End Sub

Here is the definition of the CallAddIn helper method.

    Private Sub CallAddIn(ByVal Target As Object)
        Dim ExcelApp As Microsoft.Office.Interop.Excel.Application = Nothing

        If Target IsNot Nothing Then
            Dim SmartTagRange As Microsoft.Office.Interop.Excel.Range = _
                TryCast(Target, Microsoft.Office.Interop.Excel.Range)

            If SmartTagRange IsNot Nothing Then
                ExcelApp = SmartTagRange.Application
            End If
        End If

        If ExcelApp IsNot Nothing Then
            Dim AddIn As Microsoft.Office.Core.COMAddIn = ExcelApp.COMAddIns( _
                "ExcelSmartTagInteropDemo")
            Dim Utilities As AddInInterfaces.IAddInUtilities = _
                TryCast(AddIn.Object, AddInInterfaces.IAddInUtilities)

            If Utilities IsNot Nothing Then
                Utilities.DisplayData()
            End If
        End If
    End Sub

This method tries to cast the Target parameter to an Excel Range. If successful, the method gets the Excel Application object, and then uses the COMAddIns property to get the COMAddIn that represents a loaded VSTO add-in with the name ExcelSmartTagInteropDemo. Finally, the method gets the Object property, tries to cast it to an IAddInUtilities, and then calls the DisplayData method implemented by the add-in. This of course assumes that the smart tag assembly references the assembly in which the IAddInUtilities interface is defined.

At run time, when the end user types "sale" in an Excel range and clicks the smart tag action, then the smart tag calls into the DisplayData method implemented in the VSTO add-in. This all happens by way of COM interop via several built-in APIs in VSTO and Office.

--------------------------------------------------

McLean Schofield, programming writer

The document-level projects for Excel and Word in VSTO (in Visual Studio 2005 and Visual Studio 2008) provide a simple object model that you can use to create smart tags for documents and workbooks. A smart tag is a string that an Office application recognizes in a document. After the application recognizes the string, it displays a small icon next to the text. The user can then click that icon to display a list of actions they can choose from and activate. Typically, the actions are related to in some way to the identified text. For example, you could have a smart tag that recognizes stock symbols; when a user types an uppercase string of letters that matches a known stock symbol, a list of stock-related actions, such as looking up a stock price, could appear.

In most ways, creating smart tags using VSTO is much easier than creating smart tags without VSTO. However, there are some limitations that might prevent you from using VSTO to create smart tags. Even if you cannot use VSTO to create a smart tag, you can still use features in a VSTO add-in from the smart tag.

In this discussion, I'll refer to smart tags created by using VSTO as "VSTO smart tags", and smart tags created without using VSTO as "COM smart tags".

Creating VSTO Smart Tags

Creating a VSTO smart tag is relatively straightforward: you create a SmartTag object that recognizes one or more terms, create one or more Action objects that define the code that runs when the user clicks your smart tag options, and finally add the SmartTag object to the VstoSmartTags property of the ThisDocument or ThisWorkbook class in your project. 

The following somewhat contrived example demonstrates a simple smart tag in an Excel workbook project. This smart tag recognizes the term "sale", and when clicked, the action displays the address of the cell that contains the recognized term in a message box. This code assumes it is running from the ThisWorkbook class in the project.

Private SmartTagExample As Microsoft.Office.Tools.Excel.SmartTag
Private WithEvents DisplayAddressAction As Microsoft.Office.Tools.Excel.Action

Private Sub AddSmartTag()
    SmartTagExample = New Microsoft.Office.Tools.Excel.SmartTag( _
        "www.microsoft.com/Demo#DemoSmartTag", "Smart Tag Example")
    SmartTagExample.Terms.Add("sale")
    DisplayAddressAction = New Microsoft.Office.Tools.Excel.Action( _
        "Display Cell Address")

    ' Add the action to the smart tag.
    SmartTagExample.Actions = New Microsoft.Office.Tools.Excel.Action() { _
        DisplayAddressAction}

    ' Add the smart tag to the workbook.
    Me.VstoSmartTags.Add(SmartTagExample)
End Sub

Private Sub DisplayAddress_Click(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Excel.ActionEventArgs) _
    Handles DisplayAddressAction.Click

    Dim smartTagAddress As String = e.Range.Address( _
        ReferenceStyle:=Excel.XlReferenceStyle.xlA1)
    MsgBox("The recognized text '" & e.Text & _
            "' is at range " & smartTagAddress)
End Sub

For more information, see How to: Add Smart Tags to Word Documents and How to: Add Smart Tags to Excel Workbooks in the VSTO documentation.

Limitations of VSTO Smart Tags

Although VSTO smart tags are easy to implement, they do have several limitations:

• VSTO smart tags can be used only in document-level projects for Excel and Word. They cannot be used in application-level add-ins for Excel and Word; therefore, you cannot create VSTO smart tags that are recognized in any document or workbook that the user might open (these are also called application-level smart tags).
• VSTO smart tags also cannot be used in projects for any other Office application that supports smart tags, such as PowerPoint and Outlook (when composing e-mails with Word as the e-mail editor).

If you need to create a smart tag for an application other than Word or Excel, or you need to create an application-level smart tag for Word or Excel, you must create a COM smart tag.

Creating COM Smart Tags

To create a COM smart tag, use the Smart Tag SDK to create a managed (or unmanaged, if you prefer) DLL that implements the ISmartTagRecognizer and ISmartTagAction COM interfaces at a minimum, and optionally other interfaces, depending on the features you want to provide. This requires familiarity with COM programming, and that you implement all of the properties and methods of these interfaces, even those you don't intend to use. The DLL must also be registered on end user computers, as described in the Smart Tag SDK.

Implementing a COM Smart Tag in a VSTO Add-In

At this point, you might be wondering whether you could implement a COM smart tag in a VSTO add-in, since a VSTO add-in is a managed assembly, and you can implement COM interfaces in managed code.

You could, but you probably don't want to. The reason for this is that add-ins and smart tag DLLs have entirely different discovery and load mechanisms in Office:

• Office applications discover smart tag DLLs under the HKEY_CURRENT_USER\Software\Microsoft\Office\Common\Smart Tag registry key, and then call into the smart tag DLL using only the smart tag-specific interfaces (ISmartTagRecognizer, etc.).
• On the other hand, Office applications discover add-in DLLs under an entirely different (and application-specific) registry key, and then call into the add-in DLL using only the IDTExtensibility2 interface.
• Side-bar #1: If you're a VSTO developer who is thinking "IDTExtensibility-what???", VSTO abstracts the IDTExtensibility2 interface implementation away from your add-in code. The VSTO runtime implements this interface for you, and forwards the most interesting calls into this interface on to the ThisAddIn_Startup and ThisAddIn_Shutdown event handlers in your add-in code.
• Side-bar #2: If you clicked on the IDTExtensibility2 link and are wondering why you wound up in the Visual Studio extensibility documentation, this is because this interface (and the Extensibility.dll assembly that defines it) is also used to build Visual Studio add-ins.

The implication of these differences is that if you implement the smart tag COM interfaces in a VSTO add-in assembly, your assembly will be loaded twice: once as an add-in, and again as a smart tag DLL. Depending on the size of your add-in, this could result in a lot of redundant code being loaded into memory. Furthermore, because every VSTO add-in is loaded into a separate application domain, the two instances of your assembly will be in separate application domains, and cannot easily share code or data. Because of these issues, there is not much of a benefit to implement a COM smart tag in a VSTO add-in.

Calling Into A VSTO Add-in From a COM Smart Tag—Is It Possible?

If you're following me this far, your next question might be "OK, so if I implement a COM smart tag DLL and a VSTO add-in as part of my overall Office solution, how can I call into my add-in from my smart tag?" Because there are many Office customization features that can be used only in an add-in, you can probably think of many scenarios where this might be useful. For example, you might implement a custom task pane in an add-in for Excel, and you want to display unique information on this task pane when the user clicks a smart tag action in any open workbook. When the user clicks your action, how can your smart tag tell your add-in to display data in the custom task pane?

There are a number of ways you can do this. Any technology that enables you to communicate between application domains, such as .NET remoting or Windows Communication Foundation, should work, with varying degrees of complexity. However, the easiest way to do this is to expose an object in your add-in to other Office solutions, and then to call into this object from your smart tag. My next post will show how to do this.

--------------------------------------------------

McLean Schofield, programming writer

Have you used the new ClickOnce Publish and Deployment feature in Visual Studio 2008 for Office 2007 solutions?  If so, we need your feedback now - and we need it before May 8th (which is an internal deadline for our team)!  We're working on Service Pack 1 for Visual Studio 2008 and would like to know your opinion on a specific feature:

<Start of current scenario:

Currently the end-user is unable to cancel an Automatic Update most of the time.  When the user starts an Office application (e.g. Excel or Outlook) then the VSTO Runtime checks the registry to see if it's time to check for Addin Updates.  Then if it's time, it will go and download the ClickOnce Manifests (which is the .vsto and the .manifest files) from the deployment location.  If this process of downloading the manifests takes longer than 7 seconds, then the user is presented with a dialog that gives them the option to click Cancel, which halts the download.  Most of the time no one will see the Cancel because the downloading of the manifests is almost always faster than 7 seconds.

If the user doesn't click Cancel, then the system makes a trust decision.  If the update is trusted, then it starts to download the actual assemblies.  While downloading the assemblies, the user is unable to work with the Office application.  They have to wait for the download to complete, the addin to get loaded, and then the user can start using the Office application.  Keep in mind that this process usually takes less than 20 seconds.

If the user does click Cancel during the manifest download phase, then the side effect is that the addin is now DISABLED.  If the end user wants to re-enable the addin, then she needs to open Trust Center and go through about 3 clicks to enable it again.

End of current scenario>

So our question is, would you like to ALWAYS get the option to click Cancel during the process of downloading all the stuff?  Keep in mind that sometimes the whole process might be as short as 5 seconds, or as long as five minutes on sloooooow networks. 

Next question for your feedback:  And then if you cancel, should we leave the existing "out of date version" of the Addin as Enabled? 

The reason we disable the "out of date version" of the addin is because we received feedback from many companies saying that they want to enforce updates within the update time window.  Unfortunately we don't have the ability in Service Pack 1 to make the Enable/Disable feature a option for the developer (or IT department) to specify.  We're realizing that we have far more customers from companies who aren't as concerned about "enforcement" of updates.  Your feedback here and now will help us validate the needs of our customers.

You will be happy to hear that we are planning to include lots of enable/disable and cancel options in the next version of Visual Studio.  Your feedback today will help us craft Service Pack 1 for Visual Studio 2008.

If you’re looking for guidance on how to integrate SAP or PeopleSoft into your Office applications, then the OBA Sample Application Kits are a great place to start. An OBA, or Office Business Application, is a composite application that integrates line-of-business systems with Office applications (e.g. Excel or Outlook) and Microsoft Office SharePoint Server (MOSS) 2007. These kits provide some great documentation and source code to help you get up and running quickly. The kits include:

1. Source code for an end-to-end OBA
2. Installation guide
3. Solution walkthrough
4. Technical overview document

The kits are a free download and can be found by going to the OBA Sample Application Kits landing page on MSDN:

http://msdn2.microsoft.com/en-us/office/cc442491.aspx

Check out the kits and more by visiting the OBA Sample Application Kits site on MSDN today. Also, check out Steve Fox's blog for more information.

-Christin Boyd, Program Manager

If you'd like a quick introduction to the main aspects of Office development using Visual Studio 2008 Professional, you can now get it while you drive, travel, exercise, eat lunch, or whenever you usually listen to your portable MP3 player. (Of course, you can also listen at your computer with your usual media player.) There are eight episodes that you can get individually or as a zipped group from this Microsoft Download Center page:

Audio: Office Development Overview Series

Each of the eight episodes is about five minutes long or less, and the whole series back-to-back lasts about 30 minutes. There's also a zipped file that contains transcripts for each episode.

We have two more series planned for release in May that get deeper into details about Office development. Let us know what you think about these by leaving a comment on this post--we'd like to get your feedback.

I read a question on the forum about databinding in an Excel solution.  The developer was asking about Excel 2003, but the answer I wrote will work for both Excel 2003 and Excel 2007.  Here's the question:  http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=3122341&SiteID=1&mode=1

As a best practice you can create one dataset in ThisWorkbook designer and then programmatically reference it from your code in other sheets.

Here’s how:

Add new Data Source of Data Base type, by specifying a database connection and selecting tables, views and columns.

Next open ThisWorkbook.vb in the designer.  It will look like it's a big gray box with two sentences that say "This is the workbook designer...."  Now from the Toolbox, under the Data section, select a DataSet and drag it onto the design surface.  When you drop it, you will get a dialog that asks if you want a typed or untyped dataset.  Select Typed.  It should prepopulate an edit box with <your namespace>.MyDataSet.  Click OK.  On the design surface you should now see an icon next to MyDataSet1.  In C# you will want to set the modifier to Internal or Public on the data set in the property browser.

Next open the code behind ThisWorkbook.vb.  Inside the ThisWorkbook_Startup  procedure, you should fill your MyDataSet1 instance with code like this:

VB Sample

C# sample

  MyDataSetTableAdapters.PatientsTableAdapter ta =
    new MyDataSetTableAdapters.PatientsTableAdapter();
  ta.Fill(myDataSet1.Patients);

Next you can open Sheet1 designer.  Now select "Add New Data Source" from the data menu and this time choose to add an "Object" not a database!  You will get a dialog that shows the hierarchy and this time DO NOT select the table adapter!  Open the name of your project, then the namespace, then you should see MyDataSet. Select it then click OK.  This action will create an Object in your Data Sources window.

Now you can select from the Data Sources Window, you should see something called MyDataSet.  This object can be used to create a databinding in your sheets.  So you can drag from this universal object into any one of your sheets.  Grab it and drag it onto Excel Sheet1 and it created an empty table. In order to finish setting it up, select the table and in the property grid click on the arrow next to DataMember property and select the data table that you want to be bound to the table. Try it, and see how it creates a new BindingSource object for each sheet, but you still have just the one DataSet instance. 

In each Sheet, you need to add the following line of code for Each table:

Please let me know through comments on this blog if this explanation works for you.  Thank you!

Visual Studio 2008 offers a ClickOnce deployment experience for solutions developed for the 2007 Microsoft Office system.  However, if you want to deploy additional files, add extra registry keys, or use SMS, you may still be interested in creating a Windows Installer package.

Here are the very basic steps to configure your setup project:

1. Add the release build or publish output of your solution. Then manually add the application and deployment manifests (.dll.manifest and .vsto files).

2. For application-level projects, create the registry keys so that the Microsoft Office application can find your add-in. For more information, see Registry Entries for Application-Level Add-Ins. For the add-in name, use a syntax similar to [CompanyName].[AddinName].

3. For document-level projects, update custom document properties which point to the location of the deployment manifest. If you leave the document in the same relative location compared to the customization assembly, you don't need to update the _AssemblyLocation property. But if you want to move the document to a user's desktop or Documents folders, you'll have to update the _AssemblyLocation property. For more information, see Custom Document Properties Overview.

You must still use ClickOnce security to trust your solution. You can deploy your .msi at this point, but you'll see a trust prompt asking whether the solution should be installed or not. To avoid prompting your end users, sign your manifests with a known and trusted certificate or pre-trust the solution by creating an inclusion list entry. For more information, see Security in Office Solutions (2007 System).

Bonus: there is sample code to help you complete the steps of deploying additional files, updating the document's _AssemblyLocation, and creating an inclusion list entry.  Visit http://code.msdn.microsoft.com/VSTO3MSI in the MSDN Code Gallery to download the sample code.

Mary Lee, programming writer.

One of the lesser-known features of Visual Studio Tools for Office is the Microsoft Office Word and Microsoft Office Excel command bar. When you are developing a document-level project for Word or Excel (for example, a Word Document or Excel Workbook project) and you have the document or one of your worksheets open in the designer, this command bar appears in Visual Studio, just above the designer. In Excel, this command bar looks like the following by default.

The first several buttons in this command bar are for changing the keyboard scheme and mapping XML to the document or worksheet. This post is about the purpose of the rest of the buttons.

If you are designing a custom UI for your document or worksheet that includes Windows Forms controls that you add by using the designer, you can use these buttons to arrange the controls with a single click. When you select multiple controls in the designer, these buttons become enabled.

From left to right, here are the buttons you can use:

• Align Lefts. This button moves all of the controls to the left, so that they are aligned with the left side of the left-most control.

• Align Centers. This button moves all of the controls left or right so that they are aligned around the vertical axis of the widest control.

• Align Rights. This button moves all of the controls to the right, so that they are aligned with the right side of the right-most control.

• Align Tops. This button moves all of the controls up, so that they are aligned with the top side of the upper-most control.

• Align Middles. This button moves all of the controls up or down, so that they are aligned around the horizontal axis of the tallest control.

• Align Bottoms. This button moves all of the controls down, so that they are aligned with the bottom side of the bottom-most control.

• Make Horizontal Spacing Equal. The left-most and right-most control remain in place; the controls in between move horizontally so that there is equal horizontal space between each control.

• Make Vertical Spacing Equal. The top-most and bottom-most control remain in place; the controls in between move vertically so that there is equal vertical space between each control.

A special note about Word. In Word projects, the alignment buttons are enabled only if the selected controls are not in line with text. By default, controls that you add to a Word document at design time are in line with text. To change the layout style of the control, right-click the control and then click Format Control. Then, on the Layout tab, select a wrapping style other than In line with text:

Examples. Enough words! Here are some examples that show these alignment options in action. These examples are pretty contrived, but they should give you an idea of the effects of each option.

Given the following buttons on a worksheet:

Align Lefts rearranges the controls as follows:

Align Centers rearranges the controls as follows:

And Align Rights rearranges the controls as follows:

Given the following buttons on a worksheet:

Align Tops rearranges the controls as follows:

Align Middles rearranges the controls as follows:

And Align Bottoms rearranges the controls as follows:

Given the following buttons on a worksheet:

Make Horizontal Spacing Equal rearranges the controls as follows:

Finally, given the following buttons on a worksheet:

Make Vertical Spacing Equal rearranges the controls as follows:

I hope these options come in handy then next time you are adding controls to a document or worksheet in VSTO.

-------------------------------------------------

McLean Schofield, Programming Writer

You can add a custom group to the Message tab of an Outlook mail item.  For example, here is a custom group named "MyCoolGroup" that I added to the message tab of a new message:

Outlook lets you open a message in the following two modes:

• Compose (you are drafting a new message).
• Read (you are reading a message). 

Making a custom group appear for only one of these modes is pretty easy.  Making it appear for both modes is a tad more challenging. That is because the control ID of the Message tab in read mode is different than the control ID of the Message tab in compose mode. When you design your custom group in the VSTO Ribbon designer, you can only specify one control ID. This means that when you run the project, the custom group will only appear in the Message tab of a compose window or the Message tab of a read window depending on which control ID you specify at design-time.

If you want the group to appear in both versions of the Message tab (read and compose), you have to do a bit more work. Here is how you make the group appear for both modes:

First, add a Ribbon (Visual Designer) to an Outlook 2007 add-in project.

Then, set the RibbonType property of the Ribbon to Microsoft.Outlook.Mail.Compose and Microsoft.Outlook.Mail.Read as follows:

On the Ribbon designer, add a group to a tab and customize the group as desired. 

On the Ribbon designer, select the tab, open the Properties window, and then set the OfficeId of the tab to TabReadMessage.  TabReadMessage is the control ID of the default tab that appears on the Ribbon of a mail message that is open in read mode. 

Ok. Now when you run the project, your custom group will appear only if you open a mail item in read mode. Now you need to add a little code to display the custom group in the Message tab of a new mail item. That is, a mail item that you open in compose mode.

To do this, create an event handler for the NewInspector event. This event is raised every time a new Outlook inspector is open. In the event handler, check the EntryID property of the mail item. If this property is null, then the item is a new message.  If that is the case, set the OfficeId property of the tab to TabNewMailMessage.   TabNewMailMessage is the control ID of the Message tab of a mail message in compose mode. 

private Outlook.Inspectors inspectors;
private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    inspectors = this.Application.Inspectors;
    inspectors.NewInspector += 
        new Microsoft.Office.Interop.Outlook.InspectorsEvents_NewInspectorEventHandler
            (Inspectors_NewInspector);
}

void Inspectors_NewInspector(Microsoft.Office.Interop.Outlook.Inspector Inspector)
{
    Outlook.MailItem tmpMailItem = (Outlook.MailItem)Inspector.CurrentItem;
    if (tmpMailItem != null)
    {
        if (tmpMailItem.EntryID == null)
            Globals.Ribbons.Ribbon1.tab1.ControlId.OfficeId = "TabNewMailMessage";
    }
}

You can read more about adding custom groups to built-in tabs in the following MSDN articles:

How to: Customize a Built-in tab

How to: Get Started Customizing the Ribbon

Customizing a Ribbon for Outlook

Theoretically, you can develop an add-in for multiple versions of Microsoft Office by catering to the lowest common denominator. This means if you use an Excel 2003 add-in template in Visual Studio 2008, you would be able to develop and debug this with Excel 2007. However if you try this, you may meet these error messages: "You cannot debug or run this project, because the required version of the Microsoft Office application is not installed.", followed by "Unable to start debugging."

You can develop an Office 2003 add-in but use the 2007 Microsoft Office system for debugging. The following procedure demonstrates how to update your Visual Studio debugging options to use Microsoft Excel 2007 to debug an add-in targetting Microsoft Excel 2003.

1. On the Project menu, click on ProjectName Properties.

2. Click on the Debug tab.

3. In the Start Action pane, click the Start external program radio button.

4. Click the file browser button and navigate to %ProgramFiles%\Microsoft Office\Office12.

5. Choose Excel.exe and click Open.

6. Press F5 to debug your add-in.

This procedure works because the .NET Framework runtime loads the 2007 Microsoft Office version of the primary interop assembly, even though the add-in was developed with the Microsoft Office 2003 PIA. For more information, see Office Primary Interop Assemblies.

Before you use a Microsoft Office 2003 template, consider the impact on your project. Because you created your project with an Excel 2003 add-in template, you can now develop with the .NET Framework 2.0. However, this means that you cannot use new features in Visual Studio 2008 that depend on .NET Framework 3.5.

For additional information, see Andrew Whitechapel's blog entry Can you build one add-in for multiple versions of Office? and the MSDN Library documentation Creating Solutions for Multiple Versions of Microsoft Office.

Mary Lee, programming writer.

We have received feedback from several folks that they would like design one Ribbon by using the Ribbon visual designer, and then re-use that same Ribbon in more than one Office application. This approach makes sense. If my custom tab looks the same for each application, I really don’t want to create the same Ribbon in four separate Office projects. 

So I poked around to see if this was possible. I caught up with one of developers who created the VSTO Ribbon designer and he showed me exactly how to do it.

First, add a Ribbon to a VSTO project. Then, copy the Ribbon code files to a class library project. Finally, add a reference to the class library assembly from within any VSTO project and voila. Well, it’s a tad more challenging.  Here are all the detailed steps.

Create the Ribbon

1.      Create a 2007 Excel, Outlook, PowerPoint, or Word project in Visual Studio. For the purpose of these steps, create a C# project and name the project RibbonStarterProject.

2.      Add a Ribbon (Visual Designer) item to the project. For the purpose of these steps, accept the default name “Ribbon1”.

3.      Save and close the project.

Create a Class Library Project

1.      Create a new class library project in Visual Studio. For the purpose of these steps, name the project SharedRibbonLibrary.

2.      Add a project reference to the Microsoft.Office.Tools.Common.v9.0 assembly.

3.      On the Project Menu in Visual Studio, click Add Existing Item.

4.      In the Add Existing Item dialog box, browse to the “RibbonStarterProject” project directory, select the Ribbon.cs file, and click Add.

Ribbon1.cs is copied to the project directory and appears beneath the project node in Solution Explorer.

5.      Double-click Ribbon1.cs.

The Ribbon designer appears.

6.      From the Office Ribbon Controls tab of the Toolbox, drag a button onto group1.

7.      Click button1 to select it.

8.      In the Properties window, set Modifiers to Public.

Note:  By default, controls that you add to the Ribbon are Internal. That makes them only accessible to code inside the same assembly. However, when you access these controls, you will be accessing them through an assembly reference. Therefore, to reach them from code, you must make them public. More on this soon.

9.      Right-click the Ribbon designer, and then click Properties.

10.  In the Properties window, click the RibbonType property, and then select the Ribbon ID’s of the applications or Outlook Inspector windows in which you want the Ribbon to appear. For more information about this property, see the MSDN reference topic for the RibbonType property.

11.  In Solution Explorer, right-click Ribbon1.cs, and then click View Code.

12.  Change the namespace of the class to “SharedRibbonLibrary”.

13.  Repeat this step for the Ribbon1.designer.cs file.

14.  Compile and save the SharedRibbonLibrary project. You can now use the resulting assembly in any VSTO project that supports the Ribbon.

Consume the Ribbon Customization

1.      Create 2007 Excel, Outlook, PowerPoint, or Word project.

2.      Add a reference to the SharedRibbonLibrary assembly.

3.      Add the following code to the ThisAddin, ThisWorkbook, or ThisDocument class of your project. This code overrides the CreateRibbonExtensibilityObject method and returns the Ribbon to the Office application.

protected override Microsoft.Office.Core.IRibbonExtensibility

CreateRibbonExtensibilityObject()

{

    return new Microsoft.Office.Tools.Ribbon.RibbonManager(

        new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] { new       

           SharedRibbonLibrary.Ribbon1() });

}

4.      Add a new class to the project. Accept the default name “Class1.cs”.

5.      Replace the code in the Class1 file with the following:

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

{

    internal SharedRibbonLibrary.Ribbon1 Ribbon1

    {

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

    }

}

Ok – You are done! You can now access the Ribbon and the button that you added to the Ribbon in your code.  Lets try by handling an event in the consuming project.

Handle the Button Click Event

1.      Add the following code to the startup event handler of project.

Globals.Ribbons.Ribbon1.button1.Click += new EventHandler<Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs>(button1_Click);

2.      Add the following event handler to your project:

     void button1_Click(object sender,

Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs e)

{

    System.Windows.Forms.MessageBox.Show("I can handle events!");

}

3.      Run the project.

4.      When the Office application opens, click the Add-Ins tab, and then click your button.

A message that says “I can handle events!” appears.

- Norm Estabrook

Programming Writer for BizApps User Education

The Visual Studio 2008 Tools for Office team just released a cool suite of productivity apps for VS Office development called the VSTO Power Tools. One of the tools included is the Ribbon IDs Tool Window, an add-in tool window for VS that lets you browse the MSO icons that come with Office. You can use these icons to spiff up your custom Ribbon controls. All you need to do is click an icon in the Ribbon IDs Tool Window to obtain its ID, and then plug the value into the control's OfficeImageID property.

I've recorded a short video that demonstrates the tool window and how to use it to customize some Ribbon controls:

There are a couple of additional items not in the video that bear mentioning:

1. You can also use this tool with XML-based ribbons, even dragging-and-dropping the icon value into the XML.
2. You are not limited to using only MSO images in your controls, although that this is the purpose of this tool.

Here are links to the Help topics I mentioned at the end of the video:

• Ribbon Overview
• How to: Get Started Customizing the Ribbon
• Walkthrough: Creating a Custom Tab by Using the Ribbon Designer

Try it out and let us know what you think!

- Kemp Brown
Programming Writer for BizApps User Education

There are many resources to learn about Visual Studio Tools for Office, and they are scattered through blogdom and even the MSDN Library. In my one year on this team, I've collected various helpful links that I share here.

The Visual Studio Tools for the Office System (3.0) whitepapers written by subjet matter expert like MVPs in the Microsoft Office Development section of the MSDN Library. These complement the Visual Studio Tools for Office documentation.

Several VSTO team members share their expertise on their own blogs. Misha discusses how to use an unofficial feature of Microsoft Office to deploy to alll users in Deploying your VSTO Add-In to All Users (Part I) and