Deciding Which Interface to Expose

Before a component can be configured through a macro language such as Microsoft® Visual Basic Scripting Edition (VBScript) or JavaScript, it must implement the IDispatch interface. Because any interface that you create can inherit from IDispatch, you decide which of the interfaces that you implement will use IDispatch to expose your component's properties and/or methods.

Several options are available. When you add an object to your project, as you did in Step 2 of this tutorial, Visual C++ adds an interface to the object definition that appears in the project's interface definition language (IDL) file. By default, the interface that Microsoft® Visual C++® adds inherits from IDispatch.

You can use this interface, or you can implement the IPipelineComponentAdmin interface. This interface is defined by Commerce Server 3.0 specifically to enable component writers to expose their component properties. The IPipelineComponentAdmin interface defines two methods: GetConfigData and SetConfigData. These methods take a Dictionary as a parameter, and read or write to this Dictionary to retrieve or set the values of a component's properties.

The options described in the preceding paragraphs are mutually exclusive; you cannot implement two IDispatch interfaces on a single object and make both available to Active Server Pages (ASP) clients.

The following lists the advantages to using the Visual C++ user interface to get an IDispatch implementation:

• υYou do not have to worry about specifically implementing IDispatch::Invoke on your own. By adding properties and methods through the Visual C++ user interface, this work is done for you.
• υAs you add properties and methods to your object, Visual C++ automatically adds the appropriate entries to the project's IDL, header, and implementation files. Because the added interface is the default interface for the object, a VBScript or JavaScript client that creates an instance of your object using the object's program identifier (Prog ID) gets this interface, and can set the methods and invoke the properties implemented in that interface.

The advantage of implementing IPipelineComponentAdmin is that according to the rules of the Component Object Model (COM), once an interface is published, it cannot be changed. By adding properties to a published object, you necessarily modify the dispatched interface, running the risk that you will break the client code of existing users. Because implementing IPipelineComponentAdmin does not require that your component definition be modified to add support for new properties, your component can evolve over time without requiring the publication of a new interface.

This tutorial illustrates the former approach. The WriteToDb sample, which is included on the Commerce Server compact disc, illustrates how to implement IPipelineComponentAdmin.