Printer Friendly Version      Send     
Click to Rate and Give Feedback
Related Articles
This article presents an overview of the motivation behind new techniques that decompose problems into independent pieces for optimal use of parallel programming.

By David Callahan (October 2008)
We take a look at planned support for parallel programming for both managed and native code in the next version of Visual Studio.

By Stephen Toub and Hazim Shafi (October 2008)
Here we describe some of the more common challenges to concurrent programming and present advice for coping with them in your software.

By Joe Duffy (October 2008)
Here is an ASP.NET AJAX data-driven Web application that takes the best features from server- and client-side programming to deliver an efficient, user-friendly experience.

By Bertrand Le Roy (October 2008)
More ...
Articles by this Author
Web standards are about much more than closing HTML tags. They are a critical factor in how well software components can be used in future contexts.

By Ben Waldron (April 2007)
How does Visual Studio 2005 Team System and Team Foundation Server facilitate the process of agile development and continuous integration? Here Ben Waldron explains it all.

By Ben Waldron (March 2006)
Efficient testing can require many different machine and server configurations but the effort needed to manage these test environments can take a toll. Microsoft Virtual Server 2005 simplifies the provisioning and management of testing environments. This article demonstrates how the extensive Virtual Server COM API can be used to create an automated application testing environment to make your testing chores a whole lot easier.

By Ben Waldron (August 2004)
More ...
Popular Articles
See how to build a document-level Visual Studio Tools for Office customization and integrate it with a content type in SharePoint.

By Steve Fox (May 2008)
Microsoft Robotics Studio is not just for playing with robots. It also allows you to build service-based applications for a wide range of hardware devices.

By Sara Morgan (June 2008)
In this article, author John Torjo presents a guide to his C++ GUI library called eGUI++ and explains how it makes user interface programming easier.

By John Torjo (June 2008)
In this article, the author explores how the F# language helps you create asynchronous function libraries that can be called seamlessly from any other .NET-compliant language.

By Chance Coble (October 2008)
More ...
Read the Blog
Well designed code keeps things that have to change together as close together in the code as possible and allows unrelated things in the code to change independently, while minimizing duplication in the code. In the October 2008 issue of MSDN Magazine, Jeremy Miller shows you some design ...
Read more!
The process for ink capture and analysis on the Tablet PC is straightforward in managed code. To the uninitiated developer, however, creating unmanaged Tablet PC applications can be rather daunting. In the October 2008 issue of MSDN Magazine, Gus Class a quick introduction to the Tablet PC ...
Read more!
Multicore systems are becoming increasingly prevalent, but the majority of software today will not automatically take advantage of this additional processing ability. And multithreaded programming, for anything but the most trivial of systems, is incredibly difficult and error prone today. In the October 2008 issue of MSDN ...
Read more!
Concurrent programming is notoriously difficult, even for experts. You have all of the correctness and security challenges of sequential programs plus all of the difficulties of parallelism and concurrent access to shared resources. In the October 2008 issue of MSDN Magazine, David Callahan describes ...
Read more!
A major advantage of AJAX and Silverlight applications is that they can transparently and continuously interact with a back-end service. The problem is that they run over HTTP, which wasn't designed with security in mind. In the September 2008 issue of MSDN Magazine, Dino Esposito shows you ...
Read more!
Unhandled exception processing shouldn't be a mystery. It's actually quite useful since it gives a crashing application an opportunity to perform last-minute diagnostic logging about what went wrong. In the September 2008 issue of MSDN Magazine, Gaurav Khanna discusses how ...
Read more!
More ...
New information has been added to this article since publication.
Refer to the Editor's Update below.

Smart Tags
Realize the Potential of Office 2003 by Creating Smart Tags in Managed Code
Ben Waldron

This article discusses:
  • New smart tag features in Office 2003
  • MOSTL schema for easy smart tag creation
  • Developing smart tags using managed code
  • Smart tag debugging and deployment
This article uses the following technologies:
Office, COM, C#
Smart tags were first introduced in Microsoft® Office XP as an integrated way to enable users to dynamically present additional information in their documents. For general users of Office, smart tags are a way to boost productivity by having actions linked to keywords. For corporate users, smart tags are used to link users to internal resources based on the type of data they view or input into Office applications. A good example is linking a purchase order number in an Excel spreadsheet to detailed information about the sale from a source on the company intranet. For developers, smart tags represent a new way to link information-driven services into the applications that clients spend most of their time using.
I polled developers in my community and found that most of them recognized the benefits of smart tags but had not yet taken steps to develop them or to use the Microsoft .NET Framework to do so. While many developers are excited about the prospect of building managed smart tags, developing smart tags using .NET has not received the attention it deserves.
In this article I'll demonstrate how to develop smart tags. I'll cover topics such as using the Microsoft Office Smart Tag List (MOSTL) XML schema to develop smart tags quickly as well as using the .NET Framework to create more advanced, managed smart tags for Office 2003 and Office XP. Then I'll talk about how you can deploy these features in your organization.

Smart Tag History
Smart tags came onto the scene in Office XP with full support in Word, Excel, and Microsoft Outlook® (when Word is used as the e-mail editor, which is the default). Microsoft Internet Explorer 5.0 and above support smart tags in a manner that's different from Office applications. Text is not recognized by smart tags automatically in these versions of Internet Explorer; however, custom HTML tags can be added to the HTML source file to enable recognition of text for which you want to have a smart tag action. In this first iteration, smart tags for Office XP were developed using the Microsoft Smart Tag 1.0 Type Library.
The simplicity of smart tags is what makes them so powerful. The smart tag must first recognize data as matching some important criteria and should then present the user with a menu list of actions that pertain to that data. When the user makes a selection, the appropriate action is taken. Two COM classes comprise a smart tag. A recognizer class is responsible for matching data passed by a smart tag-enabled application; an action class tells the application the menu items to display and executes an action when the application signals the action to be taken. The general interaction between the application and these classes is shown in Figure 1.
Figure 1 Smart Tag Interfaces 
Based on customer feedback Microsoft made enhancements to smart tags with the release of Office 2003. The number of applications that support smart tags has been expanded to include Microsoft PowerPoint® and Microsoft Access. Besides broader application support, the next iterations of smart tags include some better usability options. In Office XP, smart tags supported only one level of menus when displayed, but now cascading menus are included to group actions within the smart tag menu. The ability to control the period of time that smart tags are active, and allowing users to disable them from a single configuration window are also included in Office 2003. Another feature that developers have asked for is the ability to know what application is calling the smart tag. This enables you to handle recognition and actions one way if the request comes from Word and another if it comes from Excel. For a complete list of new smart tag features in Office 2003, go to What's New with Smart Tags in Office 2003.
Microsoft Smart Tags 2.0 Type Library, which is used to develop smart tags for Office 2003, is completely backward compatible with Office XP. All features that existed in Office XP will work with smart tags developed using the new type library, which is very nice for organizations that run both Office XP and Office 2003.

MOSTL Schema
Simple smart tags that come to mind involve recognizing a word and then linking that word to a Web site. Building this type of smart tag is as easy as constructing an XML file. In Office XP and Office 2003 there is a library named MOFL.dll (C:\Program Files\Common Files\Microsoft Shared\Smart Tag\MOFL.dll) that allows developers to build XML files that conform to the MOSTL schema to build tags with no coding necessary.
The MOSTL schema is used when you want to build smart tags where well-defined words or patterns are recognized and where relatively simple actions are executed once recognition occurs. A new feature in Office 2003 allows developers to use regular expressions to recognize a pattern instead of just a list of terms. For example, you can write a smart tag that can recognize an IP address and develop an action that will go to a Web site listing who owns that IP address. While this may not be practical for a business user, it does illustrate the power of MOSTL combined with regular expressions. This type of pattern recognition can be used in most businesses as unique formatted codes are commonly used for order numbers, tracking numbers, and other identifiers. The MOSTL XML that performs IP address recognition and action is shown in Figure 2.
XML that is produced for a smart tag must strictly conform to the MOSTL schema and must be a valid XML document. This means that all characters within XML must be properly escaped. The beginning of the MOSTL schema deals with setting up the smart tag so that it is recognized as a valid smart tag, setting the locale, and creating the ability to update the smart tag from a Web site at some frequency. The most important XML tags create the regular expression to be recognized and also the action that is to be taken when a user clicks on an action in the smart tag. In this case, when an IP address is recognized and the user clicks on the "Find WhoIs for IP" action in the smart tag, they are taken to the WhoIs registry for that particular IP address, as shown in Figure 3.
Figure 3 Tag 
Using the MOSTL XML schema is a fast way to create smart tags. Deploying a new smart tag involves copying the XML file to the location where Office is installed. By default, copying the file to C:\Program Files\Common Files\Microsoft Shared\Smart Tag\LISTS or a subdirectory for a specific locale will make it available to a user. This can be done using an installation application, group policy, or through a software update service such as Microsoft System Management Service.

Creating a Smart Tag Library
Oftentimes, it is not quite so easy to link recognized data to the appropriate action so a developer might need to add more programming logic than the MOSTL schema affords. As mentioned earlier, most businesses use unique identifiers for purchase orders, tracking shipments, or products for sale. More often than not, linking these identifiers to meaningful information involves deriving information from multiple sources, and to be more valuable, aggregating the data for the user. A user with a sales order identifier can quickly see the customer, price paid, shipping information, and purchase history without ever having to leave Office. In cases like this, it is necessary to build a library that implements the interfaces required to create a smart tag. Creating a simple smart tag involves implementing defined interfaces and, as with any software project, gets more complicated as more logic is needed to perform advanced functions. Building a managed smart tag allows developers to take advantage of all the features of the .NET Framework that they have been accustomed to.
Before creating a smart tag library, I would like to describe the functionality in my smart tag library example. Being a fan of major league baseball, it would be helpful to recognize terms that relate to teams. Once these terms are recognized, I can link them to various Web sites to show team standing, averages, and other information that a baseball fan might want to see. This smart tag will have to have some internal logic to determine the correct team to link to. For instance, if I match the word "Sox" in the smart tag, then I may have to present the user with choices to the Web site for the Chicago White Sox or the Boston Red Sox.
This major league baseball smart tag will be written using Visual Studio® .NET 2003. The first step to building a managed smart tag is to create a new Class Library project and add a reference to the COM Microsoft Smart Tags 2.0 Type Library, shown in Figure 4.
Figure 4 Microsoft Smart Tags 2.0 Type Library List 
Adding this reference allows smart tags to be created for both Office 2003 and Office XP. Referencing this library automatically wraps the COM library for use by the .NET Framework without requiring the developer to do any more work. The library that will be produced needs to be registered for COM Interoperability, so doing this within Visual Studio .NET will assist with debugging and deployment once the library is produced.
The two aforementioned classes that are required for the smart tag are the recognizer class, responsible for recognizing text or patterns that exist within applications that support smart tags, and the action class, which determines the menus that are shown to the user and the appropriate operation that corresponds with a menu item. I will first explore how to develop a recognizer class and then build the action class.

Recognizer Class
A recognizer class interfaces with the smart tag infrastructure using COM, so it is necessary to add the System.Runtime.InteropServices namespace to include the necessary attributes for COM integration with .NET-based applications. The Microsoft.Office.Interop.SmartTag namespace is also imported so that my Msdn.MlbSmartTag.Recognizer class can easily implement the appropriate interfaces, as shown here:
using System;
using System.Runtime.InteropServices;
using Microsoft.Office.Interop.SmartTag;

namespace Msdn.MlbSmartTag
{
    [ProgId("MlbSmartTag.Recognizer")]
    [GuidAttribute("90D62E8D-79E3-4197-907F-BF3EC133698D")]
    [ComVisible(true)]
    public class Recognizer : ISmartTagRecognizer2, ISmartTagRecognizer
    ...
There are three important attributes that decorate my Recognizer class. The ProgId attribute allows you to specify the programmatic identifier that can be used when the class is registered with COM. More important, though, is GuidAttribute, which forms a unique class ID (CLSID) for the class. When deploying the library, it is possible to use either ProgId or the CLSID to register the interface, but it's recommended that you use the CLSID to avoid a problem in Office XP where the status flag does not update when registering the interface using the ProgId. The ComVisible attribute is added to the class to ensure that it can be seen as a type in COM.
A recognizer class must implement the ISmartTagRecognizer2 and ISmartTagRecognizer interfaces. Visual Studio .NET will include the stubs for implementing the necessary interfaces, which makes it very easy to fill in the necessary logic to complete the recognizer class.
Figure 5 shows a complete list of the properties and methods to implement the interfaces for a valid recognizer. The SmartTagName property is used to uniquely identify the recognizer, as well as serving as the action key when text is recognized and sent to the corresponding action class. The SmartTagName is formed by using a namespace URI, and then adding the smart tag name separated by a pound sign. In this example the SmartTagName is urn:schemas-microsoft-com:msdnmag#mlb. It is important that this name does not conflict with any other SmartTag name that is deployed within the same environment. This name is also very important when building an action class since the smart tag name serves at the glue that binds the recognizer to the action. These names must be the same; otherwise the two classes will not be properly linked together.
It is important to remember that all COM-accessible .NET classes must provide a default constructor; that is, a constructor that requires no parameters. COM object creation functions do not pass parameters to the objects that they create so you need to ensure that the default constructor is present.
The SmartTagInitialize method is used to perform any initialization necessary when the smart tag recognizer is loaded. In the example, a list of team names are initialized into an array and that will serve as the terms that should be recognized. It should be mentioned that there are many other ways to recognize terms other than a simple list of tokens. Regular expressions are typically used to match patterns such as unique identifiers, while programming logic can be used to retrieve data or determine other match criteria. A good example of this is the Person Name Smart Tag that is included with Office. This smart tag retrieves a list of names from Outlook Contacts for recognition and allows the user to quickly send an e-mail, schedule an appointment, or see if that user is currently online. By performing this sort of setup and information retrieval in SmartTagInitialize, performance of the smart tag recognizer can be improved, since it can access the cached data rather than having to query for it on every recognition request.
The Recognize2 method (see Figure 6) is where the bulk of the responsibility exists for this class. The calling app passes to this method the text to be recognized, the locale, and type of data where the text was found in the app. The data type is set based on the text's surrounding context. The type would be IF_TYPE_CELL if it is found within a cell in Excel, and IF_TYPE_PARA if it is within a paragraph in Word. Some new parameters have also been added that did not exist in the original Recognize method. The calling app name allows a recognizer to perform alternate recognition based on the application, and a tokenized list of text items has been added to assist in developing match algorithms.
The Recognize2 method loops through all of the tokenized text passed to it by the calling application to try to find a match. If a match is found, a smart tag property bag is created to let you add more properties for the text that is matched. The RecognizerSite2 is responsible for interfacing with the calling app. The CommitSmartTag2 method passes the property bag and the location where the recognition occurred within the app. A call to this method causes the app to call the corresponding Action class along with the property bag to display the menu that lists possible actions.

Action Class
Building my Msdn.MlbSmartTag.Action class is similar to building my Recognizer class. Figure 7 shows the most important properties and methods needed to build the Action class. The same namespaces are necessary to make the class accessible to COM and to use the smart tag interfaces. It is important to note that the ProgId and GuidAttribute should not be the same as the values in my Recognizer class (they are, after all, different COM classes), so it is necessary to create a new unique identifier that will be the CLSID for the Action class.
The Action class implements two interfaces from the Smart Tag 2.0 Type library: ISmartTagAction2 and ISmartTagAction. As with a recognizer class, all the properties and methods are necessary and Visual Studio .NET will generate stubs when adding the interfaces to the class declaration, as shown here:
using System;
using System.Runtime.InteropServices;
using Microsoft.Office.Interop.SmartTag;

namespace Msdn.MlbSmartTag
{
  [ProgId("MlbSmartTag.Action")]  
  [GuidAttribute("63CB4201-3387-47c3-B0B2-0CCF56BB892D")]
  [ComVisible(true)]
  public class Action : ISmartTagAction2, ISmartTagAction
  ...
Figure 8 lists the properties and methods used by an Action class. Some properties are the same as those in the recognizer class but there are a few that deserve more attention. As I mentioned in the recognizer discussion, the SmartTagName property value must be the same in an Action class as it is in the corresponding recognizer so that the calling application can forward the request to the appropriate action handler.
The ShowSmartTagIndicator property is used to determine whether the underline indicator should be shown in order to signal to the user that the smart tag has been recognized and has action(s) associated with it. Typically, this property is always set to true, but based on the calling application or locale, it might be set to not show the indicator.
The VerbCount property is set to the maximum number of actions that the smart tag will display. In the example, a simple check is made to make sure that the correct smart tag is calling this property and then the value 4 is returned because the Smart Tag Action menu has four possible actions.
The VerbCaptionFormID2 property does a substantial amount of work for an action class. Based on the value set in the VerbCount property, this property is called repeatedly, each time with a different VerbID. It is responsible for creating the text that will de displayed in the Smart Tag Action menu. Cascading menus are a new feature in Office 2003. Using the "///" delimiter in the text that is returned by the property will apportion the text into submenus.
The first time the VerbCaptionFromID2 property is called, the value of VerbID will be 1 and the appropriate case statement is called. It is important to note that if you are using the VerbIndex as the VerbID (as in the example), the beginning index for VerbIndex is 1 rather than 0. This is something that can sometimes cause issues for those accustomed to doing development primarily with the .NET Framework. Custom logic is embedded in this property to handle the case where the word "Sox" is recognized. This is because we do not know if the user wanted to match the Boston Red Sox or the Chicago White Sox.
The IsCaptionDynamic property comes into play when the menu that is displayed to the user changes because of some value. If the menus for the action do not change, then this property should be set to false. For this example, we display a different menu based on what has been recognized so this property is set to true. These dynamic menus are one of the reasons why this smart tag is being built as a library rather than using the MOSTL schema.
The capstone to a smart tag is when a user clicks on a menu item to invoke an action. This is handled by the InvokeVerb2 method and is where developers can provide the horsepower for doing interesting things. The VerbID, application name, property bag, and recognized text are passed to this method. New to the InvokeVerb2 method is the locale so that developers can more easily build multilingual applications.
The example InvokeVerb2 is relatively straightforward and serves as a good example. Based on the menu item that the user selected, a browser opens the appropriate Web page. A user who types in "Cubs" or "Chicago Cubs" can navigate quickly to their stats. (If they are a Cubs fan like me then they will no doubt be disappointed—a common theme for us Cubs fans.)
There are countless other actions that can be taken when a user clicks a smart tag action. Using the .NET Framework to create the smart tag increases the possibilities by allowing you to do virtually anything that you can already do in .NET. This includes calling Web services, querying a database, and finding other interesting ways to add value to the data in Office documents.
One other feature of Office 2003 that is complementary to smart tags is the Office Research pane. The Research pane gives developers a place to display information to users without having to leave Office. Smart tags offer a nice link to notify users that they can view more information in the Research pane. For further information, see John Durant's article on storing and searching instant messages using the Research pane in Research Services in this issue of MSDN Magazine.

Debugging Tools
There have been some tools released recently that help developers debug and test smart tags without having to test directly within Office applications. The first utility, called the Smart Tag Explorer, enables developers to view all of the smart tag recognizers and actions that are configured on the local system. This is especially useful for ensuring that registration has completed successfully and that the smart tags are enabled on the system. It also shows which applications are configured to run the smart tags along with other settings, such as where to check for updates and the color of the smart tag indicator.
Another priceless utility is the Smart Tag Recognize Tester. This utility can be run from the Smart Tag Explorer and is used to test the recognition functionality. This utility is a time saver when the recognition logic is complicated and you want to quickly test a variety of data to be recognized. Both of these utilities are managed applications, so it is very easy to attach to them with a debugger in order to quickly step through the code to debug or test the smart tag. It's easy to see how the interface for the Smart Tag Recognize Tester, shown in Figure 9, can be helpful for debugging and testing by indicating the text and offsets of the recognition. These tools are available for download at Introduction to the Smart Tag Explorer and Smart Tag Recognize Tester.

Deployment
Now that you have developed the functionality of the smart tag, it is just as important to get it in the hands of the users who need it. Deploying a smart tag that has been developed using the MOSTL schema involves copying the XML file to all the machines that need the smart tag. MOSTL also lets you set the frequency and location where updates can be downloaded from a Web site.
Deploying smart tags libraries is not as simple because the library must be registered and Windows registry keys must be created to allow the application to know that the smart tag exists. Creating a managed smart tag library provides the ability to modify the registry using the ComRegisterFunctionAttribute when the library is registered using the Register Assembly (regasm.exe) app.
The are only two registry keys that are needed to allow the smart tag to run: one for the recognizer (HKEY_CURRENT_USER\Software\Microsoft\Office\ Common\ Smart Tag\Recognizers\{CLSID}) and one for the action (HKEY_CURRENT_USER\Software\Microsoft\Office\ Common\Smart Tag\Actions\{CLSID}). The unique identifier created for each class is placed into the appropriate sub key. The code in Figure 10 demonstrates how to ensure that these correct keys are placed in the registry for the recognizer class when the library is registered. It also shows the UnregisterFunction for when the library is unregistered.
Having the registry keys applied when the library is registered simplifies deployment. Copying the library to the clients and registering it can be accomplished in a variety of ways. The first is to build an installation for the smart tag library and allow users to install it themselves. Other ways include deploying the library via group policy or other software update applications that exist in the environment to which you are deploying.
[ Editor's Update - 2/8/2005: While registering managed smart tags for COM interop is a great way to get them up and running quickly, developers are strongly advised to isolate their managed smart tags from other managed Office add-ins. .NET provides isolation through the means of application domains, and loading each smart tag into its own application domain will improve the overall stability of the host application. Office 2003 provides for this separation through the Microsoft Visual Studio Tools for the Microsoft Office System loader. It's easy to use and represents the correct way to deploy managed smart tags. Moreover, the Visual Studio Tools for Office loader leverages the .NET security model, providing tighter security for managed add-ins. For more information on designing, developing, and deploying Office XP and Office 2003 add-ins implemented with the .NET Framework, see Information about designing Office XP add-ins and Office 2003 add-ins by using the .NET Framework and Support for Managed-Code Smart Tags. Additionally, the documentation at Isolating Office Extensions with the COM Shim Wizard discusses another way of implementing application domain isolation through the use of a C++ shim.]

Security
When creating a smart tag developed with the .NET Framework in Office XP, the library was subject to Office security checks based on a digital signature. Unfortunately, the .NET runtime engine (Mscoree.dll) is not digitally signed for Office. This meant that it was possible for users to see a macro security dialog box when using smart tags. The workaround for Office XP was to develop an unmanaged shim to call the .NET component.
In Office 2003, it is no longer necessary to develop an unmanaged shim because Office 2003 allows smart tags and other managed add-ins to be subject to the .NET security policy instead of to the Office security checks. The Visual Studio Tools for Office loader, which is included with Office 2003, loads the managed smart tag and is subject to Office security checks instead of the managed code—another good reason to start building managed smart tags.

Conclusion
There are many great uses for smart tags, and the tags are easily built using the MOSTL schema. Using the .NET Framework to build smart tags makes it easier to link Office users to external data quickly and intuitively. Likewise, building managed smart tags makes it simpler to deploy smart tags to users who need them.

Ben Waldron is a founding partner at Pollinate Media, an Interactive Branding and Innovation Company located in Portland, Oregon. Ben can be contacted for questions or opportunities via e-mail: ben.waldron@pollinatemedia.com.

© 2008 Microsoft Corporation and CMP Media, LLC. All rights reserved; reproduction in part or in whole without permission is prohibited.
Page view tracker