Silverlight

發行項
07/23/2015

從 Silverlight 4 駕馭動態 CRM 4.0 API 的威力

Mark Beckner

越來越多公司實作 Microsoft Dynamics CRM 4.0 解決方案和尋找需要建立與現有 Web 服務架構的 API 可以整合的外部應用程式。

建置的 Silverlight 應用程式，可以直接互動 Microsoft Dynamics CRM 4.0 (因簡要考量以下的 CRM 4.0) 可以證明具挑戰性，因為 Silverlight 呼叫的非同步性質和其無法呼叫 CRM 4.0 Web 服務直接。在本文中，您將得到如何建置 Silverlight 應用程式可以讀取及寫入資料透過 CRM 4.0 Web 服務 API 深入的探討。

解決方案概觀

Silverlight 4 和 CRM 4.0 是這兩種功能強大的技術，但它們不是最容易整合。我將探討建立這項整合來探查 Silverlight 和 CRM 4.0 Web 服務 API 之間的非同步通訊背後的細節。

在一般的非 Silverlight 應用程式中，對 Web 服務的呼叫是同步的-呼叫，而應用程式會等候，直到收到回應。在此期間，使用者無法與應用程式進行互動，必須等到完成完整的雙向。例如 Silverlight 非同步應用程式，超出了服務的呼叫，但應用程式會繼續傳回回應之前，甚至可完全正常運作。這會建立豐富及動態的使用者經驗，但這會造成程式開發人員更大的要求。

若要了解如何可能會發生這種通訊，我將提供幾種功能。首先，我將探討如何設定 [Silverlight 應用程式並透過 Web 服務，做為包裝函式的 CRM 4.0 API 進行互動時所需的步驟。接下來，我會逐步執行使用 CRM 4.0 API，以及如何讀取和寫入資料，使用 Web 服務包裝函式的詳細資料。我將使用核心系統使用者在 CRM 4.0 的實體，並查看使用動態的實體。最後，我將探討如何處理結果集傳回到 silverlight 的作業。最後，您可以輕鬆建立您自己的 Silverlight 4.0 (CRM) 進行整合。

建立 Silverlight 4 向

有幾個步驟，以取得設定為與 CRM 4.0 互動的 Silverlight 應用程式逐步完成。雖然可以直接從 Silverlight 專案參考的 CRM 4.0 SDK 或 Web 服務 API，大部份的介面和方法實際上不能從程式碼呼叫。若要與 CRM 4.0 API 進行互動，必須建立包裝函式 Web 服務。這個 Web 服務會仲介處理的 Silverlight Silverlight CRM 4.0 API 應用程式之間的格式，可以由的呼叫。包裝函式 Web 服務可以直接加入至 SilverlightCRMDemo.Web 應用程式。

藉由呼叫 CRM40SilverlightDemo 的 Visual Studio 2010年中建立新的 Silverlight 方案開始此程序。在 Visual Studio 中建立 Silverlight 應用程式，都一定會建立兩個專案。有核心 Silverlight 應用程式。第二個是 ASP。NET 應用程式內嵌的 Silverlight 應用程式在 Web 網頁。這個 ASP。NET 應用程式也會是主要的 Web 服務包裝函式使用 CRM 4.0 API 進行互動。 Silverlight 應用程式會參考這個 Web 服務，透過服務參考。

若要建立 Web 服務包裝函式，請先 ASP 中加入新的 Web 服務。NET 應用程式，並呼叫 CrmServiceWrapper。例如，您可以新增兩個 Web 方法到服務，一是取得 CRM 資料，另一個回傳 CRM 資料。 圖 1 現在應該看起來會顯示這些截取出來的方法。一次，您要取得 Silverlight 通訊的應用程式成功地使用這個包裝函式] 服務，在更新至實際的 CRM 4.0 API 的呼叫這些方法。

圖 1] 的 Web 方法 Stub

public class CrmServiceWrapper : System.Web.Services.WebService
{
  [WebMethod]
  public string GetCRMData()
  {
    return "This is the stubbed return for retrieving";
  }
 
  [WebMethod]
  public string PostCRMData()
  {
    return "This is the stubbed return for posting data";
  }
}

當 Web 服務包裝函式加入至 ASP。NET 應用程式，將參考加入至它的 Silverlight 應用程式最簡單的方法是在偵錯模式中執行，並擷取偵錯工具的執行應用程式的位置的 URL (您可以只是擷取 URL 從瀏覽器視窗，就會出現)。一旦擷取，您可以加入新的服務參考稱為 CrmServiceReference 的 Silverlight 應用程式] 及 [貼上此 URL 中的。所有相關的組態檔和程式碼將自動修正。如果您決定不要這樣做，您必須處理跨網域參照例外狀況，而且不少的安裝程式，才能成功地偵錯應用程式。

既然這個參考存在，實際的程式碼，就在 Silverlight 應用程式中可以進行。程式碼是由設定每個 Web 方法的事件處理常式，並建立兩種方法可以處理的資料，當完成這些 Web 方法呼叫所組成。在顯示的程式碼圖 2 可以直接新增至 Silverlight 應用程式中的 MainPage.xaml.cs 檔案。執行這會同時執行這兩種方法。

圖 2 將程式碼加入至 MainPage.xaml.cs

using CRM40SilverlightDemo.CrmServiceReference;
 
public partial class MainPage : UserControl
{
  public MainPage()
  {
    InitializeComponent();
 
    // Call the GetCRMData Web method.
CrmServiceWrapperSoapClient proxyGet =
      new CrmServiceWrapperSoapClient();
    proxyGet.GetCRMDataCompleted +=
      new EventHandler<GetCRMDataCompletedEventArgs>(proxy_GetCRMDataCompleted);
    proxyGet.GetCRMDataAsync();
 
    // Call the PostCRMData Web method.
CrmServiceWrapperSoapClient proxyPost = new CrmServiceWrapperSoapClient();
    proxyPost.PostCRMDataCompleted +=
      new EventHandler<PostCRMDataCompletedEventArgs>(proxy_PostCRMDataCompleted);
    proxyPost.PostCRMDataAsync();
  }
 
  // Called asynchronously when the GetCRMData Web method returns data.
void proxy_GetCRMDataCompleted(object sender, GetCRMDataCompletedEventArgs e)
  {
    // Do something with the data returned.
string result = e.Result.ToString();
  }
 
  // Called asynchronously when the PostCRMData Web method returns data.
void proxy_PostCRMDataCompleted(object sender, PostCRMDataCompletedEventArgs e)
  {
    // Do something with the data returned.
string result = e.Result.ToString();
  }
}

當您已驗證的 Silverlight 應用程式正在執行未發生錯誤，及從 Web 服務傳回資料時，您可以開啟您的注意，若要建立 CRM 4.0 api 的呼叫。這些呼叫將所有包含在 Web 服務包裝函式 GetCRMData 和 PostCRMData 的 Web 方法已經建立。

與 CRM 4.0 API 進行互動

有兩個主要的 Web 服務可透過 CRM 4.0： CRMService 和 MetadataService。這些 Web 服務通常可以從任何專案參考 (但實際上不允許的最多的功能，當參考的 Silverlight 應用程式)。使用 API 的最常見與最有效率的方式使用 Microsoft Dynamics CRM SDK (可從 bit.ly/6M3PvV)。 SDK 包含許多類別和方法，它簡化了之間的通訊。Net 程式碼和 CRM 4.0 Web 服務。在此區段中，您將學習如何使用 Web 服務包裝函式從 SDK 的 API 進行互動。

第一個步驟是參考適當的 CRM SDK 組件。在 ASP。NET 應用程式裝載 Web 服務包裝函式，加入兩個 SDK 組件的參考： microsoft.crm.sdk.dll 和 microsoft.crm.sdktypeproxy.dll。這些已被參考，一旦將適當的指示詞加入 CrmServiceWrapper.asmx 頁面頂端，如下所示：

using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;
using Microsoft.Crm.Sdk.Query;

下一個步驟是撰寫程式碼來具現化可讓您連接到 CRM 4.0 執行個體的 CRM 服務。這段程式碼會使用 GetCRMData 和 PostCRMData 的 Web 方法，因此會存放在自己的方法。這個方法 (顯示在圖 3) 需要兩個索引鍵欄位： CRM 4.0 執行個體和主要 (位於「 /MSCRMServices/2007/crmservice.asmx 」) 的 CRM 服務的 URL 的組織名稱。請注意這些欄位最安裝後編譯程式碼的簡單修改組態檔中。

圖 3 GetCRMService 方法

static public CrmService GetCRMService()
{
  CrmService service = new CrmService();
  CrmAuthenticationToken token =
    new Microsoft.Crm.Sdk.CrmAuthenticationToken();
  token.OrganizationName = "Contoso";
  service.Url = "http://localhost:5555/MSCRMServices/2007/crmservice.asmx";
  service.Credentials = System.Net.CredentialCache.DefaultCredentials;
  service.CrmAuthenticationTokenValue = token;
  return service;
}

查詢 CRM 資料

您現在可以開啟您注意到從 CRM 4.0 查詢的資料。請務必知道有兩種類型的 CRM 4.0 中的實體：核心系統的實體和自訂項目。可以與自訂項目比更輕鬆地一起的核心系統的實體。根據預設，所有核心實體屬性可以擷取到 C# 中的強型別物件。雖然另一個方法可讓它們被視為強型別物件，也自訂項目通常查詢以動態的實體。我將示範查詢使用兩種類型的實體的資料。

查詢的核心系統實體的範例 — 系統使用者實體，會顯示在圖 4。這段程式碼會取代本文稍早已經截取相同名稱的 Web 方法。在這個新的程式碼，所有的系統使用者的查詢 CRM 4.0 中，您會看到幾個重要方法。首先，處理物件的型別為"systemuser"。所有核心實體有它們自己的型別。其次，所傳回的結果是 XML 文件的字串表示。

圖 4 查詢系統使用者實體

[WebMethod]
public string GetCRMData()
{
  // This will return all users in CRM in a single XML structure.
StringBuilder xml = new StringBuilder();
  CrmService service = GetCRMService();
 
  QueryExpression query = new QueryExpression();
  query.EntityName = "systemuser";
  query.ColumnSet = new AllColumns();
 
  RetrieveMultipleRequest retrieve = new RetrieveMultipleRequest();
  retrieve.Query = query;
  retrieve.ReturnDynamicEntities = false;
 
  RetrieveMultipleResponse retrieved =
    (RetrieveMultipleResponse)service.Execute(retrieve);
 
  xml.Append("<Users>");
 
  for (int i = 0; i <
    retrieved.BusinessEntityCollection.BusinessEntities.Count; i++)
  {
    systemuser user =
      (systemuser)retrieved.BusinessEntityCollection.BusinessEntities[i];
 
    // Create a string represenation to return to Silverlight app.
xml.Append("<User");
    xml.Append(" FirstName ='" + user.firstname + "'");
    xml.Append(" LastName = '" + user.lastname + "'");
    xml.Append(" SystemUserId = '" + user.systemuserid.ToString() + "'");
    xml.Append(" JobTitle = '" + user.jobtitle + "'");
    xml.Append("/>");
  }
 
  xml.Append("</Users>");
 
  return xml.ToString();
}

您會發現將資料傳回至 Silverlight 的選項有仍然十分有限。比方說，您不能傳回 BusinessEntityCollection，才能使用，因為 Silverlight 無法直接使用 API。第二，就會受到限制傳遞至 Silverlight 的 XML，透過 Web 服務。因此，在結束時，簡單的字串處理可能是您最佳的選擇。

查詢的自訂實體可以稍微更複雜。若要擷取資料最常見的方式是使用動態的實體來擷取結果 (擷取這類的範例所示圖 5)。這種方法，是在處理中具有篩選器的查詢運算式中的特定屬性。雖然所有項目，可以 IntelliSense 無法幫助出許多。

[圖 5 擷取使用動態的實體

public static DynamicEntity GetCRMEntity(
  CrmService tmpService, String entityId, String entityName)
{
  DynamicEntity crmEntity = null;
 
  TargetRetrieveDynamic targetRetrieve = new TargetRetrieveDynamic();
 
  // Set the properties of the target.
targetRetrieve.EntityName = entityName;
  targetRetrieve.EntityId = new Guid(entityId);
 
  // Create the request object.
RetrieveRequest retrieve = new RetrieveRequest();
 
  // Set the properties of the request object.
retrieve.Target = targetRetrieve;
  retrieve.ColumnSet = new AllColumns();
 
  // Retrieve as a DynamicEntity.
retrieve.ReturnDynamicEntities = true;
 
  // Execute the request.
RetrieveResponse retrieved = (RetrieveResponse)tmpService.Execute(retrieve);
 
  // Extract the DynamicEntity from the request.
DynamicEntity entity = (DynamicEntity)retrieved.BusinessEntity;
 
  crmEntity = entity;
 
  return crmEntity;
}

如果您想要在 Visual Studio 中有完整的程式實體結構的可視性和與它互動的標準的實體方式相同，可能是最常見的實體的動態方法，雖然您可以建立 CrmService 的 proxy。在許多情況下，這可以大幅改進開發經驗，並啟用更多的彈性，在撰寫程式碼的方式。 Proxy 會只產生的 C# 檔案，根據最新的執行個體的 CrmService WSDL。若要建立主要的 CrmService 服務的 proxy 類別，開啟 Visual Studio 的命令提示字元輸入下列文字，取代適當的連結，要在 crmservice.asmx 頁面的 URL：

wsdl.exe /out:CrmSdk.cs /namespace:CRM40SilverlightDemo.WebReferences.CrmSdkhttp://localhost:5555/mscrmservices/2007/crmservice.asmx?wsdl

這個命令會建立稱為 CrmSdk.cs 目錄中，從您用來執行可執行檔 wsdl.exe C# 檔案。這個檔案應該加入至您的專案。一旦加入後，您可以使用完全相同的方式，核心系統的實體為任何自訂的項目。如果實體變更，只會更新您的 proxy C# 檔案，且新的屬性 (或其他修改) 會使用。基於目前的練習的目的，將不會使用 proxy C# 檔案。

更新 CRM 4.0 資料

需要看過如何從 CRM 4.0 中擷取資料，您可以在現在逐步張貼資料。在顯示的程式碼圖 6 示範如何更新系統使用者資料錄。它需要兩個屬性會傳入： CRM 4.0 記錄和暱稱的唯一識別項。若要在這些字串中傳送，一行程式碼必須修改 MainPage.xaml.cs，此處所示：

proxyPost.PostCRMDataAsync("f04b02d9-ad5f-e011-a513-000c29330bd5","My Nickname");

請注意，ID 是硬式編碼在呼叫 PostCRMData 方法。您要使用動態抓取識別碼的機制。

圖 6 張貼 CRM 4.0 資料

[WebMethod]
public string PostCRMData(string userId, string nickname)
{
  CrmService service = GetCRMService();
 
  Key kid = new Key();
  kid.Value = new Guid(userId);
  systemuser entity = new systemuser();
  entity.systemuserid = kid;
 
  entity.
nickname = nickname;
 
  service.Update(entity);
 
  return "success";
}

處理 Silverlight 中的結果

此時，方案應該擷取及公佈 CRM 4.0 的進出資料。不過，不是執行到 silverlight 的作業傳回的字串結果。 GetCRMData 方法會傳回資料字串，包含 XML 文件的所有使用者資料錄，但該做什麼？根據控制項，就可以直接繫結至 XML，或您可以透過傳回 XML 剖析，並處理的個別資料元素。

傳回的結果上執行迴圈範例所示圖 7。這段程式碼會示範如何載入 XML 文件與資料執行迴圈中的字串。在使用 Silverlight 中的 XML 文件時，最多用途的功能來自 XDocument 類別。這可以透過將參考加入至 System.Xml.Linq Silverlight 專案中。

圖 7 使用 XDocuments

void proxy_GetCRMDataCompleted(object sender, GetCRMDataCompletedEventArgs e)
{
  XDocument xDoc = XDocument.Parse(e.Result);
 
  string firstName;
  string lastName;
  string ID;
  string title;
 
  // Loop through the results.
foreach (XElement element in xDoc.Descendants("User"))
  {
    firstName = GetAttributeValue(element, "FirstName");
    lastName = GetAttributeValue(element, "LastName");
    ID = GetAttributeValue(element, "SystemUserId");
    title = GetAttributeValue(element, "JobTitle");
  }
}
 
private string GetAttributeValue(XElement element, string strAttributeName)
{
  if (element.Attribute(strAttributeName) != null)
  {
    return element.Attribute(strAttributeName).Value;
  }
  return string.Empty;
}

無窮的可能性

整合的兩個技術有無限的可能性。立即的下一個步驟，您可能想要查看的是方法的例外狀況處理 (許多 Silverlight 控制項隱藏例外狀況，所以您必須處理這種情況的基礎) 和整合使用不同的控制項。無論您採取的方向，您已經準備好您建置 Silverlight 的解決方案，讀取和寫入資料 CRM 4.0 所需要的所有項目。

標記 Beckner 是創立者 Inotek 的諮詢群組 LLC。他在跨 Microsoft 堆疊，包括 BizTalk、 SharePoint、動態 CRM 和一般工作。Net 開發。他可以連絡到在 mmbeckner@inotekgroup.com。

感謝給下列技術專家來檢閱這份文件： 陳俊銘先生