Office Development with Visual Studio : smart tags

New "How Do I" Video on Creating Smart Tags in Word (Beth Massi)

VSTO Team — Thu, 18 Dec 2008 20:00:00 GMT

Our very own Mary Lee has got a new video up on the Dev Center on programming smart tags in with custom recognizers in Word using Visual Studio 2008 Service Pack 1. This is a video version of the How To topic in the MSDN library.

Watch or download the video here.

Thanks Mary!

Enjoy,
-Beth Massi, Visual Studio Community

Peek at Service Pack 1 (Christin Boyd)

VSTO Team — Mon, 12 May 2008 08:42:10 GMT

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

Calling Into A VSTO Add-in From a COM Smart Tag (McLean Schofield)

VSTO Team — Wed, 07 May 2008 23:38:31 GMT

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

Understanding VSTO Smart Tags and COM Smart Tags (McLean Schofield)

VSTO Team — Fri, 02 May 2008 22:09:33 GMT

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