Monday, August 4, 2008

COM Shared Ad-in (Part 8)

Using the Wizard for Managed COM Add-Ins: A Walkthrough Exercise

Download COMShimWizardSetup.msi, which contains the wizard as well as the Sample HelloWorld Application.

The COM Shim Wizard behavior described in this walkthrough exercise is representative of all five of the extension types.

In this exercise, you create an example shim for a managed IDTExtensibility2 COM add-in. This is the most commonly used type of managed Microsoft Office extension, and it requires the most input from the developer to establish the precise registry requirements.

  1. After you install the COM Shim Wizard, start Visual Studio 2005. On the File menu, point to New, and then click Project. In the New Project dialog box, expand the Visual C++ Projects node, and select the child node, COM Shims, as shown in Figure 1.

Selecting the Addin Shim project in Visual Studio 2005 (click to see larger image)

Figure 1. Selecting the Addin Shim project in Visual Studio 2005 (click picture to see larger image)

  1. Select Addin Shim, and specify a name and location. For this exercise, you can accept the default name and location. Click OK. The wizard runs the COMShimHarvester component, which displays the Specify the Managed Add-in Assembly page of the COM Shim Wizard.
  2. If you know the full path to the managed extension assembly for which you want to create a shim, you can type it into the first text box. Alternatively, click Browse and navigate to the assembly. For this exercise, you can use the sample add-in (TestAddin.dll) provided with the download.
  3. Select the assembly, TestAddin.dll, and click Open. The COMShimHarvester opens the assembly (by way of the AppDomainHarvester helper assembly), harvests information, and populates the text boxes in this page of the wizard.
  4. The COMShimHarvester component of the wizard harvests the name and public key token of the assembly and the name of the class that implements IDTExtensibility2. By default, it also uses the original GUID and ProgId values, as shown in Figure 2.

Harvested assembly information with the original GUID and ProgId

Figure 2. Harvested assembly information with the original GUID and ProgId

Note If for some reason you do not want to use the same GUID and ProgId values for your shim as for your add-in, clear the check box for this option. If you clear the check box, the COMShimHarvester generates new values. But, we recommend that you reuse the original GUID and ProgId instead of the wizard-generated ones. If you do not, then both the managed extension assembly and the shim DLL are registered. In this situation, your tests pick up one or the other, depending on the GUID and ProgId you use in your test harnesses. This is usually not desired behavior.

  1. Click Next to open the Add-in Details page of the wizard, in which you can specify additional information to enter into the registry (Figure 3). This information includes a suitable description and friendly name, the load behavior of the add-in, and the list of target host applications.
  2. By default, the wizard sets the add-in to load when the Microsoft Office application starts. This effectively sets the registry LoadBehavior to 3. You can change this if you want a different setting. Also by default, the wizard uses the fully qualified type name of the class that implements the target interface as the basis for both the description and friendly name. You can change these, as appropriate, for your project. Figure 3 shows the Add-in Details page with user-specified choices completed.

Specifying registry information for the add-in

Figure 3. Specifying registry information for the add-in

  1. Click Next to display the Summary page of the wizard, which summarizes the choices you made (Figure 4).

Wizard summary page for new add-in assembly

Figure 4. Wizard summary page for new add-in assembly

  1. Click Finish to generate the new shim project and code. In the Visual Studio Solution Explorer, the shim project should include approximately 15 source files, as shown in Figure 5. The exact number of files varies according to the type of extension for which you are developing a shim.

Source files for the add-in shim project

Figure 5. Source files for the add-in shim project

To validate that the solution is working as expected with the shim in place, you should exercise your full test schedule. Before you can do this, however, there is one manual step that you must take. Important :-

The wizard cannot make any assumptions about where you deploy the add-in solution, but because the shim currently requires the extension assembly to be either in the same folder as the shim or to be deployed to the global assembly cache, you should copy or move the extension assembly to the same folder as the shim before you test the solution.

To do this you need to do the following

  1. In the solution explorer right click the Shim Project
  2. Click the properties
  3. It will open the Property Pages, In general change the OuputDirectory to the Release folder of add-in DLL.
  4. Click ok.

· Sign the Shim Project with a Strong Name Key

To do this you need to do the following

2. In the solution explorer right click the Shim Project

3. Click the properties

4. It will open the Property Pages, under Linker click the advanced tab.

5. In the keyfile option give : $(ProjectDir)/YourShimKey.snk[make sure that the keyfile is duly created and placed in the Project Directory]

6. Click ok to exit.

Your next step is to modify the setup project so that you can deploy the product in the target machines.

· Remove the existing Primary Output of the Add-in Project.

· Add assembly to the setup and deployment project

The managed COM add-in DLL is one of the files that needs to be included in the setup and deployment project. To do this:

  1. In the Solution Explorer, right-click on the newly created Setup project.
  2. Point to Add. Click Assembly. This displays the Component Selector dialog box.
  3. Click Browse and locate ..\bin\release\.[of your project]
  4. Select sampleAddin.dll. Click Open.

sampleAddin.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 COM add-in shim the primary output of the setup and deployment project. The shim will be the signed unmanaged component that will be registered.

  1. In the Solution Explorer, right-click the Setup project.
  2. Point to Add. Click Project Output. This displays the Add Project Output Group dialog box.
  3. In the Project drop-down menu, select AddInShim.
  4. In the list box, click Primary Output.
  5. Click OK.

· Set the primary output registration property

The signed COM add-in shim registration details need to be added to the registry. The keys and values that need to be registered are specified in the ConnectProxy.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.

  1. In the Solution Explorer, under the Setup project node, right-click Primary Output from AddInShim and then click Properties to view its property details.
  2. In the Properties box, in the Register drop-down menu, select vsdrpCOMSelfReg.

· Set the assembly registration property

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

  1. Under the Setup project node, right-click sampleAddin.dll and then click Properties to view its property details.
  2. In the Properties box, under the Register drop down menu, make sure vsdraDoNotRegister is selected.

No comments: