CRM 2011 xRM.SDK.Relationship and the missing link

The CRM 2011 API contains a new class xRM.SDK.Relationship. Relationship manages the parent-child reference between entities and allows you to express “RelatedEntites” in a parental or referential relationship and create the whole stack in a single Create() call.  Thats the theory but it doesn’t appear to work as expected.

Consider the scenario where we have an system Account with 1:N Contacts and each Contact has a 1:N relationship with a custom entity ‘new_pet’.  According to the SDK documentation, we can create xRM.SDK.Entity instances and relate them as in the following code snippet

Entity account = new Entity("account");
account["name"] = "Shultz";
Entity contact = new Entity("contact");
contact["lastname"] = "Charlie Brown";
Entity pet = new Entity("new_pet");
pet["new_name"] = "Snoopy";

We can then express the relationships between these as

Relationship accountContactRelationship = new Relationship("contact_customer_accounts");
Relationship contactPetRelationship = new Relationship("new_petowner");

and build up parent child collections like this

// Create a collection of contacts to relate to the account, one account can have many contacts
EntityCollection contactCollection = new EntityCollection();
contactCollection.EntityName = "contact";
contactCollection.Entities.Add(contact);
// Create a collection of Pets to relate to the contact, one contact can have many pets
EntityCollection petCollection = new EntityCollection();
petCollection.EntityName = "new_pet";
petCollection.Entities.Add(pet);

then describe the relationships as…

account.RelatedEntities[accountContactRelationship] = contactCollection;
contact.RelatedEntities[contactPetRelationship] = petCollection;

When you Create() the top level Account entity, CRM 2011 creates all the Account, Contact and Pet records but only links the Account and Contact.
If you Create() the mid level Contact entity, CRM 2011 creates the Contact and Pet and correctly links them both.

Both relationships are ‘Parental’ with the only difference being the system->system and system->custom relationships.  The full code for this sample is available here.