MS CRM 2011的自定義和開發（10）——CRM web服務介紹(第二部分)——IOrganizationService（三）

    本篇文章，介紹Microsoft Dynamics CRM 2011的組織服務中的RetrieveMultiple方法。

    RetreiveMultiple方法，用於獲取實體的多個實例，該方法的簽名如下：

public virtual EntityCollection RetrieveMultiple (
    QueryBase query
)

   RetreiveMultiple方法的輸入參數是QueryBase類的對象。QueryBase是一個基類，有多個子類，其類樹如下圖所示：

    由上圖可見，QueryBase有三個派生類，分別是QueryByAttribute、QueryExpression以及FetchExpression。下面依次進行介紹。

    QueryByAttribute類。使用QueryByAttribute類生成根據一組值測試一組屬性的查詢。該類的主要屬性列表如下所示：

屬性	說明
EntityName	指定檢索哪種類型的實體。一個查詢表達式僅檢索一個實體類型集合。
ColumnSet	指定要檢索的屬性（列）的集合。
Attributes	指定查詢中選擇的屬性集合。
Values	指定查詢執行時要查找的屬性值。
Orders	指定從查詢返回記錄的順序。
PageInfo	指定從查詢返回的頁數和每頁的記錄數。

    借由QueryByAttribute，形成的等價SQL語句如下：

Select
    [ColumnSet]
From
    [EntityName]
Where
    Attibutes[1] = Values[1] And
    Attibutes[2] = Values[2] And
    .......
    Attibutes[N] = Values[N]

    其中，所有處於方括號（“[”與“]”）之中的內容，均是來自於QueryByAttribute的各個屬性值。樣例代碼如下：

//創建QueryByAttribute實例，指定待檢索實體的邏輯名稱account
QueryByAttribute queryByAttribute = new QueryByAttribute("account");

//指定返回結果包含的數據列集合
queryByAttribute.ColumnSet = new ColumnSet("name", "address1_city", "emailaddress1");


//指定檢索條件，address1_city = ‘Detroit’

//首先指定檢索條件的列字段信息
queryByAttribute.Attributes.AddRange("address1_city");
//接着指定檢索條件中的列值信息
queryByAttribute.Values.AddRange("Detroit");

//指定檢索條件，accountnumber = ‘abc’

//首先指定檢索條件的列字段信息
queryByAttribute.Attributes.AddRange("accountnumber");
//接着指定檢索條件中的列值信息
queryByAttribute.Values.AddRange("abc");


//調用組織服務的RetrieveMultiple方法，將queryByAttribute對象傳遞給RetrieveMultiple方法
EntityCollection retrieved = _serviceProxy.RetrieveMultiple(queryByAttribute);
//遍歷返回結果
foreach (var c in retrieved.Entities)
{ 
28     System.Console.WriteLine("Name: " + c.Attributes["name"]);
    System.Console.WriteLine("Address: " + c.Attributes["address1_city"]);
    System.Console.WriteLine("E-mail: " + c.Attributes["emailaddress1"]); 
} 

    FetchExpression，最主要的屬性就是Query屬性，可以將FetchXml字符串賦值給Query屬性。FetchXml是MS CRM的專有查詢語言，FetchXml包括能夠計算總和、平均值、最小值、最大值和計數的分組和聚合函數：sum/avg/min/max/count(*)/count(屬性名稱)。FetchXml的書寫非常之繁復，可以通過第三方提供的工具，或者通過“高級查找”界面中的“下載FetchXml”獲得。首先，利用CRM提供的圖形化界面創建需要的查找，而后點擊Ribbon工具條中的“下載FetchXml”按鈕，如下圖所示：

    對應於上面查找條件的FetchXml語句如下圖所示：

    將這個FetchXml字符串賦值給FetchExpression的Query屬性，而后調用RetrieveMultiple方法，將FetchExpression對象作為參數傳遞給該方面即可。下面是樣例代碼：

string query = “<fetch version='1.0' output-format='xml-platform' mapping='logical' distinct='false'><entity name='account'><attribute name='address1_telephone1' /><attribute name='customersizecode' /><attribute name='accountratingcode' /><attribute name='accountnumber' /><attribute name='name' /><attribute name='accountid' /><order attribute='accountnumber' descending='false' /><order attribute='name' descending='false' /><filter type='and'><condition attribute='primarycontactid' operator='not-null' /><condition attribute='statecode' operator='eq' value='0' /></filter><link-entity name='contact' from='contactid' to='primarycontactid' visible='false' link-type='outer' alias='a_410707b195544cd984376608b1802904'><attribute name='gendercode' /><attribute name='telephone1' /><attribute name='fullname' /></link-entity></entity></fetch>”;

FetchExpression fetchExpression = new FetchExpression(query);

EntityCollection retrieved = _serviceProxy.RetrieveMultiple(fetchExpression);

    QueryExpression。使用QueryExpression類，可以生成復雜查詢，可以使用 ConditionExpression、ColumnSet 和 FilterExpression 類為QueryExpression設置查詢參數。QueryExpression 類可用於創建復雜查詢。QueryByAttribute 類旨在作為簡單的搜索方式，用於搜索屬性匹配指定值的實體。

    QueryExpression類的主要屬性如下表所示：

屬性	說明
EntityName	指定將檢索哪種類型的實體。一個查詢表達式僅檢索一個實體類型集合。
ColumnSet	指定要檢索的屬性（列）的集合。
Criteria	指定復雜條件和邏輯篩選器表達式，用於篩選查詢結果。
Distinct	指定查詢的結果是否包含重復記錄。
LinkEntities	指定多個實體類型之間的鏈接。
Orders	指定從查詢返回的記錄的順序。
PageInfo	指定從查詢返回的頁數和每頁中的記錄數量。

   非常重要的一個屬性是Criteria，該屬性是FilterExpression類型。可以使用FilterExpression類生成表示多個條件的查詢。例如，可以創建等效於 SQL 語句（如 ([FirstName] = 'Joe' OR [FirstName] = 'John') AND [City] = 'Redmond'）的查詢表達式。FilterExpression的屬性列表如下所示：

屬性	說明
Conditions	獲取或設置包括屬性、條件運算符和屬性值的條件表達式。
FilterOperator	獲取或設置邏輯 AND/OR 篩選器運算符。它使用 LogicalOperator 枚舉進行設置。
Filters	獲取或設置用於篩選查詢結果的條件和邏輯篩選器表達式的層次結構。

    FilterExpression 類還包含一些幫助程序方法，通過它們可以更輕松地創建查詢。AddCondition 方法可將 ConditionExpression 添加到 FilterExpression 的 Conditions 屬性中，以減少構造條件表達式所需的代碼量。AddFilter 方法可將新篩選器添加到 FilterExpression 類的 Filters 屬性中。

    除了Criteria之外，還需要注意的是LinkEntities屬性，該屬性用以指定多個實體之間的鏈接，從而形成 Account Join Contact On Account.PrimaryContactId =  Contact.ContactId Join SystemUser On Account.OwnerId = SystemUser.SystemUserId樣式的SQL語句。不過呢，該屬性是只讀的，需要使用

    AddLink ( string linkToEntityName, string linkFromAttributeName, string linkToAttributeName )

或者

    AddLink (string linkToEntityName, string linkFromAttributeName, string linkToAttributeName, JoinOperator joinOperator)方法創建實體之間的鏈接。

    使用QueryExpression的樣例代碼如下所示，：

//創建樣例數據

//創建聯系人記錄

Entity contact = new Entity("contact");
contact.Attributes["firstname"] = "ContactFirstName";
contact.Attributes["lastname"] = "ContactLastName";
Guid contactId = _orgService.Create(contact, null);

//創建三個客戶記錄，指定客戶名稱分別為“Test Account1”、“Test Account2”、“Test Account3”，並指定三個客戶記錄的主要聯系人屬性值為之前創建的聯系人記錄

Entity account = new Entity("account");
account["name"] = "Test Account1";
EntityReference primaryContactId = new EntityReference("contact", contactId);
account["primarycontactid"] = primaryContactId;

Guid accountId1 = _orgService.Create(account, null);
account["name"] = "Test Account2";
Guid accountId2 = _orgService.Create(account, null);
account["name"] = "Test Account3";
Guid accountId3 = _orgService.Create(account, null);

//創建QueryExpression實例，
QueryExpression qe = new QueryExpression();

//指定查詢表達式要查詢的實體為account
qe.EntityName = "account";

//指定返回值的列信息
qe.ColumnSet = new ColumnSet();
qe.ColumnSet.Columns.Add("name");

//指定鏈接的實體的信息

qe.LinkEntities.Add(new LinkEntity("account", "contact", "primarycontactid", "contactid", JoinOperator.Inner));
qe.LinkEntities[0].Columns.AddColumns("firstname", "lastname");
qe.LinkEntities[0].EntityAlias = "primarycontact";

//調用RetrieveMultiple方法

EntityCollection ec = _orgService.RetrieveMultiple(qe);

Console.WriteLine("Retrieved {0} entities", ec.Entities.Count);

//遍歷返回結果
foreach (Entity act in ec.Entities)
{
    Console.WriteLine("account name:" + act["name"]);
    Console.WriteLine("primary contact first name:" + act["primarycontact.firstname"]);
    Console.WriteLine("primary contact last name:" + act["primarycontact.lastname"]);
}