Skip to main content

Documentation

Global navigation

Docs

Documentation

Learn

Q&A

Code Samples

Sign in

kevin13

[email-masked]

Profile

Collections

Challenges

Sign out

Docs

Previous Versions

Articles and Overviews

.NET General

Registration-Free Activation of COM Components: A Walkthrough

Contents

Exit focus mode

Save

Share

Twitter

LinkedIn

Facebook

Email

Table of contents

Search

.NET Framework Deployment

.NET General

Enterprise Development Technology Map

Smart Client Applications Technology Map

Visual Basic .NET Technology Map

Visual Studio .NET Technology Map

Web Applications Technology Map

Application Resiliency: Unlock the Hidden Features of Windows Installer

Auto-Generating Wrapper Classes for Stored Procedures, Part 1: Using the AutoSproc Tool

Auto-Generating Wrapper Classes for Stored Procedures, Part 2: The Internals of the AutoSproc Tool

Beyond (COM) Add Reference: Has Anyone Seen the Bridge?

BITS: Write Auto-Updating Apps with .NET and the Background Intelligent Transfer Service API

Boosting the Performance of the Microsoft .NET Framework

Building Connected Systems: The .NET Framework and the Microsoft Enterprise Application Development Platform

C#: A Message Queuing Service Application

C#: A SQL Server XML and ASP.NET Runtime Application

Choosing Between ClickOnce and Windows Installer

Use Reflection to Discover and Assess the Most Common Types in the .NET Framework

Coding Best Practices Using DateTime in the .NET Framework

Comparing LINQ and Its Contemporaries

Use Design Patterns to Simplify the Relationship Between Menus and Form Elements in .NET

Conversations on .NET

Coroutines: Implementing Coroutines for .NET by Wrapping the Unmanaged Fiber API

Creating a Design Surface Using Windows Forms and GDI+ in Microsoft .NET

Customizing Code Generation in the .NET Framework Visual Designers

Debugging Tool: Build a Logging and Event Viewing Library to Help Debug Your .NET Framework-based App

Design Patterns: Architecture of an Autonomous Application

Designing Knowledge Management Solutions with a Web Storage System

Designing Reader Classes for .NET Documents

Displaying Metadata in .NET EXEs with MetaViewer

Dr. GUI on Visual C++ .NET

An Evaluation of Stored Procedures for the .NET Developer

Full Eiffel on the .NET Framework

Garbage Collector Basics and Performance Hints

Generics FAQ: .NET Framework

Generics FAQ: Best Practices

Generics FAQ: Fundamentals

Generics FAQ: Tool Support

Getting the Most Out of the .NET Framework PropertyGrid Control

Handling Language Interoperability with the Microsoft .NET Framework

Implement a Microsoft Word-like Object Model for Your .NET Framework Application

Implementing XmlReader Classes for Non-XML Data Structures and Formats

Improving String Handling Performance in .NET Framework Applications

Introducing the .NET Framework 3.0

Introducing System.Transactions in the .NET Framework 2.0

Introduction to System.DirectoryServices.ActiveDirectory (S.DS.AD)

Introduction to System.DirectoryServices.Protocols (S.DS.P)

Leveraging the .NET Framework in Measurement and Automation Applications

Link-time Code Generation

LINQ

Make Your Components Really RAD with Visual Studio .NET Property Browser

Microsoft .NET and Windows XP COM+ Integration with SOAP

Microsoft .NET Framework 1.0 Addendum

Microsoft .NET Framework Benchmark Testing Terms

Microsoft Win32 to Microsoft .NET Framework API Map

Migrating 32-bit Managed Code to 64-bit

Monitor Your .NET Applications with Microsoft Operations Manager 2005

Monitoring and Dynamically Configuring Windows Services

Microsoft .NET Framework FAQ

The Microsoft Shared Source CLI Implementation

The Microsoft Shared Source CLI Implementation Refresh

Migrating Native Code to the .NET CLR

Moving Java Applications to .NET

Nested Grids for Hierarchical Data

.NET: Calling Win32 DLLs in C# with P/Invoke

.NET: The CLR's Thread Pool

.NET Framework Support on Windows Operating Systems

.NET Internals: Rewrite MSIL Code on the Fly with the .NET Framework Profiling API

.NET: Introducing Generics in the CLR

.NET: More on Generics in the CLR

The .NET Profiling API and the DNProfiler Tool

.NET Technology Map

New Recommendations for Using Strings in .NET 2.0

Northwind Unplugged

Object Serialization in the .NET Framework

An Overview of Managed/Unmanaged Code Interoperability

Performance Considerations for Run-Time Technologies in the .NET Framework

A Performance Comparison of Windows Communication Foundation (WCF) with Existing Distributed Communication Technologies

Performance Tips and Tricks in .NET Applications

Persisting Application Settings in the .NET Framework

Plug-Ins: Let Users Add Functionality to Your .NET Applications with Macros and Plug-Ins

Primary Interop Assemblies (PIAs)

Profiler Stack Walking in the .NET Framework 2.0: Basics and Beyond

Programming the Thread Pool in the .NET Framework

Providing Custom Layout Engines for Windows Forms

Real-World XML: Manipulate XML Data Easily with Integrated Readers and Writers in the .NET Framework

Registration-Free Activation of .NET-Based Components: A Walkthrough

Registration-Free Activation of COM Components: A Walkthrough

Remoting: Managing the Lifetime of Remote .NET Objects with Leasing and Sponsorship

Reviewing Managed Code

Serving Images from .NET Assemblies

Simplifying Deployment and Solving DLL Hell with the .NET Framework

SOS: It's Not Just an ABBA Song Anymore

TypeRefViewer Utility Shows TypeRefs and MemberRefs in One Convenient GUI

Understanding Enterprise Services (COM+) in .NET

Using MSMQ with Visual Basic .NET

Using .NET Framework Data Provider for Oracle to Improve .NET Application Performance

Using the .NET Framework SDK Interoperability Tools

Using Reflection Emit to Cache .NET Assemblies

Using System.DirectoryServices to Search the Active Directory

Using the ECMA Standards: An Interview with Miguel de Icaza

Using the Microsoft .NET Framework to Create Windows-based Applications

Using Windows Hooks to Enhance MessageBox in .NET

Windows Hooks in the .NET Framework

Writing Faster Managed Code: Know What Things Cost

Writing High-Performance Managed Applications : A Primer

Writing Custom Designers for .NET Components

XSLT: Simplify Development and Maintenance of Microsoft .NET Projects with Code Generation Techniques

.NET Remoting

Upgrading to Microsoft .NET

.NET Framework Version and Assembly Information

Coding4Fun

Dr. GUI .NET

.NET in the Real World

Data Access and Storage

Deployment and Management

Enterprise Services

Identity

Networking and Communication

Smart Client Applications (Windows Forms)

Web Applications (ASP.NET)

Web Services

Windows Communication Foundation

Windows Workflow Foundation

Windows Server AppFabric

Windows Vista

Writing coupled WMI providers using WMI.NET Provider Extension 2.0

XML and the .NET Framework

Registration-Free Activation of COM Components: A Walkthrough

04/30/2007

23 minutes to read

In this article

Introduction

Registration-Free COM Terminology

Running the Sample

Building the Visual C++ COM Server

Building the C++/.NET Client

Registration-Free Activation

The Visual Basic 6.0 COM Server and Client

Incompatible Apartments

Using the Activation Context API

Troubleshooting

Conclusion

Further Reading

Steve White

Premier Support for Developers, Microsoft UK

Leslie Muller

Global IT Research & Development, Credit Suisse First Boston

July 2005

Summary: The Microsoft Platform SDK does an excellent job of documenting the topics of isolated applications and side-by-side assemblies. However, not everyone equates this topic with that of registration-free activation of COM components. Registration-free COM is a platform feature of great interest to enterprises with locked-down servers and applications isolated on shared infrastructures. This article walks through a working example of the registration-free activation of a native COM component by native clients and, via COM interop, by a managed client. (18 printed pages)

Applies to:

Microsoft Windows Server 2003

Microsoft Windows XP

Microsoft .NET Framework version 1.1

Microsoft Visual Studio .NET 2003

Microsoft Visual Studio 6.0

Download the sample that accompanies this article, MSDNRegFreeCOM.msi.

Contents

Introduction

Registration-Free COM Terminology

Running the Sample

Building the Visual C++ COM Server

Building the C++/.NET Client

Registration-Free Activation

The Visual Basic 6.0 COM Server and Client

Incompatible Apartments

Using the Activation Context API

Troubleshooting

Conclusion

Further Reading

Introduction

Registration-free COM is a mechanism available on the Microsoft Windows XP (SP2 for .NET-based components) and Microsoft Windows Server 2003 platforms. As the name suggests, the mechanism enables easy (for example, using XCOPY) deployment of COM components to a machine without the need to register them.

On the target platforms, one of the stages of initializing a process and its dependent modules is to load any associated manifest files into a memory structure called an activation context. In the absence of corresponding registry entries, it is an activation context that provides the binding and activation information the COM run time needs. No special code is required in the COM server or in the client unless you choose to obviate the use of files by building activation contexts yourself using the activation context API.

In this walkthrough I will build a simple native COM component and consume it, both registered and unregistered, from native and managed clients. The component and the native client will be presented in both Visual C++ and Visual Basic 6.0; the managed client will be presented in both C# and Visual Basic .NET. You can download the source code and samples and see them in action right away or you can follow along with the walkthrough and build them yourself step-by-step.

Registration-Free COM Terminology

Anyone familiar with .NET Framework technology will be accustomed to the term assembly, which denotes a set of one or more modules deployed, named, and versioned as a unit, with one module containing a manifest that defines the set. In Registration-free COM, the terms assembly and manifest are borrowed for ideas that are similar in concept but not identical to their .NET counterparts.

Registration-free COM uses assembly to mean a set of one or more PE modules (i.e., either native or managed) deployed, named, and versioned as a unit. Registration-free COM uses manifest to refer to text files with the .manifest extension containing XML, which either defines the identity of an assembly (assembly manifest), together with the binding and activation details of its classes, or defines the identity of an application (application manifest), together with one or more assembly identity references. An assembly manifest file is named for the assembly, and an application manifest file is named for the application.

The term side-by-side (SxS) assemblies refers to the configuration of different versions of the same COM component, via manifest files, in order that they can be loaded simultaneously by different threads without needing to be registered. SxS enables, and is loosely synonymous with, registration-free COM.

Running the Sample

After you've downloaded and extracted the sample code, you'll find a folder called \deployed. In here is the Visual C++ version of the client application (client.exe), its manifest (client.exe.manifest), the Visual C++ version of the COM server (SideBySide.dll) and its manifest (SideBySide.X.manifest). Go ahead and run client.exe. The expected result is that client.exe will activate an instance of SideBySideClass (implemented in SideBySide.dll) and display the result of calling its Version method, which should look like "1.0.0-CPP".

Building the Visual C++ COM Server

Step 1

The first step is to build a COM server. In Visual Studio create a new Visual C++ ATL Project and call it SideBySide. In the ATL Project Wizard, on the Application Settings tab, deselect the Attributed check box and select the Allow merging of proxy/stub code check box.

In Solution Explorer, right-click the project node and choose Add | Add Class.... Select ATL Simple Object and choose Open. Give the class a short name of SideBySideClass and click Finish.

In Class View, right-click the ISideBySideClass node and choose Add | Add Method.... In the Add Method Wizard, enter Version as the method name, choose a parameter type of BSTR*, enter pVer as the parameter name, select the retval check box, then click Add and then click Finish.

In Class View, expand the CSideBySideClass node and double-click the Version method. Replace the // TODO line with:

Copy

*pVer = SysAllocString(L"1.0.0-CPP");

Produce a release build and copy \release\SideBySide.dll into \deployed.

Building the C++/.NET Client

The next step is to build the client. In this part of the walkthrough you have the option to build either a Visual C++ or a .NET client for the Visual C++ COM server. Needless to say, it is possible to mix and match clients and servers written in Visual C++, Visual Basic 6.0, and .NET. If you wish to do so, you will find the samples trivial to amend so that they work together. The sets of clients and servers are organized as they are in this walkthrough in the interest of presenting code that works as-is.

Step 2 (Option A: Visual C++)

Create a new Visual C++ Win32 Console Project called client in a sibling folder relative to the SideBySide project's folder. In the Win32 Application Wizard, on the Application Settings tab, check the Add support for ATL check box.

Edit stdafx.h and add the following line at the top of the file, immediately after the #pragma once:

Copy

#define _WIN32_DCOM

Also in stdafx.h add the following line at the bottom of the file:

Copy

#import "..\deployed\SideBySide.dll" no_namespace

Replace the contents of client.cpp with this code:

Copy

#include "stdafx.h"
#include <iostream>
using namespace std;

void ErrorDescription(HRESULT hr)
{
TCHAR* szErrMsg;
if (FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER|
FORMAT_MESSAGE_FROM_SYSTEM, NULL, hr,
MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
(LPTSTR)&szErrMsg, 0, NULL) != 0)
{
cout << szErrMsg << endl;
LocalFree(szErrMsg);
}
else
cout << "Could not find a description for error 0x"
<< hex << hr << dec << endl;
}

int _tmain(int argc, _TCHAR* argv[])
{
CoInitializeEx(0, COINIT_MULTITHREADED);

{
ISideBySideClassPtr ptr;
HRESULT hr = ptr.CreateInstance(__uuidof(SideBySideClass));
if (SUCCEEDED(hr))
{
cout << ptr->Version() << endl;
}
ErrorDescription(hr);

char c;
cin >> c;
}

CoUninitialize();

return 0;
}

Produce a release build and copy \release\client.exe into \deployed.

Step 2 (Option B: .NET Framework)

In Visual Studio .NET 2003 create a new C# or Visual Basic .NET Console Application called client in a sibling folder relative to the SideBySide project's folder. Add a reference to the SideBySide 1.0 Type Library from the Add Reference dialog's COM tab.

Paste the following code inside the Main method:

C# code

Copy

SideBySideLib.ISideBySideClass obj =
new SideBySideLib.SideBySideClassClass();
Console.WriteLine(obj.Version());
Console.ReadLine();

Visual Basic .NET code

Copy

Dim obj As SideBySideLib.ISideBySideClass =
New SideBySideLib.SideBySideClassClass
Console.WriteLine(obj.Version())
Console.ReadLine()

Produce a release build and copy client.exe into \deployed.

Step 3

At present the \deployed folder should contain, apart from some intermediate files, only client.exe and SideBySide.dll, and the latter will have been registered by its build process. To check that your server and client work together under these normal circumstances, run \deployed\client.exe and note the expected output "1.0.0-CPP".

Step 4

This walkthrough is about registration-free COM, so we now need to unregister the SideBySide assembly. At a command prompt, navigate to the \deployed folder and execute the command: regsvr32 /u SideBySide.dll.

Step 5

To see what effect the previous step has had, run \deployed\client.exe again and you will see the message "Class not registered". At this stage we have frustrated the COM runtime from finding the information it needs in the registry but we have yet to make the information available by alternative means. We will remedy that in the following steps.

Registration-Free Activation

Step 6

In the \deployed folder, create an application manifest file (a text file) for the client.exe application and call it client.exe.manifest. Paste the following into the file:

Copy

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

Step 7

In the \deployed folder, create a private assembly manifest file (a text file) for the SideBySide.dll component and call it SideBySide.X.manifest. Paste the following into the file:

Copy

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1"
manifestVersion="1.0">

<assemblyIdentity
type="win32"
name="SideBySide.X"
version="1.0.0.0" />

<file name = "SideBySide.dll">

<comClass
clsid="{[CLSID_SideBySideClass]}"
threadingModel = "Apartment" />

<typelib tlbid="{[LIBID_SideBySide]}"
version="1.0" helpdir=""/>

</file>

<comInterfaceExternalProxyStub
name="ISideBySideClass"
iid="{[IID_ISideBySideClass]}"
proxyStubClsid32="{00020424-0000-0000-C000-000000000046}"
baseInterface="{00000000-0000-0000-C000-000000000046}"
tlbid = "{[LIBID_SideBySide]}" />

</assembly>

I've written the GUID values, which will be particular to your project, in the form of placeholders. The respective values of these placeholders can be found as follows, either in the SideBySide project's SideBySide.idl file, or by opening SideBySide.dll in the OLE/COM ObjectViewer (Oleview.exe) tool.

Copy

[
object,
uuid([IID_ISideBySideClass]),
dual,
nonextensible,
helpstring("ISideBySideClass Interface"),
pointer_default(unique)
]
interface ISideBySideClass : IDispatch{
[id(1), helpstring("method Version")] HRESULT
Version([out,retval] BSTR* pVer);
};
[
uuid([LIBID_SideBySide]),
version(1.0),
helpstring("SideBySide 1.0 Type Library")
]
library SideBySideLib
{
importlib("stdole2.tlb");
[
uuid([CLSID_SideBySideClass]),
helpstring("SideBySideClass Class")
]
coclass SideBySideClass
{
[default] interface ISideBySideClass;
};
};

Step 8

At this point I should broach the subject of embedding assembly manifest files as Win32 resources. Where developers are both able and willing to rebuild their COM components, it is advised that an assembly manifest (like the one created in the previous step) is embedded into the COM DLL as a Win32 resource of type RT_MANIFEST (defined in windows.h). In cases where this is not possible, please be careful to give your assembly (and consequently your assembly manifest) a name that differs from that of the COM DLL's file name. So, in the above case, the COM DLL is called SideBySide but the assembly is called SideBySide.X. If you're interested in the reason for this constraint, it is explained in the Troubleshooting section. In this walkthrough the assembly manifest is not embedded to reflect the many real-world cases in which doing so will not be feasible.

Step 9

To verify that, courtesy of the manifest files, your client is once more able to activate the SideBySideClass class, run \deployed\client.exe and note the expected output "1.0.0-CPP".

The Visual Basic 6.0 COM Server and Client

Step 1

The first step is to build a COM server. Create a new Visual Basic 6.0 ActiveX DLL project. In the Project Explorer select the Project1 node and, in the Properties Window, change its name to SideBySide. In the Project Explorer select the Class1 node and, in the Properties Window, change its name to SideBySideClass.

Paste the following subroutine into the Code Window:

Copy

Public Function Version()
Version = "1.0.0-VB6"
End Function

Choose File | Make SideBySide.dll... and navigate to the \deployed folder and then click OK. To prevent new GUIDs from being generated each time you make the dll, choose Project | SideBySide Properties..., then click the Component tab, and in the Version Compatibility group select the Binary Compatibility radio button.

Step 2

Create a new Visual Basic 6.0 Standard EXE project. In the Project Explorer select the Project1 node and, in the Properties Window, change its name to client. Choose File | Save Project As and save the form file and the project file in a sibling folder relative to the SideBySide project's folder. Choose Project | References, select the check box next to SideBySide, and click OK.

Double-click the main form in the Form designer and paste the following code inside Sub Form_Load():

Copy

Dim obj As New SideBySideClass
MsgBox obj.Version()

Choose File | Make client.exe... and navigate to the \deployed folder and then choose OK.

Step 3

At present the \deployed folder should contain, apart from some intermediate files, only client.exe and SideBySide.dll; and the latter will have been registered by its build process. To check that your server and client work together under these normal circumstances, run \deployed\client.exe and note the expected output "1.0.0-VB6".

Step 4

This walkthrough is about registration-free COM, so we now need to unregister the SideBySide assembly. At a command prompt, navigate to the \deployed folder and execute the command: regsvr32 /u SideBySide.dll.

Step 5

To see what effect the previous step has had, run \deployed\client.exe again and you will see the message "Run-time error '429': ActiveX component can't create object". At this stage we have frustrated the COM runtime from finding the information it needs in the registry, but we have yet to make the information available by alternative means. We will remedy that in the following steps.

Step 6

In the \deployed folder, create an application manifest file (a text file) for the client.exe application and call it client.exe.manifest. Paste the following into the file:

Copy

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

Step 7

In the \deployed folder, create a private assembly manifest file (a text file) for the SideBySide.dll component and call it SideBySide.X.manifest. Paste the following into the file:

Copy

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1"
manifestVersion="1.0">

<assemblyIdentity
type="win32"
name="SideBySide.X"
version="1.0.0.0" />

<file name = "SideBySide.dll">

<comClass
clsid="{[CLSID_SideBySideClass]}"
threadingModel = "Apartment" />

<typelib tlbid="{[LIBID_SideBySide]}"
version="1.0" helpdir=""/>

</file>

<comInterfaceExternalProxyStub
name="_SideBySideClass"
iid="{[IID__SideBySideClass]}"
proxyStubClsid32="{00020424-0000-0000-C000-000000000046}"
baseInterface="{00000000-0000-0000-C000-000000000046}"
tlbid = "{[LIBID_SideBySide]}" />

</assembly>

I've written the GUID values, which will be particular to your project, in the form of placeholders. The respective values of these placeholders can be found by opening SideBySide.dll in the OLE/COM ObjectViewer (Oleview.exe) tool.

Copy

[
uuid([LIBID_SideBySide]),
version(1.0),
custom(50867B00-BB69-11D0-A8FF-00A0C9110059, 8169)

]
library SideBySide
{
// TLib : // TLib : OLE Automation : {00020430-0000-0000-
C000-000000000046}
importlib("stdole2.tlb");

// Forward declare all types defined in this typelib
interface _SideBySideClass;

[
odl,
uuid([IID__SideBySideClass]),
version(1.0),
hidden,
dual,
nonextensible,
oleautomation
]
interface _SideBySideClass : IDispatch {
[id(0x60030000)]
HRESULT Version([out, retval] VARIANT* );
};

[
uuid([CLSID_SideBySideClass]),
version(1.0)
]
coclass SideBySideClass {
[default] interface _SideBySideClass;
};
};

Step 8

To verify that, courtesy of the manifest files, your client is once more able to activate the SideBySideClass class, run \deployed\client.exe and note the expected output "1.0.0-VB6".

Incompatible Apartments

All the COM servers in this walkthrough are built to run in a Single-Threaded Apartment (i.e., they are STA, or Apartment-threaded, components). All the clients are STA except for the C++ client, which is MTA (its thread runs in a Multi-Threaded Apartment). So there is one case in which the client and server live in incompatible apartments and in this case cross-apartment marshaling of COM calls needs to take place between a proxy and a stub. It is this case that makes use of the following section of the assembly manifest file:

Copy

...
<typelib tlbid="{[LIBID_SideBySide]}"
version="1.0" helpdir=""/>

</file>

<comInterfaceExternalProxyStub
name="ISideBySideClass"
iid="{[IID_ISideBySideClass]}"
proxyStubClsid32="{00020424-0000-0000-C000-000000000046}"
baseInterface="{00000000-0000-0000-C000-000000000046}"
tlbid = "{[LIBID_SideBySide]}" />
...

These elements provide information that would otherwise be present in the registry. The comInterfaceExternalProxyStub element provides enough information for type library marshalling to occur and it is appropriate for COM interfaces that derive from IDispatch (which includes all Automation interfaces). In these cases ole32.dll provides the external proxy-stub used (i.e., external to the files in the assembly). If your COM components implement only dispatch or dual interfaces then this is the element you should use.

Custom interfaces are a little more rare and for these you have to do a little more work. Consider an interface called ISxSCustom that derives directly from IUnknown and is not automation-compatible. For SideBySideClass to implement ISxSCustom, and for clients to call its methods in a registration-free scenario, I need to add a comInterfaceProxyStub element to my assembly manifest. As suggested by the element name, this time the proxy-stub is not external: it is provided either by SideBySide.dll (if I checked the Allow merging of proxy/stub code check box in the ATL Project Wizard) or in SideBySidePS.dll. If my proxy-stub is merged then the new element is a child of the existing file element:

Copy

<file name = "SideBySide.dll">
...
<comInterfaceProxyStub
name="ISxSCustom"
iid="{[IID_ISxSCustom]}" />
</file>

Otherwise I need to add a further file element declaring the proxy-stub dll:

Copy

<file name = "SideBySide.dll"> ... </file>
<file name = "SideBySidePS.dll">
<comInterfaceProxyStub
name="ISxSCustom"
iid="{[IID_ISxSCustom]}" />
</file>

If I hadn't needed to illustrate the elements described above, I would have built the Visual C++ COM server to be both-threaded so that its coclasses would have been activated in the client's MTA. In the event that the client and the server exist in the same apartment, the elements just discussed are ignored. However, I urge you not to depend on this circumstance because there may be situations outside of your control where a component is activated in a different apartment than its client, even if their threading models are consistent. Considering the relatively small effort required, I think it's advisable to always include proxy-stub configuration in your manifests.

Using the Activation Context API

In the Introduction section I mentioned that one of the stages of initializing an application's process, on the platforms to which this article applies, is to locate an application manifest file. The application manifest file contains references to the assemblies on which the application has dependencies. In the case of the registration-free activation of native COM components, what is meant by an assembly is a set of one or more COM DLLs collected under a common identity and version.

If your application knows a priori the potential set of coclasses to be directly or indirectly activated during its lifetime, then application manifests are convenient. But there is a relatively rare class of application (e.g., grid servers) that by design do not, prior to runtime, know the modules they will load. In this case, a way of referencing assembly manifest files after process initialization is called for. This is satisfied by the activation context API, the use of which obviates an application manifest file. At its simplest, the technique is to initialize an ACTCTX structure with the location of the assembly manifest file and then create and activate an activation context from it. The following instructions assume you have already built the Visual C++ client application described in Step 2 (Option A).

Edit stdafx.h and add the following line immediately after your definition of _WIN32_DCOM:

Copy

#define _WIN32_FUSION 0x0100 // this causes activation context
structs and APIs to be included.

If you look at the _tmain function in client.cpp, in between the COM initialize and uninitialize calls, you will see a compound statement that activates and calls the SideBySideClass. We need to move this compound statement (everything between the curly braces) inside a new section of code that initializes the activation context as follows:

Copy

ACTCTX actCtx;
memset((void*)&actCtx, 0, sizeof(ACTCTX));
actCtx.cbSize = sizeof(ACTCTX);
actCtx.lpSource = "SideBySide.X.manifest";

HANDLE hCtx = ::CreateActCtx(&actCtx);
if (hCtx == INVALID_HANDLE_VALUE)
cout << "CreateActCtx returned: INVALID_HANDLE_VALUE"
<< endl;
else
{
ULONG_PTR cookie;
if (::ActivateActCtx(hCtx, &cookie))
{
// previous compound statement goes here...
::DeactivateActCtx(0, cookie);
}
}

The above code runs before any coclasses are activated. The code simply reads the assembly manifest file (whose name is hard-coded in this example, but should correspond to whichever assembly you wish to load dynamically) into an activation context that it then activates (i.e., makes current). From this point onwards the activation of coclasses occurs as before. You may now discard client.exe.manifest.

An alternative to the direct activation context API, but available only on Windows Server 2003, is the Microsoft.Windows.ActCtx object.

Needless to say, there is a lot more to the activation context API than I have shown here and you can find a link to the full API documentation in the Further Reading section.

Troubleshooting

As we've seen, the registration-free activation of COM components requires no special code in the server or in the client. All that's required is a matching pair of manifest files.

I suggest you approach your own registration-free development the way this walkthrough does. Specifically: first get to a known state by seeing your client working with a registered server; then unregister the server and verify that your error message is what you expected; and finally, remedy the situation by crafting and deploying manifest files. This way your troubleshooting efforts around registration-free activation will be confined to the structure of your manifest files (and the correct embedding of the assembly manifest if you choose to do so).

When troubleshooting registration-free COM issues, the Event Viewer on Windows Server 2003 is your friend. When Windows XP or Windows Server 2003 detects a configuration error it will typically show an error message box titled for the application you have launched and containing the message "This application has failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem." I advise that whenever you see this message you reproduce the problem on Windows Server 2003, consult the System Event Log and look for events from the SideBySide source. The reason I don't suggest that you look at the Windows XP Event Log in these cases is that it will invariably contain a message such as "Generate Activation Context failed for [path]\[application filename].Manifest. Reference error message: The operation completed successfully," which doesn't help identify the problem.

The schemas of the various manifest files are documented in the Platform SDK under the heading Manifest Files Reference, and the schema validation tool Manifestchk.vbs is available, so here I will only call out a few points relevant to the walkthrough. First let's examine the assembly manifest file. For an example, look back to Step 7.

You will recall that, in the registration-free COM sense, an assembly is an abstract idea with which you associate one or more physical files by means of the contents of the assembly manifest file. The name of the assembly appears in three places and must be identical in each: in the name attribute of the assembly manifest file's assemblyIdentity element; in the name attribute of the application manifest file's dependentAssembly/assemblyIdentity element; and the name of the assembly manifest file itself, excluding the .manifest extension. If the manifest file name does not match the name in the application manifest then you will see the following message in the Windows Server 2003 System Event Log: "Dependent Assembly [value of name attribute in application manifest] could not be found and Last Error was The referenced assembly is not installed on your system." If the name element in the assembly manifest is incorrect then you will see the following message in the Windows Server 2003 System Event Log: "Component identity found in manifest does not match the identity of the component requested."

If SideBySide.dll had been a .NET Framework-based component, then we would have been obliged to embed the assembly manifest file into the SideBySide assembly as a Win32 resource (and we would have named the manifest file after the .NET assembly—i.e., SideBySide.manifest). However, due to the assembly-loader's searching sequence, for native COM components it is optional to embed the manifest into the module. Before the assembly-loader looks for [AssemblyName].manifest, it looks for [AssemblyName].dll and searches in it for a Win32 resource of type RT_MANIFEST. The configuration inside the resource must have an AssemblyIdentity element that matches [AssemblyName] as well as the other attributes in the application manifest's AssemblyIdentity reference.

However, if [AssemblyName].dll is found but it does not contain a matching manifest, then the assembly-loading mechanism stops and does not continue to look for [AssemblyName].manifest. At the time of writing, this is true of the assembly-loader on Windows XP (which in this circumstance will display its usual message that "the application configuration is incorrect"), but not on Windows Server 2003. On Windows Server 2003, searching does continue and will find the manifest file even if it has matched the name of a module. However, I urge you not to depend on this behavior. Rather, to ensure you consistently support both platforms, I'd recommend that you embed your assembly manifest in your assembly as an RT_MANIFEST resource whenever feasible. Where it's not feasible, you must give your assembly manifest file a different name from that of any module in the same folder. Alternatively, place your COM component in a child folder of the assembly manifest's folder and reference this child path in the assembly manifest's file element.

The assemblyIdentity element defines the identity of the assembly. For native COM components neither its name nor its version attribute need match that of any physical file, although it's a good idea to apply some kind of consistency.

The file element is the parent to the comClass, typelib, and comInterfaceProxyStub elements. Its purpose is to locate the physical files comprising the assembly. If the file element's name attribute does not correctly reference the files in the file system, then CoCreateInstance will return a HRESULT corresponding to either "Class not registered" or "The specified module could not be found". So that you can install different versions of your COM component in different folders, the name attribute can include a path. On Windows XP SP2 the path can be relative or absolute and can reference a folder anywhere in the file system. Windows Server 2003 requires the path to reference either the application root or a child folder, and if you try to violate this rule then you will see the following message in the Windows Server 2003 System Event Log: "Syntax error in manifest or policy file [assembly manifest filename] [...] The value [...] is invalid."

The comClass element has only one mandatory attribute: clsid. If the application attempts to activate an unregistered coclass whose CLSID is not listed in a comClass element in the assembly manifest, then CoCreateInstance will return a HRESULT with the value REGDB_E_CLASSNOTREG (0x80040154), the message text for which is "Class not registered".

As I've said, the typelib and comInterface[External]ProxyStub elements are required in the event that the client and server exist in different apartments, so the following errors can be seen only when these elements are processed. Configuration errors in these elements cause CoCreateInstance to return a HRESULT that corresponds to the messages "Library not registered", "Error loading type library/DLL", or "no such interface supported". If you see any of these messages, double-check your GUIDs and make sure all the mandatory attributes are present. You will find the manifest file schema in the Platform SDK.

Now let's turn our attention to the application manifest file. For an example, look back to Step 6. The application manifest must be named in the format [application filename].manifest. So, in the walkthrough it was named client.exe.manifest to make it clear it should be read whenever client.exe is loaded into a process. If this is not done correctly, then CoCreateInstance will return a HRESULT with the value REGDB_E_CLASSNOTREG (0x80040154), the message text for which is "Class not registered".

The most important element in the application manifest is the dependentAssembly/assemblyIdentity element. This element is a reference to the equivalent one in the assembly manifest and the two must match exactly. A good way of ensuring that they do so is to copy the element from the assembly manifest and paste it here. If there is any difference whatsoever, you will see the following message in the Windows Server 2003 System Event Log: "Component identity found in manifest does not match the identity of the component requested."

Conclusion

Registration-free COM is a technology that liberates COM components from a dependency on the Windows registry and consequently liberates the applications that use them from requiring dedicated servers. It enables applications with dependencies on different versions of the same COM component to share an infrastructure and to load those various COM component versions side by side in an echo of the .NET Framework versioning and deployment mechanism.

This article walks you through a demonstration of the registration-free activation of native COM components by native client applications written in both Visual C++ and Visual Basic 6.0 and by a managed client. It explains some of how the mechanism works and underlined some possible configuration errors and how to troubleshoot them.

Further Reading

Registration-Free Activation of .NET-Based Components: A Walkthrough

Isolated Applications and Side-by-side Assemblies

Manifest File Schema

Using the Activation Context API

About the author

Steve White is an Application Development Consultant working in the Premier Support for Developers team at Microsoft UK. He supports customers developing with Visual C#, Windows Forms, and ASP.NET. His blog has more information about his interests in music, visualizations, and programming.

Leslie Muller is a technologist with the Research & Development team at Credit Suisse First Boston. Leslie has 12 years experience as a developer and technical architect, working in environments such as financial services, technology startups, industrial automation and defence. When he’s not programming or doing research he enjoys skiing, ice hockey and when possible doing slightly mad things with motorized vehicles in extreme environments like Iceland or the Rockies.

English (United States)

Theme

Light

Dark

High contrast

Previous Version Docs

Blog

Contribute

Privacy & Cookies

Terms of Use

Trademarks

© Microsoft 2021

In this article

Introduction

Registration-Free COM Terminology

Running the Sample

Building the Visual C++ COM Server

Building the C++/.NET Client

Registration-Free Activation

The Visual Basic 6.0 COM Server and Client

Incompatible Apartments

Using the Activation Context API

Troubleshooting

Conclusion

Further Reading

English (United States)

Theme

Light

Dark

High contrast

Previous Version Docs

Blog

Contribute

Privacy & Cookies

Terms of Use

Trademarks

© Microsoft 2021