How to create an Office XP Smart Tag DLL by using Visual Basic .NET

Smart Tags are a technology that was introduced with Office XP that provides Office users more interactivity with the content of their Office documents. A Smart Tag is an element of text in an Office document that is recognized as having custom actions associated with it. An example of one of these special elements of text might be an e-mail name that is typed into a Word document or an Excel workbook. If the e-mail name is recognized as a Smart Tag, the user is presented with one or more actions to perform on the specified text. Possible actions associated with an e-mail name are to look up additional contact information, or send a new e-mail message to that contact.

You can extend the capabilities of Office XP by developing your own Smart Tag Recognizer/Action DLL for use in Office documents. This article describes how to build a Smart Tag DLL by using Visual Basic .NET and discusses what registry settings are required for Office XP to identify and use your Smart Tag DLL.

NOTE: Excel 2002 and Word 2002 are the only Office XP programs that support Smart Tags. However, the information presented in this article can be applied to Smart Tag development for any program that adopts the Smart Tag technology.

Smart Tag interfaces

A Smart Tag DLL is an object that implements two special interfaces: ISmartTagRecognizer and ISmartTagAction. The ISmartTagRecognizer interface is responsible for recognizing text that is typed into a document as a Smart Tag. The ISmartTagAction interface is responsible for performing actions on a particular Smart Tag string at the user's request. It is not required that these interfaces be implemented in the same DLL. You can have a recognizer DLL and one or more action DLLs that extend a single Smart Tag type for different actions.

Documentation for these interfaces, and the type library that defines them, is provided in the Smart Tag Software Development Kit (SDK). If you have not already done so, install the Smart Tag SDK before you continue with the steps to create the sample Smart Tag. You can obtain the Smart Tag SDK from the Microsoft Office XP Developer (MOD) CD-ROM, or you can download it. To download the Smart Tag SDK, visit the following Microsoft Web site:

Step-by-Step Instructions to Build a Smart Tag DLL

The following steps create a simple Smart Tag DLL that recognizes the Microsoft Network (MSN) Instant Messenger contacts and gives the user the ability to send e-mail or instant messages to a recognized contact. You must have Instant Messenger 7.5 or a later version to use this sample. If you do not have Instant Messenger 7.5 or a later version, you can download a copy. To do this, visit the following Microsoft Web site:

Create the resource libraries and install them in the Global Assembly Cache

1. On the Start menu, point to Programs, click Microsoft Visual Studio .NET, click Visual Studio .NET Tools, and then click Visual Studio .NET Command Prompt. Change to the root directory of drive C.
2. Generate strong named key pairs by issuing the following commands:

   sn -k SmartTagLib.snk
   sn -k Messenger.snk
   sn -k SmartTagSample.snk
   					

3. From the command prompt, change the directory to the location that contains the Smart Tag SDK type library. The default location for this directory is C:\Program Files\Common Files\Microsoft Shared\Smart Tag.
4. Issue the following command to generate the strong named wrapper DLL from the type library:

   tlbimp mstag.tlb /keyfile:c:\SmartTagLib.snk /out:c:\SmartTagLib.dll
   					

5. Issue the following command to install this DLL into the global assembly cache:

   gacutil /i c:\SmartTagLib.dll
   					

6. From the command prompt, change the directory to the installation location for MSN Instant Messenger. The default location for this directory is C:\Program Files\Messenger.
7. Issue the following command to generate the strong named wrapper DLL from the type library:

   tlbimp msmsgs.exe\3 /keyfile:c:\Messenger.snk /out:c:\Messenger.dll 

8. Issue the following command to install this DLL into the global assembly cache:

   gacutil /i c:\Messenger.dll

Create the Smart Tag DLL

1. Start Microsoft Visual Studio .NET. On the File menu, click New and then click Project. Under Project types click Visual Basic Projects, and then select Class Library. Name the project SmartTagSample. Class1 is created by default.
2. Add references to the MSN Instant Messenger Library and the Smart Tag SDK library that you just created. To do this, follow these steps:
   1. On the Project menu, click Add Reference.
   2. Click Browse. In the Select Component dialog box, select C:\SmartTagLib.dll, and then click Open.
   3. Click Browse. In the Select Component dialog box, select C:\Messenger.dll, and then click Open.
   4. Click OK in the Add References dialog box to accept your selections.
3. In the Project Properties window, rename Class1.vb to Recognizer.vb.
4. Replace the code in the code window for Recognizer.vb with the following:

      Public Class Recognizer
          Implements SmartTagLib.ISmartTagRecognizer
    
          Dim Contacts As Array
    
          Public Sub New()
              Dim i As Integer
              Dim oMessenger As New Messenger.MessengerClass()
              Dim oUsers As Messenger.IMessengerContacts
              Dim oUser As Messenger.IMessengerContact
    
              oUsers = oMessenger.MyContacts()
              Contacts = Array.CreateInstance(GetType(String), oUsers.Count)
              i = 0
    
              For Each oUser In oUsers
                  Contacts.SetValue(oUser.FriendlyName, i)
                  i = i + 1
              Next
          End Sub
    
          Public ReadOnly Property Desc(ByVal LocaleID As Integer) As String _
     Implements SmartTagLib.ISmartTagRecognizer.Desc
              Get
                  Debug.WriteLine("Recognizer::Desc")
                  ' Return a long description of the recognizer.
                  Return "Microsoft Messenger recognizes your Instant Messenger Contacts"
              End Get
          End Property
    
          Public ReadOnly Property Name(ByVal LocaleID As Integer) As String _
     Implements SmartTagLib.ISmartTagRecognizer.Name
              Get
                  Debug.WriteLine("Recognizer::Name")
                  ' Return a short title about the recognizer.
                  Return "Microsoft Messenger Contacts Visual Basic .NET Recognizer"
              End Get
          End Property
    
          Public ReadOnly Property ProgId() As String _
     Implements SmartTagLib.ISmartTagRecognizer.ProgId
              Get
                  Debug.WriteLine("Recognizer::ProgID")
                  ' Return the ProgID of the Recognizer interface.
                  Return "SmartTagSample.Recognizer"
              End Get
          End Property
    
          Public Sub Recognize(ByVal [Text] As String, ByVal DataType As SmartTagLib.IF_TYPE, _
     ByVal LocaleID As Integer, ByVal RecognizerSite As SmartTagLib.ISmartTagRecognizerSite) _
     Implements SmartTagLib.ISmartTagRecognizer.Recognize
              Debug.WriteLine("Recognizer::Recognize")
              ' The Recognize method is called and passed a text value.
              ' You should recognize strings in the text and set up the actions.
              Dim i As Integer
              Dim startpos As Integer
              Dim strlen As Integer
              Dim propbag As SmartTagLib.ISmartTagProperties
    
              ' Loop through all contacts.
              For i = 0 To Contacts.GetUpperBound(0)
                  ' Look for a contact name in the text.
                  startpos = Text.IndexOf(Contacts(i)) + 1
                  ' Find the length of the contact name.
                  strlen = Contacts(i).Length
                  ' Look for all occurrences of contacts in the string.
                  While (startpos > 0)
                      ' Create a new property bag.
                      propbag = RecognizerSite.GetNewPropertyBag
                      ' Commit the Smart Tag to the property bag.
                      RecognizerSite.CommitSmartTag("microsoft/messenger#contacts", _
                               startpos, strlen, propbag)
                      ' Continue looking for contacts in the string.
                      startpos = Text.IndexOf(Contacts(i), startpos + strlen) + 1
                  End While
              Next i
          End Sub
    
          Public ReadOnly Property SmartTagCount() As Integer _
     Implements SmartTagLib.ISmartTagRecognizer.SmartTagCount
              Get
                  Debug.WriteLine("Recognizer::SmartTagCount")
                  ' Return the number of Smart Tags that you support.
                  Return 1
              End Get
          End Property
    
          Public ReadOnly Property SmartTagDownloadURL(ByVal SmartTagID As Integer) As String _
     Implements SmartTagLib.ISmartTagRecognizer.SmartTagDownloadURL
              Get
                  Debug.WriteLine("Recognizer::SmartTagDownloadURL")
                  ' Return the URL that is embedded in documents.
                  Return ""
              End Get
          End Property
    
          Public ReadOnly Property SmartTagName(ByVal SmartTagID As Integer) As String _
     Implements SmartTagLib.ISmartTagRecognizer.SmartTagName
              Get
                  Debug.WriteLine("Recognizer::SmartTagName")
                  ' This method is called the same number of times as you
                  ' return in SmartTagCount. This method sets a unique name
                  ' for the Smart Tag.
                  Return "microsoft/messenger#contacts"
              End Get
          End Property
      End Class
   					

5. On the Project menu, select Add Class. Under Templates, select Class, and name the class Action.vb. Click Open to create the new class.
6. Replace the code in the code window for Action.vb with the following:

      Public Class Action
          Implements SmartTagLib.ISmartTagAction
    
          Public ReadOnly Property Desc(ByVal LocaleID As Integer) As String _
     Implements SmartTagLib.ISmartTagAction.Desc
              Get
                  Debug.WriteLine("Action::Desc")
                  ' Return a long description describing the action.
                  Return "Provides actions for the Messenger Smart Tag"
              End Get
          End Property
    
          Public Sub InvokeVerb(ByVal VerbID As Integer, ByVal _
   ApplicationName As String, ByVal Target As Object, ByVal Properties _
   As SmartTagLib.ISmartTagProperties, ByVal [Text] As String, ByVal _
   Xml As String) Implements SmartTagLib.ISmartTagAction.InvokeVerb
              Debug.WriteLine("Action::InvokeVerb")
    
              ' This method is called when a user invokes a verb
              ' from the Smart Tag menu.
              Dim oMessenger As New Messenger.MessengerClass()
              Dim oUsers As Messenger.IMessengerContacts
              Dim oUser As Messenger.IMessengerContact
    
              oUsers = oMessenger.MyContacts()
              ' Loop through the contacts.
              For Each oUser In oUsers
                  ' Verify that the contact is the correct one.
                  If (String.Compare(oUser.FriendlyName, Text, True) = 0) Then
                      Select Case VerbID
                          Case 1
                              ' The user wants to display the Instant Message
                              ' box to send the contact a message.
                              oMessenger.InstantMessage(oUser)
                          Case 2
                              ' Shell the "mailto" protocol to start the
                              ' mail program and create a new message.
                              System.Diagnostics.Process.Start("mailto:" & _
   oUser.EmailAddress)
                      End Select
                  End If
              Next
          End Sub
    
          Public ReadOnly Property Name(ByVal LocaleID As Integer) As String _
     Implements SmartTagLib.ISmartTagAction.Name
              Get
                  Debug.WriteLine("Action::Name")
                  ' Return a short name describing the Action.
                  Return "Messenger Smart Tag"
              End Get
          End Property
    
          Public ReadOnly Property ProgId() As String _
   Implements SmartTagLib.ISmartTagAction.ProgId
              Get
                  Debug.WriteLine("Action::ProgID")
                  ' Return the ProgID of the Action interface.
                  Return "SmartTagSample.Action"
              End Get
          End Property
    
          Public ReadOnly Property SmartTagCaption(ByVal SmartTagID As _
   Integer, ByVal LocaleID As Integer) As String _
     Implements SmartTagLib.ISmartTagAction.SmartTagCaption
              Get
                  Debug.WriteLine("Action::SmartTagCaption")
                  ' This caption appears on the menu for the smart tag.
                  Return "Messenger Smart Tag"
              End Get
          End Property
    
          Public ReadOnly Property SmartTagCount() As Integer _
   Implements SmartTagLib.ISmartTagAction.SmartTagCount
              Get
                  Debug.WriteLine("Action::SmartTagCount")
                  ' Return the number of smart tags this action supports.
                  Return 1
              End Get
          End Property
    
          Public ReadOnly Property SmartTagName(ByVal SmartTagID As _
   Integer) As String Implements SmartTagLib.ISmartTagAction.SmartTagName
              Get
                  Debug.WriteLine("Action::SmartTagName")
                  ' This method is called the same number of times as you
                  ' return in SmartTagCount. This method sets a unique name
                  ' for the smart tag.
                  Return "microsoft/messenger#contacts"
              End Get
          End Property
    
          Public ReadOnly Property VerbCaptionFromID(ByVal VerbID As _
   Integer, ByVal ApplicationName As String, ByVal LocaleID As Integer) _
   As String Implements SmartTagLib.ISmartTagAction.VerbCaptionFromID
              Get
                  Debug.WriteLine("Action::VerbCaptionFromID")
                  ' Get a caption for each verb. This caption appears
                  ' on the Smart Tag menu.
                  Select Case VerbID
                      Case 1
                          Return "Send this contact an Instant Message"
                      Case 2
                          Return "Send e-mail to this contact"
                  End Select
              End Get
          End Property
    
          Public ReadOnly Property VerbCount(ByVal SmartTagName As String) _
   As Integer Implements SmartTagLib.ISmartTagAction.VerbCount
              Get
                  Debug.WriteLine("Action::VerbCount")
                  ' Return the number of verbs you support.
                  If (SmartTagName.Equals("microsoft/messenger#contacts")) Then
                      Return 2
                  End If
              End Get
          End Property
    
          Public ReadOnly Property VerbID(ByVal SmartTagName As String, _
   ByVal VerbIndex As Integer) As Integer Implements SmartTagLib.ISmartTagAction.VerbID
              Get
                  Debug.WriteLine("Action::VerbID")
                  ' Return a unique ID for each verb you support.
                  Return VerbIndex
              End Get
          End Property
    
          Public ReadOnly Property VerbNameFromID(ByVal VerbID As Integer) As String _
     Implements SmartTagLib.ISmartTagAction.VerbNameFromID
              Get
                  ' Return a string name for each verb.
                  Select Case VerbID
                      Case 1
                          Return "SendInstantMessage"
                      Case 2
                          Return "SendEmail"
                  End Select
              End Get
          End Property
      End Class
   					

7. Add the following line to the end of AssemblyInfo.vb:

   <Assembly: AssemblyKeyFile("C:\SmartTagSample.snk")>
   					

8. On the Build menu, click Build Solution to create the DLL.
9. From a Visual Studio .NET command prompt, change the directory to the bin directory for your project.
10. For this DLL to work correctly, you must install it into the global assembly cache. Issue the following command to install the DLL:

    gacutil /i SmartTagSample.dll
    					

11. To register the .NET DLL so that COM clients can invoke it, run the following command:

    regasm SmartTagSample.dll
    					

Register the Smart Tag DLL for use with Office

Warning Serious problems might occur if you modify the registry incorrectly by using Registry Editor or by using another method. These problems might require that you reinstall your operating system. Microsoft cannot guarantee that these problems can be solved. Modify the registry at your own risk.
Before you can use any Smart Tag DLL, it must be registered on the system. Typical COM registration is completed for you when you compile the project, distribute the DLL with the Package and Deployment Wizard, or call Regsvr32.exe with the DLL name. You must create additional registry entries that are not part of typical COM registration so that Office applications can identify the DLL as a Smart Tag DLL. To do this, follow these steps:

1. From a command line, start Regedit.exe.
2. Locate the following key in the registry:
   HKEY_CURRENT_USER\Software\Microsoft\Office\Common\Smart Tag\Actions
3. Add a new subkey named SmartTagSample.Action.
4. Locate the following key in the registry:
   HKEY_CURRENT_USER\Software\Microsoft\Office\Common\Smart Tag\Recognizers
5. Add a new subkey named SmartTagSample.Recognizer.
6. Close Registry Editor.

Steps to test the Smart Tag DLL

Smart Tags obey the same security model as macros. If the security settings of the application are set to High, the Smart Tag DLL does not load unless Trust all installed add-ins and templates is selected. If the security settings are set to Medium and Trust all installed add-ins and templates is not selected, the user is prompted to enable or disable each add-in. Because the InprocServer32 key for the .NET assembly references the Mscoree.dll file instead of the DLL that you build, a dialog box prompts you to enable or disable macros for Mscoree.dll.

To test the custom Smart Tag Recognizer/Action DLL in Word, follow these steps:

1. Start Instant Messenger, and log on.
   
   NOTE: The sample Smart Tag requires that you log on to Instant Messenger; if you are not logged on to Instant Messenger, the custom DLL loads but does not recognize any contacts.
2. Start Word 2002. On the Tools menu, point to Macro, and then click Security. Set the macro security to Medium, and then click OK. If the macro security setting was previously set to High, restart Word.
3. Type the friendly name of a contact in a new document (for example, John Smith), and then press ENTER. A faint line appears under the friendly name to indicate that it is recognized as a Smart Tag. Move the pointer over the friendly name, and the Smart Tag Action button appears.
4. Click the Smart Tag button, and select one of the custom action items from the drop-down menu. You can send an e-mail or instant message to the contact from your new document.

You can use similar steps to test the Smart Tag DLL in Excel 2002.

Troubleshooting

If you have problems getting your custom Smart Tags to work, first verify that the custom Smart Tag DLL is being loaded. In Word or Excel, on the Tools menu, click Auto Correct Options, click the Smart Tag tab, and verify that Label Text with Smart Tags is selected and that your Smart Tag DLL is listed and selected. If your Smart Tag is not listed, it may not be properly registered.

If the execution of the custom Recognizer or Action class is the source of the problem, you can debug a Smart Tag DLL as you would any Visual Studio .NET DLL. From Project Properties, click Configuration Properties and then click Debugging. Select Start External Program and specify the path to Winword.exe. Set a breakpoint in the New method for the class item you want to debug. When Excel or Word starts and loads the Smart Tag, your code breaks at the breakpoint and you can step through the code for debugging.

Your Smart Tag DLL should trap and handle any run-time errors. If an error is raised in your code and the error is not handled, Office immediately unloads the DLL and clears the item so that it is not loaded again. This behavior is the same as the way Office treats COM Add-ins, and can give you the impression that Office is not loading the DLL when it is in fact doing so, but was forced to unload it because of an unhandled run-time error.

For more information about how to use CLSIDs to register the Smart Tag DLL instead of ProgIDs, click the following article number to view the article in the Microsoft Knowledge Base: For more information, see the following Microsoft Developer Network (MSDN) Web site: