Deploying a Serviced Component

   

---

The two main steps to deploy a serviced component are as follows :

1. Register the serviced component with the COM+ catalog The three different ways for registration are as follows:

   • Lazy Registration The .NET Framework automatically registers a serviced component with the COM+ catalog, when the component is requested for the first time. The registration of a component requires administrative privileges, and the component registration will fail if the first user of that application does not have administrative privileges. This option can be used while developing or testing a component but is not a good idea for deployment.

   • Manual Registration You can use the Component Services administrative tool ( regsvcs.exe ) to manually register a serviced component with the COM+ catalog. This technique of registration is useful in combination with XCOPY deployment of the serviced component.

   • Programmatic Registration You can use the RegistrationHelper class to programmatically register a serviced component with the COM+ catalog. This registration technique is what you will use when creating a Windows Installer-based setup package for the deployment of a serviced component.

2. Install the serviced component assembly at a location where the CLR can locate it Where the CLR locates an assembly also depends on the program that makes the request to an assembly. Therefore, the installation location might depend on how the component is registered with the COM+ catalog. If the component is registered as

   • Library Application Then the serviced component is created in the process of the calling application. In this case, the serviced component might be deployed as a private application within the calling application directory structure. But if the serviced component is used by multiple calling applications, instead of introducing redundancy by copying the serviced component in the directory of each calling application, a better idea is to install the serviced component in the GAC.

   • Server Application Then the serviced component is created in the process of dllhost.exe , which is located in the Windows System directory. Obviously, the GAC is also a better installation choice in this case.

From the preceding list, it is clear that, in most cases, you should install a serviced component assembly in the GAC. You should also either use the Component Services administrative tool for the registration of the serviced component in the COM+ catalog, or you should use the RegistrationHelper class when programmatically registering a serviced component; for example, when registering through a setup program. I already covered the basics of COM+ catalog registration in Chapter 7, "Component Services," in which I discuss the use of the Component Services administrative tool.

In this chapter, I cover the following two techniques to deploy a serviced component:

• Using a Visual Studio .NET Setup and Deployment Project

• Using the Component Services administrative tool

Deploying a Serviced Component Using a Visual Studio .NET Setup and Deployment Project

Step By Step 10.18 shows how to deploy a serviced component. In this exercise, you'll use a Visual Studio .NET setup project to deploy a serviced component. If the serviced component is deployed as a part of a Web application, you can also use a Web Setup project for its deployment.

STEP BY STEP

10.18 Creating a Setup Project for the NorthwindSC Serviced Component

1. Add the existing Windows service project StepByStep7-8 ( NorthwindSC , created in Chapter 7) to the solution.

2. Right-click the project StepByStep7-8 and choose Add, Add New Item from the context menu. The Add New Item dialog box appears. Select Installer Class from the right pane. Name the new class NorthwindSCInstaller.vb .

3. Add a reference to the System.Windows.Forms.dll to the StepByStep7-8 project using the Add Reference dialog box.

4. Open the NorthwindSCInstaller.vb file in the code view and add the following Imports directives:

    Imports System.EnterpriseServices Imports System.Reflection Imports System.Windows.Forms 

5. Add the following code after the Component Designer generated code section in the class definition:

    Public Overrides Sub Install(_  ByVal stateSaver As System.Collections.IDictionary)     Try         Dim app As String         Dim tlbimp As String         ' Get the location of the assembly         Dim a As [Assembly]         Dim sa As [Assembly]         Dim i As New Integer()         sa = a.GetAssembly(i.GetType())         Dim scassembly As String = sa.Location         ' Install the assembly in the COM+ catalog         Dim rh As RegistrationHelper = _          New RegistrationHelper()         rh.InstallAssembly(scassembly, _          app, tlbimp, _          InstallationFlags. _          FindOrCreateTargetApplication)         ' Save the application name and assembly         ' location in the InstallState file         stateSaver("application") = app         stateSaver("scassembly") = scassembly     Catch ex As Exception         MessageBox.Show(_             ex.Message, "Install Exception")     End Try End Sub Public Overrides Sub Uninstall(_ ByVal savedState As System.Collections.IDictionary)     Try         ' Retrieve the application name and assembly         ' location from the InstallState file         Dim app As String = _          CStr(savedState("application"))         Dim scassembly As String = _          CStr(savedState("scassembly"))         ' Uninstall the assembly from the COM+ catalog         Dim rh As RegistrationHelper = _          New RegistrationHelper()         rh.UninstallAssembly(scassembly, app)     Catch ex As Exception     MessageBox.Show(_         ex.Message, "Uninstall Exception")     End Try End Sub 

6. Build the StepByStep7-8 project.

7. Add a new project to the solution. In the Add New Project dialog box, select Setup and Deployment Projects from the Project Types tree and then select Setup Project from the list of templates on the right. Name the project NorthwindSCSetup .

8. In Solution Explorer, right-click the project and select Add, Project Output from the context menu. In the Add Project Output Group dialog box, select StepByStep7-8 as the project and then select Primary Output from the list box. Click OK.

9. Open the Custom Actions Editor for the NorthwindSCSetup project. Right-click the Install node under the Custom Actions node and then select Add Custom Action from the shortcut menu. The Select Item in Project dialog box appears. Look in the Application Folder and select Primary Output from StepByStep7-8(Active). Click OK. The primary output is added to the Install node.

10. Now right-click the Uninstall node and select Add Custom Action from the context menu. The Select Item in Project dialog box appears. Look in the Application Folder and select Primary Output from StepByStep7-8(Active). Click OK. The primary output is now also added to the Uninstall node as shown in Figure 10.33.

    Figure 10.33. You can perform custom actions using the Custom Action Editor.

    

11. Open the File System Editor for the NorthwindSCSetup project. Right-click the File System on Target Machine node and choose Add Special Folder, Global Assembly Cache Folder from the context menu. Right-click the Global Assembly Cache Folder and then select Add, Project Output from the context menu.

12. The Add Project Output Group dialog box appears. Select the StepByStep7-8 project and then select Primary Output from the list of items to be added. Click OK. The File System Editor now appears as shown in Figure 10.34.

    Figure 10.34. You can add files to special folders on the target machine using the File System Editor.

    

13. Open the Registry Editor for the NorthwindSCSetup project. Select the HKEY_LOCAL_MACHINE node and hierarchically add new keys to the node in the order HKEY_LOCAL_MACHINE, Software, Microsoft, .NETFramework, AssemblyFolders, NorthwindSCCorp, as shown in Figure 10.35.

    Figure 10.35. You can set the keys and values in the Registry with the help of the Registry Editor.

    

14. Add a new string value to the newly added NorthwindSCCorp key. Select the value and invoke the Properties window. Empty the Name property. When you do this, the (Default) name of the value is set (see Figure 10.35). Set the Value property to [TARGETDIR] . This is the folder where the assembly file copy is stored, along with the GAC.

15. Select the new project in Solution Explorer. Activate the Properties window. Set Manufacturer to NorthwindSC Corp , ProductName to NorthwindSC Serviced Component , and Title to NorthwindSC Serviced Component Installer .

16. Build the NorthwindSCSetup project. Install the project.

    WARNING

    Working with the Registry Be extra careful when working with the Windows Registry. Take special care with the DeleteAtUninstall property of the Registry Settings Properties. Setting DeleteAtUninstall to true for a wrong key (such as HKEY_LOCAL_MACHINE\SOFTWARE ) might have a very bad impact on the target computer.

17. Open the Component Services administrative tool from the Administrative Tools section of the Windows Control Panel. You should see that the NorthwindSC component in the application Northwind Data Application with Object Pooling is being added to the Component Services on the target machine.

In Step By Step 10.18, you used a custom Installer component to register the serviced component using the RegistrationHelper class. The Installer component is stored in the assembly of the serviced component itself. In the Custom Action editor, you add the output of this project to the Install and the Uninstall node. This instructs the setup program to activate the Install() and Uninstall() methods from the assembly at the time of deployment.

In Step by Step 10.18, you learned how to place assemblies in the GAC. You also learned how to make entries to Windows Registry. You added a Registry, which enables the serviced component assembly to be automatically displayed in the Visual Studio .NET Add Reference dialog box.

Deploying a Serviced Component Using the Component Services Administrative Tool

The Component Services administrative tool provides a Wizard to export a configured application as a Windows Installer package. This tool also provides a wizard to create a new COM+ application based on the information stored in a Windows Installer package. This deployment technique is most useful for transferring already configured COM+ applications from one computer to another. You can export the configured application as a Windows installer package from one computer. Transfer the package to another computer and then use the COM+ Install wizard to create a new COM+ application based on it.

However, this COM+ Install wizard is of little use for installing new serviced components from a Windows installer package created from a Visual Studio .NET Setup Project because COM+ can't recognize that.

Step By Step 10.19 shows how to export a COM+ application as a Windows Installer package.

STEP BY STEP

10.19 Creating an Installation Package for the NorthwindSC Serviced Component Using the Component Services Tool

1. Open the Component Services administrative tool from the Administrative Tools section of the Windows Control Panel.

2. Right-click the Northwind Data Application with Object Pooling (created in StepByStep7-8 ) in the Component Services administrative tool and select Export from the context menu.

3. The Welcome screen of the COM Application Export Wizard appears. Click Next.

4. The second screen of the wizard is the Application Export screen. Enter the full path and filename where the package file needs to be exported, with the extension .msi , as shown in Figure 10.36. Also, in the Export As Group dialog box, select the Server Application option (see Figure 10.36). Click Next and then click Finish.

   Figure 10.36. The Application Export screen of the wizard allows you to specify information required to export the COM+ application.

   

5. Browse to the destination folder, where the package files are exported. You should see that two files, NorthwindSC.msi and NorthwindSC.msi.cab , have been created.

6. Right-click the NorthwindSC.msi installation package in the Windows Explorer and select Install to install the COM+ application.

7. Open the Component Services administrative tool from the Administrative Tools section of the Windows Control Panel. You should see that the COM+ application Northwind Data Application with Object Pooling has been added to the Component Services on the target machine.

Now you have all the settings for the COM+ application as well as the DLL files for the serviced component in the MSI file. Step by Step 10.20 shows how to use the Component Services administrative tool to create a new COM+ application based on the information in the MSI file.

STEP BY STEP

10.20 Installing an Installation Package for the NorthwindSC Serviced Component Using the COM+ Application Export Wizard

1. Open the Component Services administrative tool from the Administrative Tools section of the Windows Control Panel.

2. Right-click the COM+ Applications node and select New, Application from the context menu.

3. The Welcome screen of the COM+ Application Install Wizard appears. Click Next.

4. The second screen of the wizard is the Install or Create a New Application screen. Click the Install Pre-built Application(s) button as shown in Figure 10.37.

   Figure 10.37. The Install or Create a New Application screen of the wizard allows you to install a prebuilt application or create a new application.

   

5. This opens the Install from Application File dialog box. Browse and select the NorthwindSC.msi package created in Step by Step 10.19. The Select Application Files screen of the wizard with the application file appears as shown in Figure 10.38. Click Next.

   Figure 10.38. The Select Application Files screen of the wizard allows you to choose the files for the application you need to install.

   

6. The Set Application Identity screen of the wizard appears. Select the Interactive user option as shown in Figure 10.39. You can also provide a user and password details if you want to install the application with a different identity. Click Next.

   Figure 10.39. The Set Application Identity screen of the wizard allows you to specify the application identity.

   

7. The Application Installation Options screen of the wizard appears. Select the Specific Directory option and specify a desired install directory for the component files as shown in Figure 10.40. Click Next and then click Finish.

   Figure 10.40. The Application Installation Options screen of the wizard allows you to specify the install directory and the role configuration.

   

   You should see that the COM+ application Northwind Data Application with Object Pooling is being added to the Component Services on the target machine.

8. Browse to the install directory selected in step 7. You should see that two component files, StepByStep7-8.dll and StepByStep7-8.tlb , have been created.

The Component Services administrative tool was created before .NET. It, therefore, does not allow you to install the assemblies in the GAC. If you want to use the COM+ Install wizard to install .NET applications, you must also take an extra step to register the serviced component in the GAC.

---

Top