Deploying Interop User Controls

As with InteropForm assembles, Interop UserControls must be registered on the client computer. You can deploy them using the same techniques described in the topic Hybrid Application Deployment, or if you are deploying to computers running Windows XP or later, you can deploy them side-by-side using the techniques described later in the topic.

For an example of deploying with a Visual Studio .NET Setup and Deployment project, see How To: Deploy a Hybrid Application.

Note: In most cases it is easier to deploy using the methods described in How To: Deploy a Hybrid Application. Deploying with Reg-Free COM requires more effort, but works best when you want to have a minimal impact to your existing setup package (i.e. a Setup created using the Package & Deployment Wizard). Since no additional registry entries are required, deploying your new application is as simple as updating your package to copy the new .NET .dlls and .manifest file to the application folder.

Deploying Side-by-side with Reg-Free COM

Windows XP provides a mechanism known as Reg-Free COM for deploying COM objects without requiring registry entries. This allows you to deploy Interop UserControls as .dll files that install in the same directory as your application .exe. If you include a .manifest file in the application directory, the .exe can find and use the Interop UserControl even though it is not registered as a COM object. This also allows you to deploy your Visual Basic 6.0 application using the newer ClickOnce deployment technology, which does not support COM registration.

Note The Interop UserControl will still need to registered on the development machine, since Visual Basic 6.0 pre-dates Reg-Free COM.

In order to deploy your Interop UserControl with Reg-Free COM, you will need both a client manifest (for the application) and a private assembly manifest (for the UserControl). The private assembly manifest is automatically generated by the Visual Basic 6.0 Interop UserControl template, but you need to create the client manifest yourself and add it to your Visual Basic 6.0 application directory.

You can create the manifest file in the XML editor in Visual Studio .NET, or you can create it using a text editor such as Notepad. The following is an example of a client manifest:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <assemblyIdentity type="win32" name="MyApp" version="1.0.0.0" processorArchitecture="x86" />
        <dependency>
            <dependentAssembly>
                 <assemblyIdentity type="win32" name="MyUserControl" version="1.0.0.0" />
            </dependentAssembly>
        </dependency>
</assembly>

The name "MyApp" should be replaced by the name of your Visual Basic 6.0 .exe, and the name "MyUserControl" should be replaced by the name of your Interop UserControl .dll; the .exe and .dll extensions should not be included. In addition, the version numbers should be updated to match the versions of your .exe and .dll.

The manifest file must be named MyApp.exe.manifest, where MyApp is the name of your Visual Basic 6.0 .exe. During deployment, the .exe, the client manifest, and the .dll must all be installed to the same directory on the client computer. When the application loads, Windows inspects the manifest and determines that the application uses Reg-Free COM, and then loads the .dll from the specified location.

Private Assembly Manifest

The Visual Basic 6.0 Interop UserControl template creates a private assembly manifest for your control named InteropUserControl.manifest. In most case you will never need to touch this file, but if you make changes to the name of the project or the class you will need to update the manifest to reflect your changes. You will also need to update this file if you add more than one Interop UserControl to your project (the first clrClass entry is automatically filled in, but additional ones must be added manually). The following is an example of a private assembly manifest; the italicized elements are the ones that might need to be changed:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<assembly xmlns="urn:schemas-microsoft-com:asm.v1"
manifestVersion="1.0">
<assemblyIdentity
            type="win32"
            name="MyUserControl"
            version="1.0.0.0" />
      <clrClass

clsid=" {Insert GUID here}"

progid="MyUserControl.MyUserControlClass"

threadingModel="Both"

name=" MyUserControl.MyUserControlClass" >

</clrClass>

<clrClass

clsid=" {Insert GUID here}"

progid="MyUserControl.SecondUserControlClass"

threadingModel="Both"

name=" MyUserControl.SecondUserControlClass" >

</clrClass>
</assembly>

In the above example, the value for clsid would be the ClassID found in your COM registration section of the UserControl.vb file. For progid and name, MyUserControl would be the name of your UserControl assembly, and MyUserControlClass would be the name of your UserControl class. To add multiple UserControls in a single assembly, add a <clrClass> element for each UserControl.

In addition, there is a hidden file named InteropUserControl.rc that must be updated when you change the project or class name. You can view this file in Solution Explorer by choosing Show All Files. The following is an example of the .rc file; the italicized elements are the ones that might need to be changed:

#define RT_MANIFEST 24

1 RT_MANIFEST MyUserControl.manifest

101 BITMAP MyUserControl.bmp

For more information about Reg-Free COM, see How to: Configure .NET Components for Registration-Free Activation.