NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

What is a Custom Marshaler

The runtime’s marshaling service makes it possible to expose NGWS objects to COM and vice versa. In order to do this, the marshaler makes extensive use of wrappers called COM Callable Wrappers (CCW’s) and Runtime Callable Wrappers (RCW’s). A CCW is used to expose a managed type to COM and an RCW is used to expose an unmanaged type to the NGWS runtime. In most cases, the standard CCW or RCW that the marshaler generates is adequate for marshaling calls between the managed and unmanaged space. But, under some circumstances a custom wrapper is necessary or more desirable (see section 2). A custom wrapper is a specialized wrapper that allows a developer to control precisely how a managed type is exposed to COM and/or how an unmanaged type is exposed to the NGWS runtime. A custom wrapper is used in place of the standard wrappers when more control is need over the marshaling process.

A custom marshaler is a managed class used to activate custom wrappers as needed. The runtime marshaling service uses the custom marshaler to activate and deactivate wrappers as arguments and fields are marshaled across the Interop boundary. In order to use a custom wrapper in place of the standard wrapper, the parameter or field being marshaled must be decorated with the MarshalAs attribute (see section 3.6). The attribute identifies the custom marshaler used for marshaling that particular parameter. The custom wrappers are only used to marshal parameters or field that have the attribute applied.

Consider the managed interface INew. If exposed to COM through a standard COM callable wrapper (CCW), the interface would have the same methods as the managed interface and would use the marshaling rules built into the runtime’s marshaler. Instead of using the standard wrappers, a custom wrapper could be designed for use with the interface. The custom wrapper may have different marshaling behavior or it may expose the interface to COM in a different way. Suppose a well know COM interface called IOld already existed that provided the same functionality as the INew interface. A customized wrapper could provide an unmanaged implementation of IOld that simply delegated the calls to the managed implementation of the INew interface. The custom wrapper essentially acts as a bridge between the INew and the IOld interfaces.

Custom wrappers can also be built to replace standard runtime callable wrappers (RCW). In that case, the wrapper delegates calls made on the managed interface to another unmanaged interface implementation.

Using a custom marshaler has some significant advantages:

The wrapper essentially provides a bridge between the functionality of the old and new interfaces. They allow clients built to work with the old interface to continue to work with servers that only implement the new interface. Similarly, they allow clients built to work with the new interface to also work with server that expose the old interface.