Mapping Weakly Typed Properties to Storage
You can think of any class property as a name-value pair. Strongly typed properties are properties defined as part of a class definition. Weakly typed properties are properties that have not been added as class properties to a class, but instead are placed in a string indexer (this[string] in C#) as a name-value pair. This functionality is provided in all of the base Orders classes for backward compatibility with legacy COM-based pipeline components. Normally, weakly typed properties are serialized into a single binary large object (BLOB) as part of saving to storage. Weakly typed properties whose names start with an underscore, and those that are not serializable, are not serialized.
The Orders storage mapping system provides the ability to map individual weakly typed properties to their own columns, similar to the way in which you map strongly typed properties. The default Orders storage mapping file contains no weakly typed property mappings.
When saving a weakly typed property to storage, an exception is thrown by the storage code Microsoft.CommerceServer.Runtime.Orders.Basket.SaveAsOrder and Microsoft.CommerceServer.Runtime.Orders.PurchaseOrder.Save if the type of the weakly typed property is not compatible with the column's type.
The following example shows how to perform such a mapping from a weakly typed property UserNickname in the OrderAddress class to its own column added to the OrderAddresses table.
Step 1: Modify the Storage Mapping File
Only excerpts from the mapping file are shown in this step.
Adding the UserNickname Column
You must add a new column definition to the OrderAddresses table in which to store values from OrderAddress class instances.
Note
· The line numbers appear for clarity; remove them before using this code.
1 <Table Name="OrderAddresses">
2 <Columns>
3 <Column Name="OrderGroupId" DataType="uniqueidentifier" />
...
4 <Column Name="UserNickname" DataType="nvarchar" Precision="50" IsNullable="true" />
5 <Column Name="MarshalledData" DataType="image" IsNullable="true" />
6 </Columns>
7 </Table>
At line 4, add the new column definition for UserNickname as type nvarchar(50) and null-able. It is required that any column corresponding to a weakly typed property have a null-able column constraint. When the weakly typed property is not present in the name-value pair set, null is applied to the column value.
Adding a Weakly Typed Property to a Class Definition
Next, update the class definition for OrderAddress to add a definition for your new weakly typed property that you want to map. Only weakly typed properties mapped to their own columns must be added to the class definition; unmapped properties can simply be added to the name-value pairs on an ad hoc basis.
Note
· The line numbers appear for clarity; remove them before using this code.
1 <Class Name="OrderAddress">
2 <Property Name="OrderAddressId" />
...
3 <WeaklyTypedProperty Name="UserNickname" />
4 </Class>
At line 3, add a special type of XML node to the class, WeaklyTypedMember. The only attribute for this node is the Name attribute, which defines the name of the weakly typed property.
Adding the Mapping for the Weakly Typed Property
Finally, change the OrderAddress mapping to add a mapping between the weakly typed property and the column.
Note
· The line numbers appear for clarity; remove them before using this code.
1 <ClassTableMap Class="OrderAddress" Table="OrderAddresses">
2 <PropertyMap Property="OrderAddressId" Column="OrderAddressId" />
...
3 <PropertyMap Property="UserNickname" Column="UserNickname" />
4 </ClassTableMap>
At line 3, add a PropertyMap XML node containing the source object property and the target database column names.
Step 2: Use OrderMapping.exe on the Mapping File
See the notes from the MyLineItem sample on how to use OrderMapping.exe with a Web.config file. You use the generated OrdersStorage.sql file to update the site database. This new file contains changes to the default Orders stored procedures to support saving to and loading from the new table.
Step 3: Modify the Site Database
In the Commerce Server 2007, you perform modifications to existing tables. Assuming this sample is applied to the CSharpSite sample provided with the CS2007, this means adding a column named UserNickname of type nvarchar(50) to the OrderGroupAddresses table. After adding the column, you update the stored procedures in the database. Load the OrdersStorage.sql file into the SQL Server Query Analyzer and run it against the site database (CSharpSite_transactions in the CSharpSite demonstration site provided with the CS2007).
Step 4: Deploy the Mapping File
The MyLineItem sample describes the steps to deploy the new version of the mapping file.
