Using the Smart Tag Shim Solution to Deploy Managed Smart Tags in Office XP

Article
06/14/2014

Click here to download sample - odc_stshim.exe.Click here to download sample - stsdk.exe. This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Misha Shneerson and Siew-Moi Khor
Microsoft Corporation

May 2002

Applies to:
Microsoft® Office XP

Summary: How to use the smart tag shim solution template to enable secure managed smart tags deployment in Office XP. (13 printed pages)

Download Odc_stshim.exe.

Introduction
Download the Smart Tag Shim Solution and Managed Smart Tag Sample
Procedure for Incorporating the Unmanaged Smart Tag Shim into a Managed Smart Tag Project
Insert the Correct Assembly, Public Key Token, Recognizer, and Action Proxy Class Values
Checklist and Notes
Conclusion

Introduction

Deploying and installing managed code smart tags securely in Microsoft® Office XP currently requires the assembly be hosted in an unmanaged smart tag proxy component called a shim. The explanation on what a shim is and why it is currently needed to deploy smart tag DLLs has been discussed in detail in Deployment of Managed COM Add-Ins in Office XP and therefore won't be repeated here. This article will concentrate on how to use the smart tag shim solution template so that you can successfully deploy your managed smart tags under the highest Office XP security setting.

It's assumed that the reader:

Has read Deployment of Managed COM Add-Ins in Office XP.
Knows what a smart tag is, and how to build, deploy, and install one. For more information about smart tags, see the Microsoft Office XP Smart Tag SDK 1.1.
Knows how to build managed smart tags using Microsoft Visual Studio® .NET. This article does not include a tutorial on how to build one. However, there is a list of references at the end of the article that you can go to for examples.
Knows how to strong name an assembly.
Knows what code signing is and how to code sign. For information on how to code sign, the Digital Code Signing Step-by-Step Guide has detailed step-by-step instructions and explains how to code sign using Microsoft Authenticode® technology.
Is familiar with Microsoft .NET security, and .NET and COM Interop.

Download the Smart Tag Shim Solution and Managed Smart Tag Sample

The first thing you need to do is download the smart tag shim solution and managed smart tag sample on a machine that has the .NET Framework, Visual Studio .NET, and Office XP installed:

Download odc_stshim.exe and run this self-extracting archive to save the odc_stshim.msi and stshimChecklist.xls files on your local machine.
- stshimChecklist.xls—a checklist to help you keep track of the tasks that need to be accomplished when using the smart tag shim solution.
- odc_stshim.msi—contains the smart tag shim solution template and sample managed smart tag.
Install the odc_stshim.msi and save the download in a folder named SmartTagShimTutorial, that is, c:\SmartTagShimTutorial.

If you examine the c:\SmartTagShimTutorial folder after you have installed the MSI, you should find three subfolders in that folder: SmartTagShim, HelloSmartTagVB, and HelloSmartTagVBSetup.
- SmartTagShim folder—contains the smart tag shim solution project written in unmanaged Microsoft Visual C++®. To view this project, open SmartTagShim.sln and the project will open up in Visual Studio .NET.
- HelloSmartTagVB folder—contains a simple managed smart tag Microsoft Visual Basic® .NET project. The name of the smart tag assembly is HelloSmartTagVB. This project will be used to demonstrate how to add the smart tag shim to a managed smart tag project. To view this project, open HelloSmartTagVB.sln located in C:\SmartTagShimTutorial\HelloSmartTagVB\.
- HelloSmartTagVBSetup folder—contains the managed HelloSmartTagVB smart tag installer project.

Test the Managed Smart Tag DLL

Before incorporating the smart tag shim into the managed smart tag project, let's first test the managed HelloSmartTagVB smart tag in Microsoft Word. The managed HelloSmartTagVB smart tag is a very simple smart tag sample that recognizes only one word and that is Hello.

Prepare Office XP Security Settings

Before installing the managed HelloSmartTagVB smart tag DLL, the security settings in Microsoft Word should be set to Medium, with the Trust all installed add-ins and templates settings disabled.

Note After you are done testing, you can reset these security settings to whatever level they were at prior to testing by making the appropriate changes in the Security dialog box as shown in the steps below.

To change the security settings:

Start Microsoft Word.
On the Tools menu, point to Macro, and then click Security. This displays the Security dialog box.
On the Security Level tab, click Medium.
Click the Trusted Sources tab. Uncheck Trust all installed add-ins and templates.
Quit Word.
Repeat the steps above with Microsoft Excel. Also make sure smart tags are enabled in Excel. To enable smart tags in Excel, on the Tools menu, click AutoCorrect Options and then click the Smart Tags tab. Check the Label text with smart tags box.

Install the Managed HelloSmartTagVB Smart Tag DLL

Before installing the managed HelloSmartTagVB smart tag DLL, close all instances of Microsoft Word, Microsoft Excel, and Microsoft Outlook® that are currently open. To install the smart tag, do the following:

To open the HelloSmartTagVB project in Visual Studio .NET, open the HelloSmartTagVB.sln file located at C:\SmartTagShimTutorial\HelloSmartTagVB.
You should find two projects in the Solution Explorer of the Visual Studio .NET IDE: HelloSmartTagVB and HelloSmartTagVBSetup.
First, build the managed smart tag by right-clicking on the HelloSmartTagVB project and then clicking Build.
Next build the managed smart tag setup project by right-clicking on the HelloSmartTagVBSetup project and then clicking Build.
You can now install the smart tag by right-clicking on the HelloSmartTagVBSetup project and then clicking Install. This will launch the HelloSmartTagVBSetup setup wizard.
Click Next.
In the Select InstallationFolder dialog box, type C:\SmartTagShimTutorial\ in the Folder edit field.
Click Next.
Click Next. This installs the managed HelloSmartTagVB smart tag.
Click Close.

Test the Managed HelloSmartTagVB Smart Tag DLL

Open Word. You should see a security warning dialog box like the one shown in Figure 1. This security warning is displayed because mscoree.dll—the main entry point of the common language runtime engine—is not signed.
If in the Prepare Office XP Security Settings section above you had set the security level to High with the Trust all installed add-ins and templates settings disabled, you won't get this security warning at all. This is because Office XP automatically disables all unsigned components when security is set at its highest.

Figure 1. Security dialog box warning that mscoree.DLL is not signed
Click Enable.
On the Tools menu, click AutoCorrect Options. This displays the AutoCorrect dialog box.
Click the Smart Tags tab.
You should see VBHello, which is the recognizer for the HelloSmartTagVB smart tag listed in the Recognizers box.
Type Hello in Word. It should be smart tagged.
Click on the Smart Tag Action button and select an action.

Uninstall the Managed HelloSmartTagVB Smart Tag DLL

Close all instances of Word, Excel, and Outlook that are open.
Back in the Solution Explorer of the Visual Studio .NET IDE, uninstall the HelloSmartTagVB smart tag by right-clicking on the HelloSmartTagVBSetup project and then clicking Uninstall.
This will uninstall the HelloSmartTagVB smart tag. Double-check this in Word by clicking the Tools menu, clicking AutoCorrect Options, and then clicking the Smart Tags tab. The VBHello recognizer should not be in the Recognizers list.

Remove the HelloSmartTagVBSetup Project

The HelloSmartTagVBSetup project was included to make it easy for you to install and test the managed HelloSmartTagVB smart tag DLL. Before incorporating the unmanaged smart tag shim into the managed HelloSmartTagVB project, remove the HelloSmartTagVBSetup project.

To do this, in the Solution Explorer, right-click on the HelloSmartTagVBSetup project and then click Remove.
Click OK.

Procedure for Incorporating the Unmanaged Smart Tag Shim into a Managed Smart Tag Project

We have broken down the procedure to six main steps as listed below.

Add the SmartTagShim project to your managed smart tag project.
Set the Smart Tag Shim properties.
Incorporate the correct assembly name, public key token value, recognizer, and action class names.
Generate GUIDs for the Smart Tag Shim Type Library, and unmanaged smart tag recognizer and action proxy classes.
Rebuild the solution.
Sign the modified unmanaged smart tag shim DLL, and if you are doing delay signing, the managed smart tag DLL.
Create an MSI using the setup and deployment project.
Test the MSI.

Add the SmartTagShim Project to Your Managed Smart Tag Project

The first thing you need to do is add the smart tag shim to your managed smart tag project in Visual Studio .NET. As an illustration, we will be using the HelloSmartTagVB assembly as an example. If you have your own smart tag assembly handy, you may use that instead if you like.

Note You can still continue to make changes to your managed smart tag code even after you have added the smart tag shim to the project. Development on your smart tag assembly doesn't have to be frozen; it can continue in parallel.

In the Solution Explorer, right-click Solution "HelloSmartTagVB" (1 project).
Point to Add.
Click Existing Project.
Locate C:\SmartTagShimTutorial\SmartTagShim\SmartTagShim.vcproj.
Click Open. This will add a project which contains the unmanaged smart tag shim to your solution in Visual Studio .NET.

Set the Smart Tag Shim Properties

Since the smart tag shim is a template, you will need to change certain smart tag shim properties, for example the name of the shim, to avoid name collision. The properties that you need to change are as follows:

In the Solution Explorer, right-click the SmartTagShim project.
Click Properties. This will display the SmartTagShim Property Pages dialog box.
Under General configuration properties, change the Output Directory so that the smart tag shim DLL will be created in the same folder as the HelloSmartTagVB assembly. Type the following value in the Output Directory edit box: ..\HelloSmartTagVB\Bin.

Note Make sure there are only two dots preceding \HelloSmartTagVB\Bin. If, for example, you accidentally put three dots instead, compilation will return an error.
Rename the SmartTagShim.dll to avoid name collision. In this example, we will rename it to HelloSmartTagVBShim.dll. To do this, in the Linker configuration properties, under Output File, type the following value:
$(OutDir)/HelloSmartTagVBShim.dll.
Click OK.
In the Solution Explorer, open the Resource Files folder of the SmartTagShim project.
Double-click SmartTagShim.rc to display the Resource View—SmartTagShim window.
Open the Version folder.
Double-click VS_VERSION_INFO to display the version information.
Click InternalName and change the shim name from SmartTagShim.dll to its new name: HelloSmartTagVBShim.dll.
Do the same for OriginalFileName. Change it from SmartTagShim.dll to HelloSmartTagVBShim.dll.

Insert the Correct Assembly, Public Key Token, Recognizer, and Action Proxy Class Values

Again, because the smart tag shim is a template, the assembly name, public key token value, recognizer, and action proxy class names are only samples. They need to be changed to correctly match the real names.

Assembly Name

In the Solution Explorer, open the Source Files folder of the SmartTagShim project.
Double-click ShimConfig.cpp.
Replace the sample assembly nameSTManagedProjin
```
static LPCWSTR szSmartTagsAssemblyName = L"STManagedProj, 
   PublicKeyToken=6c96c7507b8e2be8";
```
with the correct smart tag assembly name. For this particular tutorial, the assembly name is HelloSmartTagVB.

Public Key Token

First retrieve the HelloSmartTagVB.dll assembly public key token. To do this, click Start, point to Programs, point to Microsoft Visual Studio .NET, point to Visual Studio .NET Tools, and click Visual Studio .NET Command Prompt.
In the Visual Studio .NET Command Prompt window, go into the HelloSmartTagVB\bin folder by typing cd C:\SmartTagShimTutorial\HelloSmartTagVB\bin as shown in Figure 2.
Retrieve the public key token of the HelloSmartTagVB assembly using the sn –T command line option. To do this, after
C:\SmartTagShimTutorial\HelloSmartTagVB\bin>
type sn –T HelloSmartTagVB.dll as shown in Figure 2.

Figure 2. Command line options to retrieve the public key token (click thumbnail for larger image)
Copy the public key token, which in this case is 4abf65dfc60ff309.

Note To be able to copy quickly, make sure the command prompt properties are set correctly. To check this, right-click the Visual Studio .NET Command Prompt title bar and click Properties. In the Options tab, make sure both the QuickEdit Mode and Insert Mode boxes are checked.

To copy, press and hold the primary mouse button to highlight the GUID value you want to copy. Then click the secondary mouse button to copy the selected text to the Clipboard.

Replace the sample public key token value6c96c7507b8e2be8in the ShimConfig.cpp file with 4abf65dfc60ff309 in

static LPCWSTR szSmartTagsAssemblyName = L"HelloSmartTagVB, 
   PublicKeyToken=6c96c7507b8e2be8";

It should now read:

static LPCWSTR szSmartTagsAssemblyName = L"HelloSmartTagVB, 
   PublicKeyToken=4abf65dfc60ff309";

Recognizer Class Name

In the ShimConfig.cpp file, replace the sample recognizer class name in

static LPCWSTR szRecognizerClassName = L"STManagedProj.STRecognizer";

with the correct full recognizer class name. For this particular tutorial, it is HelloSmartTagVB.HelloSTRecognizer. After you have done that, it should look as follows:

static LPCWSTR szRecognizerClassName =
  L"HelloSmartTagVB.HelloSTRecognizer";

Action Class Name

In the ShimConfig.cpp file, replace the sample action class name in

static LPCWSTR szActionClassName = L"STManagedProj.STAction";

with the correct full action class name. For this particular tutorial, it is HelloSmartTagVB.HelloVBAction. After you have done that, it should look as follows:

static LPCWSTR szActionClassName = L"HelloSmartTagVB.HelloVBAction";

Generate GUIDs for the Smart Tag Shim Type Library Unmanaged Smart Tag Recognizer and Action Proxy Classes

The GUIDs for the smart tag shim type library, and the smart tag recognizer and action proxy classes in the shim template are samples. To avoid possible GUID collision, the sample GUIDs must be replaced with newly created ones. To generate GUIDs, you can use the uuidgen utility.

Generate GUID for the unmanaged smart tag recognizer proxy class:

In the Visual Studio .NET Command Prompt window, after C:\SmartTagShimTutorial\HelloSmartTagVB\bin>
type uuidgen as shown in Figure 3. This generates a GUID.

Figure 3. Generating a GUID using the uuidgen utility (click thumbnail for larger image)
Copy the GUID to the Clipboard.
In the Solution Explorer, open the SmartTagShim project's Resource Files folder, and then double-click the STRecognizerProxy.rgs file.
Replace the sample recognizer proxy class CLSID with the GUID you just generated in step 2 in two places.

First under the HKCR hive in:
```
ForceRemove {56705B5D-2FFA-453B-82DB-CE7F25326B8A} = s
  'STRecognizerProxy Class'
```
and then in the HKCU hive at:
```
ForceRemove {56705B5D-2FFA-453B-82DB-CE7F25326B8A}
```
replace the highlighted CLSID with the GUID you just generated using the uuidgen utility.

Open the SmartTagShim project's Source Files folder. Double-click SmartTagShim.idl. Replace the sample recognizer class CLSID highlighted below with the GUID you just generated in step 2 at:
```
[
    uuid(56705B5D-2FFA-453B-82DB-CE7F25326B8A),
    helpstring("STRecognizerProxy Class")
]
```

Generate GUID for the unmanaged smart tag action proxy class:

In the Visual Studio .NET Command Prompt window, after C:\SmartTagShimTutorial\HelloSmartTagVB\bin> type uuidgen. This generates a GUID.
Copy the GUID to the Clipboard.
Back in the Solution Explorer, expand the SmartTagShim project Resource Files folder, and then double click on the STActionProxy.rgs file.
Replace the sample action class CLSID with the GUID you generated in step 1, in two places.

First under the HKCR hive in:
```
ForceRemove {56705B5D-2FFA-453B-82DB-CE7F25326B8A} = s 
  'STActionProxy Class'
```
and then in the HKCU hive at:
```
ForceRemove {56705B5D-2FFA-453B-82DB-CE7F25326B8A}
```
replace the highlighted CLSID with the GUID you just generated using the uuidgen utility.
Open the SmartTagShim project's Source Files folder. Double-click on SmartTagShim.idl. Replace the sample action class CLSID highlighted below with the GUID you just generated in step 2 at:
```
[
    uuid(EECB21D6-8B59-4582-8A5C-F6AC47D0F088),
    helpstring("STActionProxy Class")
]
```

Generate GUID for the unmanaged Smart Tag Shim 1.0 Type Library:

In the Visual Studio .NET Command Prompt window, after C:\SmartTagShimTutorial\HelloSmartTagVB\bin>
type uuidgen. This generates a GUID.
Copy the GUID to the Clipboard.
In the Solution Explorer, open the SmartTagShim project's Source Files folder. Double-click SmartTagShim.idl.
Replace the sample unmanaged Smart Tag Shim Type Library CLSID highlighted below with the GUID you just generated in step 1 at:
```
[
    uuid(DE6A3742-4874-44D9-BD8C-0784D2AAFFAB),
    version(1.0),
    helpstring("SmartTagShim 1.0 Type Library") 
]
```

Build the Solution

Close all instances of Word, Excel, and Outlook that are open.
In the Solution Explorer, right-click the SmartTagShim project, and then click Rebuild.

Sign the Unmanaged Smart Tag Shim DLL and Managed Smart Tag DLL (If You Are Doing Delay Signing)

Authenticode sign the smart tag shim DLL. You have renamed the shim to HelloSmartTagVBShim.dll in step 4 of the Set Smart Tag Shim Properties procedure, so HelloSmartTagVBShim.dll would be the DLL you want to Authenticode sign.
If you are doing delay signing on your assembly, now is the time to complete the signing.

Create an MSI Using the Setup and Deployment Project

It is highly recommended that you build an MSI to install the managed smart tag along with the smart tag shim you intend to deploy to the public. In Visual Studio .NET, it is very easy to build one.

Create setup and deployment project

In the Solution Explorer, right-click Solution "HelloSmartTagVB" (2 projects).
Point to Add.
Click New Project. This will display the Add New Project dialog box.
In the Project Types frame, click Setup and Deployment Project.
In the Templates frame, select Setup Project.
In the Name edit field, rename the project to HelloSmartTagVBwShimSetup.
Click OK.

Add assembly to the setup and deployment project

The managed smart tag DLL now needs to be included in the setup and deployment project. To do this:

In the Solution Explorer, right-click the newly created HelloSmartTagVBwShimSetup project.
Point to Add. Click Assembly. This displays the Component Selector dialog box.
Click Browse and locate C:\SmartTagShimTutorial\HelloSmartTagVB\bin.
Select HelloSmartTagVB.dll. Click Open. HelloSmartTagVB.dll is now added to the Selected Components edit box in the Component Selector dialog box.
Click OK.

Add project output to the setup and deployment project

Make the smart tag shim the primary output of the setup and deployment project. The shim will be the signed unmanaged component that will be registered.

In the Solution Explorer, right-click the HelloSmartTagVBwShimSetup project.
Point to Add. Click Project Output. This displays the Add Project Output Group dialog box.
In the Project drop-down menu, select SmartTagShim.
In the list box, click Primary Output.
Click OK.

Set the primary output registration property

The signed smart tag shim registration details need to be added to the registry. The keys and values that need to be registered are specified in the STActionProxy.rgs and STRecognizerProxy.rgs files. These keys and values are then compiled into the DLL file to enable a process known as self registration to be performed, which is usually handled by the regsvr32 utility. To enable self registration to be performed from within the installation package, the Register property of the smart tag shim must be set to vsdrpCOMSelfReg.

In the Solution Explorer, under the HelloSmartTagVBwShimSetup project node, click Primary Output from SmartTagShim to view its property details.
In the Properties box, in the Register drop-down menu, select vsdrpCOMSelfReg.

Set the assembly registration property

The managed smart tag doesn't need to be registered for COM interop since it will be called from within the shim.

Under the HelloSmartTagVBwShim project node, click HelloSmartTagVB.dll to view its property details.
In the Properties box, under the Register drop-down menu, make sure vsdraDoNotRegister is selected.

Exclude unneeded dependency files from the setup and deployment project

It is important that you exclude unneeded dependency files from your project. Examples of unneeded dependency files are MSTAG.TLB and shdocvw.dll. MSTAG.TLB is the smart tag type library file and shdocvw.dll is the Microsoft Internet Explorer control file. A target machine that has Office XP and Internet Explorer installed would also have MSTAG.TLB and shdocvw.dll installed.

If you don't exclude these files and the target machine has them already, the MSTAG.TLB and shdocvw.dll that you packaged will overwrite the registration of already installed components. Consequently, when users uninstall your solution, the smart tag and Internet Explorer controls' registration will be broken, thus leaving the users' machines without Automation support for those components.

To exclude these files, in the Detected Dependencies folder of the HelloSmartTagVBwShimSetup project:

Right-click shdocvw.dll.
Verify if the Exclude property for shdocvw.dll is unchecked. If it is, click Exclude to check it.

Note Be sure not to accidentally exclude ShDocVw.dll. ShDocVw.dll is not the same as shdocvw.dll. ShDocVw.dll is an Internet Explorer interop assembly whereas as mentioned earlier, shdocvw.dll is an Internet Explorer control. In the Solution Explorer you can tell them apart by looking at the icons. The shdocvw.dll icon is shaped like a file and the ShDocVw.dll icon is a rectangular shape.
Right-click MSTAG.TLB.
Verify if the Exclude property for MSTAG.TLB is unchecked. If it is, click Exclude to check it.

Note SmartTagLib is a smart tag interop assembly.

Build the MSI

Now you are done including all the needed files, excluding the unneeded files, and resetting properties of the setup project. You are ready to build an MSI. To do this, right-click the HelloSmartTagVBwShimSetup project. Click Build. This creates a HelloSmartTagVBwShimSetup.msi.

Test the MSI

In this example, the HelloSmartTagVBwShimSetup.msi you have just created will be in the c:\SmartTagShimTutorial\HelloSmartTagVBwShim\Debug folder. Test the MSI thoroughly before deploying it.

Checklist and Notes

For your convenience, a checklist has been created to help you keep track of the tasks that need to be accomplished when using the smart tag shim solution template. To reference the checklist, open the stshimChecklist.xls file included in the download discussed in the Download the Smart Tag Shim Solution and Managed Smart Tag Sample section.

A few important points to remember and note:

It is important for security reasons to never fail to include the public key token in the ShimConfig.cpp file. By specifying the assembly strong name and, especially, its public key token (while keeping the corresponding private key secret) will ensure that the assembly to be loaded is the intended one.
Your smart tag assembly should not register for COM Interop. This is because the assembly will be called from the shim and as such does not need to be registered for COM Interop. To disable register for COM Interop property, in the assembly property pages dialog box, open the Configuration Properties folder and click Build. Uncheck the Register for COM Interop box.
Even after adding the smart tag shim to your assembly project, you can still continue developing your smart tag assembly. The content of your assembly doesn't have to be frozen. Development can continue in parallel.
The shim DLL must be signed with Authenticode.
Your smart tag assembly must be signed with a strong name.
Strongly name other private assemblies that the COM add-in assembly might depend on.

Conclusion

By incorporating the smart tag shim solution template to your managed smart tag project, you will be able to deploy your smart tag assembly to end users even when their Office XP security is set at High with Trust all installed add-ins and templates disabled. You will be able to digitally sign the shim DLL and therefore comply with the Office XP security signature checking mechanism. In addition, you will have some level of control over what the common language runtime does.

For examples on how to build smart tags in a .NET language, the following articles have more information: