CommerceCreate

This operation is used to create new commerce entities, new commerce entities related to the model, and new relationships between a new source commerce entity and an existing commerce entity.

Note: When creating a related item or relationship to an existing commerce entity, use the update operation on that existing commerce entity.

Class	Description
CommerceOperation	Base class of every operation. PropertyDescription ModelThis property represents the commerce entity of the operation. An example is the creation of a UserProfile. RelatedOperationsThis property represents commerce entities that are related to the Model. An example is the creation of an Address for a UserProfile.
CommerceCreateOperation	This is the concrete create operation class.
CommerceCreateOptions	The CommerceCreateOptions can be specified as part of a CommerceCreateOperation definition. PropertyDescription ReturnModelThis property identifies the properties of the created commerce entity to be returned as part of the response. A Null indicates nothing is returned. ReturnModelQueriesThis property identifies the related query operations that will be used to populate relationships of the commerce entity to be returned as part of the response. If ReturnModel is Null, this property has no effect on the operation response.As an example, if a new UserProfile is being created, the caller may be interested in having the Id of the new user returned in the response.
CommerceRelatedOperation (Abstract)	Base class for every type of supported related operation. PropertyDescription ModelThis property represents the commerce entity type that is being created associated. RelationshipNameThis property indicates which collection it belongs to. An example is the Address collection of the UserProfile. SearchCriteriaThis optional property is specified only when creating new relationships. It is used to identify the existing commerce entity of the new relationship. RelatedOperationsThis property specifies the child relationships of the commerce entity.
CommerceCreateRelatedItem	This class indicates a request to create a new commerce entity related to the item that is the target of the parent operation.
CommerceCreateRelationship	This class indicates a request to create a relationship between an existing commerce entity, represented by RelatedOperation.SearchCriteria, and the item that is the target of the parent operation.
CommerceCopyRelatedItem	This class indicates a request to copy a relationship between an existing commerce entity, represented by RelatedOperation.SearchCriteria, and the item that is the target of the parent operation.

Restrictions

You can create only one top-level commerce entity for each operation request. Microsoft Multi-Channel Commerce Foundation will throw an exception if the search type is not supported, or if the search criteria of a relationship selects anything other than a single commerce entity.

Response

Running a CommerceCreateOperation request creates a CommerceCreateOperationResponse.

Class	Property
CommerceOperationResponse	Base class for every operation.
CommerceCreateOperationResponse	Response of a CommerceCreateOperation. Returns the created commerce entity if a ReturnModel has been specified in the create options.

CommerceCreate<> Generic Class

The CommerceCreate<> generic class generic class constructs a CommerceCreateOperation operation or request to send to Microsoft Multi-Channel Commerce Foundation.

Class	Property
CommerceCreate<TItem>	Generic class used to create a request for the CreateOperation. PropertyDescription TItemThis item represents the commerce entity type (i.e. the Model) of the create operation. TOption is defaulted to CommerceCreateOptionsBuilder<TItem> which represents the default CommerceCreateOptions message.
CommerceCreate<TItem, TOption>	Generic class used to create a request for the CreateOperation. PropertyDescription TItemThis item represents the commerce entity type (i.e. the Model) of the create operation. TOptionThis item represents the type of CommerceCreateOptions to pass to the service call.
CommerceCreateRelationship<TItem, TRelationship>	Generic class used to create a relationship between the newly created commerce entity and an existing related item. PropertyDescription TItemThis item represents the commerce entity type (i.e. the Model) of the create operation. TRelationshipThis item represents the relationship type being created.
CommerceCreateRelationship<TItem>	Generic class used to create a relationship between the parent commerce entity and an existing commerce entity. PropertyDescription TItemThis item represents the commerce entity type (i.e. the Model) of the create operation.
CommerceCreateRelatedItem<TItem>	Generic class used to create a new related commerce entity. PropertyDescription TItemThis item represents the commerce entity type (i.e. the Model) of the create operation.
CommerceCopyRelatedItem<TItem>	Generic class used to copy a related commerce entity. PropertyDescription TItemThis item represents the commerce entity type (i.e. the Model) of the copy operation.
CommerceCopyRelatedItem<TItem, TParent>	Generic class used to copy a new related commerce entity. PropertyDescription TItemThis item represents the commerce entity type (i.e. the Model) of the copy operation. TParentThis item represents the parent of the commerce entity being copied.

Example

The following example creates a new user profile and the associated credit card information.

// Construct a CommerceCreate<> generic class specifying the UserProfile 
// commerce entity type.
var createUser = new CommerceCreate<CommerceEntity>("UserProfile");

createUser.Model.FirstName = "Joe";
createUser.Model.LastName = "Smith";
createUser.Model.Email = "joesmith@company.com";

// Create the credit card for this user using the CreateRelatedItem<>
// construct.  The relationship name passed in is defined as part of the UserProfile
// commerce entity.
var newCreditCard = new CommerceCreateRelatedItem<CommerceEntity>(
    "CreditCards",
    "CreditCard");

newCreditCard.Model.CreditCardNumber = "1234123412341234";
newCreditCard.Model.CreditCardType = "Visa";
newCreditCard.Model.CustomerName = "Joe Smith";

// Add the credit card object to the RelatedOperations list of the operation.
// This creates it and related it to the user.
createUser.RelatedOperations.Add(newCreditCard);

// Provide the return model context indicating the properties to return
// as a result of the Create operation.
createUser.Options.ReturnModel.Properties.Add("Id");

// Provide the return model queries indicating the relationships to return
// as a result of the Create operation.
createUser.Options.ReturnModelQueries.Add(
    new CommerceQueryRelatedItem<CommerceEntity>("CreditCards", "CreditCard"));

// Invoke the service by providing it the request.  This is done
// by calling createUser.ToRequest() which creates the request apropriately.
CommerceResponse response = OperationService.ProcessRequest(base.GetCurrentRequestContext(), createUser.ToRequest());

CommerceCreateOperationResponse createResponse = response.OperationResponses[0]
    as CommerceCreateOperationResponse;

Assert.IsNotNull(createResponse);
Assert.IsNotNull(createResponse.CommerceEntity);
Assert.IsNotNull(createResponse.CommerceEntity.Id);
Assert.IsNotNull(createResponse.CommerceEntity.Properties["CreditCards"]);

See Also

Other Resources

Developing with the Multi-Channel Commerce Foundation

Commerce Foundation Operations