Commerce Foundation Metadata

Microsoft Multi-Channel Commerce Foundation metadata provides access to the metadata defined within different Commerce Server Core Systems (Catalog, Profiles and Orders; Marketing does not expose the metadata) through a unified and consistent object model. It also allows you to extend the Commerce Server metadata with additional property metadata, relationships, and constraints as well as override metadata definitions provided by the Commerce Server.

Commerce Foundation Metadata Object Model

The following diagram depicts the Commerce Server 2009 Metadata Object Model.

DefinitionBase class

The DefinitionBase is an abstract class that is used as a direct or indirect base class for all the Commerce Server 2009 metadata classes: CommerceEntityDefinition, PropertyDefintion, EnumeratedPropertyDefinition, RelationshipDefinition, and RelationshipTypeDefinition.

The following are DefinitionBase properties:

Property	Description
Name	The programmatic name of the definition.
DisplayName	A human readable name of the definition. A definition can have different DisplayName values for different languages.
Description	A human readable description of the definition. A definition can have different Description values for different languages.

MultilingualValue class

The MultilingualValue class represents a multilingual value and has the following properties:

Property	Description
CurrentValue	A value that corresponds to the current language -Thread.CurrentThread.CurrentUICulture.Name. If there is no language-specific value defined, then the language-neutral value is used.
this[string language]	An indexer that provides access to the language-specific values. The format of the language name is identical to the CultureInfo.Name in.NET Framework, which is: <languagecode2>-<country/regioncode2> where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. The language-neutral value is identified by the CultureInfo.InvariantCulture.Name.

CommerceEntityDefinition class

The key class in the Commerce Server 2009 metadata object model is CommerceEntityDefinition, which represents the metadata that describes a Commerce Server 2009 Commerce Entity. The following are CommerceEntityDefinition properties:

Property	Description
PropertyDefintions	A Relationship List that targets the metadata for all the properties of the corresponding CommerceEntity.
RelationshipDefintions	A Relationship List that targets the metadata for all the relationships of the corresponding CommerceEntity.
EntityMappings	A Relationship List that targets the EntityMapping objects. Each EntityMapping object defines a mapping between the Commerce Entity and the corresponding Commerce Server class properties. In most cases, there is one Commerce Server class for a given Commerce Server 2009 Commerce Entity. Though, some Commerce Server 2009 Commerce Entities can map to different Commerce Server classes depending on the context they are used in. For example, a Microsoft Multi-Channel Commerce Foundation Address can be mapped either to the OrderAddress or an Address Profile.

EntityMapping class

The EntityMapping class defines the mapping between a Commerce Server class and a Commerce Server 2009 CommerceEntity class. It derives from the CommerceEntity class and contains the following additional properties:

Property	Description
CommerceEntityName	The short name of the CommerceEntity that corresponds to the CommerceEntityDefinition.Name property such as a Product or Address.
CommerceServerClass	The fully qualified name of the Commerce Server class that is used as the source of the property mapping. For example: Microsoft.CommerceServer.Runtime.Orders.OrderAddress.
CommerceServerDefinitionName	An optional name of the Commerce Server Definition. The Definition name in Commerce Server Core Systems applies to a Profile or a Catalog Definition name such as a UserObject or Address.
CommerceServerAssembly	The full name of the assembly containing the Commerce Server Core Systems Class.
CommerceServerArea	Specifies which area of the Commerce Server functionality this entity mapping belongs to. This optional property should be used for any CommerceEntityDefinition that contains more than one EntityMapping to distinguish one entity mapping from another. A CommerceEntityDefinition can contain no more than one EntityMapping with the same value of the CommerceServerArea.
PropertyMappings	A collection of StringPair objects that map the source entity properties to the target entity properties. The Key of the StringPair is the source property name (belongs to the CommerceEntity class), the Value is the target property name (belongs to the Commerce Server class).
DefinitionMappings	A Relationship List that targets the DefinitionMapping objects. Each DefinitionMapping object contains the metadata that defines a Commerce Server definition and maps it to the Commerce Server 2009 object model.

The CommerceServerDefinitionName and the DefinitionMappings are mutually exclusive. If an EntityMapping maps a CommerceEntity to a Commerce Server entity's specific definition, like for example the Address definition of the Commerce Server Profile class or a specific product definition of the Commerce Server Product class, then the CommerceServerDefinitionName is specified and the DefinitionMappings has no entries. In this case the CommerceEntity is based on a specific Commerce Server definition and cannot contain any definitions. On the other hand, if a CommerceEntity maps to a more generic Commerce Server entity that contains definitions, than the DefinitionMappings RelationshipList is populated. An example of this use case would be a Product CommerceEntity that maps to the Commerce Server Product class that has multiple product definitions.

DefinitionMapping class

The Commerce Server 2009 object model provides DefinitionMapping class to define a mapping between the Commerce Server Core Systems object model and the Microsoft Multi-Channel Commerce Foundation definitions (this applies to Category Product and Variant which can have definition specific properties). This class derives from the CommerceEntityDefinition and contains the following additional properties:

Property	Description
DefinitionName	A name of the Microsoft Multi-Channel Commerce Foundation definition.
CommerceServerDefinitionName	A name of the Commerce Server Core Systems definition.
PropertyMappings	A collection of StringPair objects that map the source entity properties to the target entity properties. The Key of the StringPair is the source property name (belongs to the CommerceEntity Core Systems class), the Value is the target property name (belongs to the Commerce Server class). This PropertyMappings collection only contains mappings for the properties specific to the definition. The properties common to all the definitions are mapped through the EntityMapping. PropertyMappings. Note: A definition can re-map a property found in the entity mapping.

PropertyDefintion class

The PropertyDefinition class represents the metadata that defines a CommerceEntity property. It derives from the DefinitionBase class and contains the following additional properties:

Property	Description
PropertyType	Specifies the data type of the CommerceEntity property. All possible property data types are defined by the PropertyDataType enum: public enum PropertyDataType { Array, BigInteger, Binary, Boolean, Decimal, Date, DateTime, Double, Email, Float, Integer, Password, RichText, String, Time, UniqueIdentifier, Url }
CommerceEntityName	The name of the CommerceEntity class to which this property belongs. This name is the short name of the CommerceEntity that corresponds to the CommerceEntityDefinition.Name property.
Format	A string that defines the CommerceEntity property formatting. This string corresponds to the .NET String.Format.
Constraints	A Relationship List that targets the Constraint objects associated with the CommerceEntity property. Each constraint defines a validation rule. The validation rules are combined using logical AND operators, which means that the property is valid if none of the constraints is broken; the property is invalid if any of the constraints are broken.
DefaultValue	The CommerceEntity property's default value.
IsMultilingual	Indicates whether the CommerceEntity's property can contain language (culture) specific values.
IsStronglyTyped	Indicates whether the CommerceEntity's property is a strongly typed one in the Commerce Server object model.

EnumeratedPropertyDefinition class

The EnumeratedPropertyDefinition class represents the metadata that defines a multi-choice CommerceEntity property. It derives from the PropertyDefintion class and contains only one additional property:

Property	Description
EnumeratedValues	A Relationship List that targets the EnumerationEntry objects, which represent the values of a multi choice property.

EnumerationEntry class

The EnumerationEntry defines a value of the multi choice property. It derives from the CommerceEntity class and contains the following additional properties:

Property	Description
DisplayName	A multilingual display name of the entry.
Value	The entry's value.

RelationshipDefintion class

The RelationshipDefintion class represents the metadata that defines a CommerceEntity relationship. It derives from the DefinitionBase class and contains the following additional properties:

Property	Description
SourceCommerceEntity	The name of the CommerceEntity to which this relationship belongs.
IsMultipleItems	Defines the multiplicity of the relationship. If True the relationship is one-to-many
RelationshipType	Specifies the type of the relationship.

RelationshipTypeDefinition class

The RelationshipTypeDefinition represents the metadata that defines a type of the CommerceEntity relationship. It derives from the DefinitionBase class and contains the following additional properties:

Property	Description
PropertyDefinitions	Metadata for all the properties of the corresponding relationship type.

Constraint classes

Microsoft Multi-Channel Commerce Foundation Services Metadata defines a number of the constraint classes that provide validation rules as part of the CommerceEntity property metadata. These classes themselves do not enforce validity of the data, but rather provide a set of rules that can be used by the application to enforce validation using either platform specific validation mechanisms (like ASP.NET validation controls) or any custom implemented validation logic.

ConstraintBase class

The ConstraintBase class is a base class that all the Constraint classes derive from. It has the following properties:

Property	Description
Negated	An indicator of the negated validation logic. If True the default validation logic will be used
ValidationMessage	A language specific validation message.

RequiredPropertyConstraint class

The RequiredPropertyConstraint class specifies that a property requires a value.

CompareConstraint class

The CompareConstraint class allows for comparing the property’s value with the value of another property of the same CommerceEntity. It has the following properties:

Property	Description
PropertyToCompare	The name of the property to compare.
Operator	A logical comparison operator defined by the following enum: public enum ValidationCompareOperator { Equal, NotEqual, GreaterThan, GreaterThanEqual, LessThan, LessThanEqual }

RegularExpressionConstraint class

The RegularExpressionConstraint class provides a regular expression string that the property’s value must match. It has the following properties:

Property	Description
Pattern	Defines the regular expression pattern that the CommerceEntity’s property must match.

RangeConstraint class

The RangeConstraint class provides a range that the property’s value cannot exceed. The range boundaries specify the minimum and the maximum values allowed for the property. For the string type properties it specifies the string’s length. It has the following properties:

Property	Description
MinValue	The lower boundary value.
MaxValue	The upper boundary value.
MinBoundaryType	Specifies how the lower boundary should be treated. It is defined by the following enum: public enum BoundaryType { Ignore, Include, Exclude }
MaxBoundaryType	Specifies how the upper boundary should be treated. It is defined by the BoundaryType enum.

JoinKeyConstraint class

The JoinKeyConstraint class defines a constraint that marks the property as the join key.

PrimaryKeyConstraint class

The PrimaryKeyConstraint class defines a constraint that marks the property as the primary key.

ReadOnlyConstraint class

The ReadOnlyConstraint defines a constraint that requires the property to be read-only.

UniqueKeyConstraint class

The UniqueKeyConstraint defines a constraint that requires the property to have unique values.

See Also

Other Resources

Working with Metadata in Commerce Foundation

Commerce Foundation Metadata Repository Design

Commerce Foundation Metadata Flow Through Rules

Commerce Foundation Metadata API Reference

Managing and Manipulating Metadata in Commerce Foundation

Commerce Foundation Property Metadata