How to Extend the Orders Runtime

For the latest version of Commerce Server 2007 Help, see the Microsoft Web site.

You can customize the behavior of the Orders System by extending the Orders System classes and overriding methods of some of the Orders classes.

You can extend the Orders runtime classes in the following ways:

• Derive a new class from an Orders class.

• Add a new property to an Orders class by using the weakly-typed property indexer that each Orders class provides.

The following table presents the advantages and disadvantages of each way of extending the Orders runtime classes.

Extension option	Advantages	Disadvantages
Derive a new class	The implementation is more robust than adding a new property. You can add new methods and properties. If you store new properties in the database, you can use the Commerce Server business user interface and Commerce Server APIs to search the properties.	Deriving a new class and integrating it with Commerce Server is more complex than adding a new property.
Add a new property	Adding a new property to a weakly-typed property indexer is simple.	The implementation is more error prone. As you add more properties, you are more likely to encounter name conflicts or type clashes. You cannot use the Commerce Server business user interface or Commerce Server APIs to search the properties in the database.

From the integration side (CS Adapters) there are advantages and disadvantages to each way of extending the Orders runtime classes as well, as shown in the following table.

Extension option	Advantages	Disadvantages
Derive a new class	Strongly-typed properties can be easily used for content-based routing within BizTalk Purchase Order Schema is more self-evident Message size is usually smaller (because the weakly-typed properties add more XML markup)	Changes to properties on a derived order class call for regeneration of schemas in BizTalk, which can affect mappings and other artifacts Regeneration of schemas in BizTalk calls for a recompile and redeployment
Add a new property	Relatively transparent to existing Purchase Order schemas in BizTalk when adding new properties (the schemas will still validate)	Content Based Routing is more difficult. Custom pipelines or complex mappings are required to pull the content into context. Schema doesn't fully describe what the data looks like Messages are usually larger (because the weakly-typed properties add more XML markup)

The following procedures introduce the high-level tasks that you must perform to extend the Orders System. The documentation in the section Extending the Orders Runtime contains more detailed instructions for completing these procedures.

To extend an Orders System class

1. Determine which Orders class or classes you will extend.

2. Write the application code to define the derived classes.

   For more information about how to create a new class, see How to Derive a New Orders Class.

3. Create or modify the database table definitions to store the classes and properties that you are adding.

   You can create or modify the database tables manually by using SQL Server management tools. Alternatively, you can use the Order Mapping tool to create or modify the database tables. For more information about how to use the Order Mapping tool, see How to Generate SQL Tables and Stored Procedures for Orders Mapped Storage.

4. Update the mapping between runtime objects and the database to include the classes and properties that you added.

   For more information about how to update the mapping between objects and the database, see Mapping Purchase Orders to the Database.

5. Generate new stored procedures for the database and apply the stored procedures.

   For more information about generating the stored procedures, see How to Generate SQL Tables and Stored Procedures for Orders Mapped Storage.

6. Update the mapping between runtime objects and the pipeline dictionaries to include the mappings for the classes and properties that you added.

   For more information about how to update the mapping between objects and the dictionaries, see How to Modify the OrderPipelineMappings.xml File.

7. Update the Web.config files to reflect the new classes and files.

   For more information about the Orders system elements in the Web.config file, see How to Add a Derived Orders Class to the Web.config File.

8. Write the site code that uses the extended classes.

To add a weakly-typed indexer property to an Orders System class

1. Determine what additional data you have to associate with an instance of an Orders class.

2. Choose a name for the new weakly-typed indexer property.

   Note

   Confirm that the name that you choose has not already been used. The compiler will not warn you if you reuse a name.

3. Write the site code to use the weakly-typed indexer property.

   For more information about how to use weakly-typed indexer properties, see How to Add a Weakly Typed Indexer Property to an Orders Class.

   You do not have to modify the definition of the class to use a weakly-typed indexer property.

4. If you want to store the value of the weakly-typed indexer property in a database column, update the database schema and update the OrderObjectMappings.xml file to map the weakly-typed indexer property to the database column. For example, you might do this if you will search the database using this value.

   For more information about how to update the mapping between objects and the database, see Mapping Purchase Orders to the Database.

To override a method on an Orders System class

1. Determine which method or methods that you will override.

   For more information about the methods that you can override, see Overrideable Orders Methods.

2. Write the application code to implement your version of the method.

See Also

Other Resources

Extending the Orders Runtime

Orders System Design-Time Scenarios