This documentation is archived and is not being maintained.

Walkthrough: Creating a Smart Tag by Using a Document-Level Customization

Applies to

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.

Project type

  • Document-level projects

Microsoft Office version

  • Word 2003

  • Word 2007

For more information, see Features Available by Application and Project Type.

This walkthrough demonstrates how to create a smart tag in a document-level customization for Word. The smart tag recognizes Fahrenheit temperature strings. The smart tag includes an action that converts the temperature value to Celsius, and replaces the recognized text with a formatted Celsius temperature string.

To run this smart tag, end users must enable smart tags in Word. For more information, see How to: Enable Smart Tags in Word and Excel.

This walkthrough illustrates the following tasks:

  • Creating a smart tag that recognizes a regular expression.

  • Creating an action that retrieves data from the smart tag and modifies the recognized smart tag text.


Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

You need the following components to complete this walkthrough:

  • Visual Studio Tools for Office (an optional component of Visual Studio 2008 Professional and Visual Studio Team System).

  • Microsoft Office Word 2003 or Microsoft Office Word 2007.

Visual Studio Tools for Office is installed by default with the listed versions of Visual Studio. To check whether it is installed, see Installing Visual Studio Tools for Office.

The first step is to create a Word Document project.

To create a new project

Visual Studio opens the new Word document in the designer and adds the My Smart Tag project to Solution Explorer.

The project needs a reference to the smart tag DLL, and also needs to use regular expressions.

To configure your project

  1. On the Project menu, click Add Reference.

  2. On the COM tab, select Microsoft Smart Tags 2.0 Type Library and click OK.

  3. In Solution Explorer, right-click ThisDocument.vb (in Visual Basic) or ThisDocument.cs (in C#), and then click View Code.

  4. Add the following line of code to the top of the file.

    Imports System.Text.RegularExpressions

    using System.Text.RegularExpressions;

To enable the smart tag to find and convert Fahrenheit temperature strings, add a regular expression to the list of terms that the smart tag recognizes, and create an action that will be available when the user clicks the smart tag.

To create the smart tag

  1. Replace the ThisDocument_Startup event handler in the ThisDocument class with the following code. This code creates a SmartTag that represents the Visual Studio Tools for Office smart tag, and adds a regular expression to the list of terms that the smart tag recognizes.

    private Microsoft.Office.Tools.Word.Action action1;
    private void ThisDocument_Startup(object sender, System.EventArgs e)
        Microsoft.Office.Tools.Word.SmartTag smartTag1 =
            new Microsoft.Office.Tools.Word.SmartTag(
            "Demonstration Smart Tag");
        smartTag1.Expressions.Add(new Regex(
  2. Create a new Action and add it to the Actions property of the smart tag. The Action represents an item that the user can click in the smart tag menu.

    action1 = new Microsoft.Office.Tools.Word.Action(
        "Convert to Celsius");
    smartTag1.Actions = new
        Microsoft.Office.Tools.Word.Action[] {action1};
  3. Attach the smart tag to the document by adding the SmartTag to the VstoSmartTags property. In C#, attach an event handler to the Click event of the action.

        action1.Click += new

The event handler retrieves the Fahrenheit temperature value from the key number, which is in the property bag of the smart tag. The event handler then converts the Fahrenheit temperature value to Celsius, and replaces the recognized string.

In this example, the key number identifies a captured group from the regular expression assigned to the smart tag. For more information about property bags and regular expressions in Visual Studio Tools for Office smart tags, see Smart Tags Architecture.

To create the event handler

  • Copy the following code to the ThisDocument class.

    void action1_Click(object sender,
        Microsoft.Office.Tools.Word.ActionEventArgs e)
        string value = e.Properties.get_Read("number");
        double fahrenheit = System.Convert.ToDouble(value);
        int celsius = (int)(fahrenheit - 32) * 5 / 9;
        e.Range.Text = celsius.ToString() + "�C";

Now you can test your document to make sure that the smart tag converts Fahrenheit temperatures to Celsius.

To test your workbook

  1. In Word, enable smart tags.

    For more information, see How to: Enable Smart Tags in Word and Excel.

  2. Press F5 to run your project.

  3. Type a string that conforms to the regular expression you added to the smart tag, such as 60F, 60° F, or 60 F.


    To type a degree symbol (°), press ALT and type 248.

  4. Click the smart tag icon that appears over the recognized string, and then click Convert to Celsius.

  5. Confirm that the original string is replaced with a new string that contains the temperature in Celsius.