Back in August of 2006, I wrote an article about calling .NET components from PowerBuilder using COM wrappers (i.e., CCW). Since I was basing it on a registry entry approach, the technique demonstrated required the component to be added to the GAC, which in turn required that we create a strong name and sign the assembly (besides having it compiled as a COM-visible assembly).
You don't always have access to the GAC or the registry of the machine that you need to deploy your application to. Well, fortunately we have some options. Beginning with Windows XP and Windows Server 2003, the Microsoft operating systems allowed the use of manifest files rather than registry entries for loading COM components. It not only works for regular COM components, but for .NET components that have been exposed as COM-visible. The only difference is how the manifest file is structured.
If you want further information on the details, I'd recommend the following resources:
- How to: Configure .NET-Based Components for Registration-Free Activation:
http://msdn2.microsoft.com/en-us/library/eew13bza%28VS.80%29.aspx - Registration-Free Activation of .NET-Based Components: A Walkthrough:
http://msdn2.microsoft.com/en-us/library/ms973915.aspx - Simple COM server registration:
www.simple-talk.com/dotnet/.net-framework/simple-com-server-registration/In particular, I'd recommend the following tool, which generates one of the required manifest files for you:
- Genman32 - a tool to generate Sxs manifest for managed assembly for Registration Free COM/.NET Interop:
http://blogs.msdn.com/junfeng/archive/2007/04/14/genman32-a-tool-to-generate-sxs-manifest-for- managed-assembly-for-registration-free-com-net-interop.aspx
We actually need two manifest files. We'll only deploy one because the other one is going to be compiled into our .NET assembly.
Component Manifest
The Component Manifest is the first of the manifest files, and the one that will get compiled into the .NET assembly. Actually Windows Server 2003 lets you deploy it as a separate file alongside the assembly. However, since Windows XP requires it to be part of the assembly, and because it's just a better practice, we'll compile it into the assembly.
You can use the Genman32 utility referenced above to automatically create the file for you, or you can simply create it by hand. I'll assume the later to indicate what the different portions of the file do. A manifest is a text file in XML format, so you start off by creating an empty text file with the same name as the assembly except it ends in .manifest rather than .dll. The first two lines of the file are the standard XML file declaration and the standard declaration for a manifest file. That is followed by the assemblyIdentity that identifies this assembly. It has at least two values, the name of the assembly and its version, as specified in the project settings.
Listing 1 - DotNetSMTP.manifest file
<assemblyIdentity
name="DotNetSMTP"
version="0.0.0.0__
/>
<clrClass
clsid="{4599956A-2686-3D5F-8F14-9E7F45832B6C}"
name="DotNetSMTP.DotNetSMTP"
progid="DotNetSMTP.DotNetSMTP"
threadingModel="Both"
runtimeVersion="v2.0.50727__>
The next section of the file is where we associate the CLSID, PROGID, and ThreadingModel information that we would normally provide through registry entries. CLSID must match the GUID value that was used in the assembly. Because we're working in the clrClass tag, we know that this is a managed .NET-based COM component. You can use the Registration Free Activation approach with unmanaged code as well, but there's a different tag that the information for those component is provided in.
Note that as with all XML, the tag names are case-sensitive. One minor mistake in either of the manifest files will result in an error message at runtime, often "This application has failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem." Fortunately, more information about the specific problem is recorded in the System event log under a "SideBySide" source. For example, if I entered the assemblyIdentity tag as assemblyidentity (all lower case), the event log would show:
Syntax error in manifest or policy file "dotnetinteropsmtp.exe.Manifest" on line 7. The element assemblyidentity
appears as a child of element urn:schemas-microsoft-com:asm.v1^assembly which is not supported by this version of
Windows.
Now that we have a manifest file for the assembly, we need to compile it into the assembly. To do that, we need to create a resource file that references the manifest file. So create another empty text file, except that this one has a .rc extension. You then add the following three lines of code, one of which includes the reference to the manifest file:
DotNetSMTP.rc file
#include
#define MANIFEST_RESOURCE_ID 1
MANIFEST_RESOURCE_ID RT_MANIFEST DotNetSMTP.manifest
You can add the resource file to your VS project as an existing file, but it isn't necessary.
Now we need to compile the resource file. We do that with the .NET Resource Compiler (rc.exe), using the following at a command prompt:
set include=C:\Program Files\Microsoft Visual Studio 8\VC\PlatformSDK\Include
rc DotNetSMTP.rc
The result is a file called DotNetSMTP.res that we need to pass to the .NET C# compiler using the /win32res option to instruct it to add it to the assembly. Unfortunately, there's no place in the VS IDE to specify this, so what we do instead is create a one-line batch file that does the compile for us. Simply create a build.cmd file with the following command in it:
csc /t:library /out:\DotNetSMTP.dll /win32res:DotNetSMTP.res DotNetSMTP.cs
The isn't literal. You put the directory that you want the compiled assembly stored in there (e.g., bin/Debug).
Note that the Genman32 isn't only capable of generating the manifest file for you; it can also embed it directly in the assembly as well.
Application Manifest
Now that we have all the COM information we need to access the component, we need to tell the application to look in the assembly for it. To do that we use an Application Manifest file. Once again it's a text file in XML format and begins with the same two initial lines.
Listing 2 - Application Manifest file
name = "dotnetinteropsmtp"
version = "1.0.0.1__
processorArchitecture="x86__
/>
<assemblyIdentity
name="DotNetSMTP"
version="0.0.0.0__
/>
The assemblyIdentity section now identifies our application. Note that if you want to be able to test this from the PowerBuilder IDE, you'd need to create such a manifest file for it (or modify the already existing one). That is followed by a dependency section, and within that a dependentAssembly section. Note that the information in the dependentAssembly section must match the information in the Component Manifest file or the application won't be able to locate the component.
That's essentially it. At this point you can put the DotNetSMTP.dll file and Application Manifest file in the same directory as the application. Absolutely no changes are needed to the PowerBuilder code (or to the VS code for that matter, except for removing the signing information from the project options). When PowerBuilder attempts to create the COM component (the CCW), the Windows operating system will note that there is a dependent assembly defined in the application manifest and attempt to determine if that assembly is the one needed to instantiate the component. Since it is, it then uses the information in the manifest file embedded in the assembly to activate the component.
--This article was originally published on PBDJ.
Comments (1)