MS CRM 2011的自定义和开发（10）——CRM web服务介绍(第二部分)——IOrganizationService（二）

    上一篇文章介绍了Microsoft Dynamics CRM 2011的组织服务OrganizationService的Create、Update、Delete方法，本文介绍Associate、Disassociate和Retrieve方法。

    Associate方法的签名如下：

public virtual void Associate (
    string entityName,
    Guid entityId,
    Relationship relationship,
    EntityReferenceCollection relatedEntities
)

  从签名可以看出，Associate方法完成的功能是依据输入参数relationship指定的关联，将主要实体(entityName指定）的某个实例（entityId指定)与一组相关实体（relatedEntities）进行连接。

  下面是Associate方法的样例代码，该样例代码完成的功能是依据关联“account_primary_contact”，连接两个客户实例与联系人实例。从数据库角度讲，就是设置客户实例的primarycontactid字段值为联系人的主键值，对于多对多关系而言，系统会自动向交叉表插入数据。该方法的样例代码如下：

//创建联系人记录

Entity setupContact = new Entity("contact");
setupContact["firstname"] = "John";
setupContact["lastname"] = "Doe";
_contactId = _service.Create(setupContact);

// 创建客户记录1
Entity setupAccount1 = new Entity("account");
setupAccount1["name"] = "Example Account 1";

_account1Id = _service.Create(setupAccount1);

//创建客户记录2

Entity setupAccount2 = new Entity("account");
setupAccount2["name"] = "Example Account 2";

_account2Id = _service.Create(setupAccount2);

//创建客户记录3

Entity setupAccount3 = new Entity("account");
setupAccount3["name"] = "Example Account 3";

_account3Id = _service.Create(setupAccount3);

 

//创建关联实例，指定当前使用的关联是account_primary_contact
Relationship relationship = new Relationship("account_primary_contact");

//创建EntityReference集合，将关联信息中的相关实体引用添加到集合中

EntityReferenceCollection relatedEntities = new EntityReferenceCollection();
relatedEntities.Add(new EntityReference("account", _account1Id));
relatedEntities.Add(new EntityReference("account", _account2Id));
relatedEntities.Add(new EntityReference("account", _account3Id));

//调用Associate方法，指定主要实体的逻辑名称，主要实体的主键值，Associate方法使用的关联，以及相关实体的引用集合

_service.Associate("contact", _contactId, relationship, relatedEntities);

    Disassociate方法，从该方法的命名就可以知道，Disassociate方法和Associate方法是互逆的两个操作，Disassociate方法的签名如下：

public virtual void Disassociate (
    string entityName,
    Guid entityId,
    Relationship relationship,
    EntityReferenceCollection relatedEntities
)

  可见，Disassociate方法和Associate方法的输入参数是一样的。在调用本方法时，系统会根据relationship关联，找到相关实体的外键字段，而后，将relatedEntities集合中的记录的该外键值置为null。对于多对多关系而言，系统会根据根据entityId以及relatedEntities集合中的每个元素的主键值，从中间表中删除该数据。

  样例代码如下：

_service.Disassociate("contact", _contactId, relationship, relatedEntities);

  这条语句是基于本文前面的样例代码而来，放置于_service.Associate("contact", _contactId, relationship, relatedEntities);之后，即可完成解除连接的操作。

  Retrieve方法，用于获取某个实体的单挑数据，签名如下：

public virtual Entity Retrieve (
    string entityName,
    Guid id,
    ColumnSet columnSet
)

   该方法的输入参数有三个，分别是带查询实体的逻辑名称entityName，带查询实体实例的主键值id，以及返回列columnSet。返回值是Entity对象，Entity对象的包含的字段信息由columnSet指定。样例代码如下：

//首先，创建一条样例数据——一条客户记录，以便后续Retrieve方法使用

Entity account = new Entity("account");

account["name"] = "Fourth Coffee";

_accountId = _service.Create(account);

 

//实例化ColumnSet，以设定返回列的信息，本样例中，设定返回列是”name”以及”ownerid”
ColumnSet attributes = new ColumnSet(new string[] { "name", "ownerid" });

//调用Retrieve方法，设定查询的实体的逻辑名称”account“，设定带查询的客户实例的主键值_accountId

//返回值是一个Entity对象。
account = _service.Retrieve(“account”, _accountId, attributes);

以上，介绍了微软CRM 2011中组织服务提供的三个方法Associate、Disassociate以及Reteive方法。