Microsoft Dynamics CRM - Web 服務

---

---

Microsoft Dynamics CRM 提供兩種重要的 Web 服務，用於從外部應用程式訪問 CRM 並呼叫 Web 方法以執行常見的業務資料操作，例如在 CRM 中建立、刪除、更新和查詢。

考慮以下場景：

• 您有一個外部 .NET 應用程式，需要與 CRM 通訊。例如，當您的外部應用程式註冊新客戶時，您可能希望在 CRM 中插入一個聯絡人記錄。

• 或者，您可能希望在 CRM 中搜索記錄並在您的外部應用程式中顯示搜尋結果。

在這種情況下，您可以使用 CRM 公開的 Web 服務在您的應用程式中使用它們，並在 CRM 中執行建立、刪除、更新和查詢操作。

IDiscoveryService Web 服務

此 Web 服務返回指定使用者所屬的組織列表以及每個組織的 URL 端點。

IOrganizationService Web 服務

此 Web 服務是用於訪問 CRM 中的資料和元資料的主要 Web 服務。IOrganizationService 使用兩個重要的程式集 – **Microsoft.Xrm.Sdk.dll** 和 **Microsoft.Crm.Sdk.Proxy.dll**。這些程式集可以在 **Bin** 資料夾內的 CRM SDK 包中找到。

Microsoft.Xrm.Sdk.dll

此程式集定義了核心 xRM 方法和型別，包括用於簡化與 Microsoft Dynamics CRM 連線的代理類、身份驗證方法和服務契約。

Microsoft.Crm.Sdk.Proxy.dll

此程式集定義了非核心訊息的請求和響應，以及與組織資料一起使用所需的列舉。以下是這兩個程式集支援的名稱空間。

每個程式集都支援某些訊息，這些訊息將用於處理儲存在任何實體中的資料。可以在以下連結中找到它們支援的訊息的完整列表：

**支援的 xRM 訊息** - https://msdn.microsoft.com/en-us/library/gg334698.aspx

**支援的 CRM 訊息** - https://msdn.microsoft.com/en-us/library/gg309482.aspx

IOrganizationService Web 服務方法

**IOrganizationService** 提供八種方法，允許您對系統和自定義實體以及組織元資料執行所有常見操作。

Web 服務示例

為了瞭解 Web 服務在 CRM 中的工作方式，我們將研究 CRM SDK 提供的一個示例。在此示例中，我們將使用 CRM **IOrganizationService** Web 服務建立一個新的帳戶記錄、更新它，然後最終刪除它。

**步驟 1** - 開啟您解壓 CRM SDK 的資料夾。現在透過瀏覽到以下位置開啟 QuickStartCS.sln 解決方案：SDK\SampleCode\CS\QuickStart

**步驟 2** - 我們將探索使用 **簡化連線** 專案的 **QuickStart**。開啟此專案中的 **app.config**。預設情況下，此檔案中的 **connectionStrings** 部分將被註釋。

從中取消第一個連線字串鍵的註釋並編輯以下三個細節：

**Url** - 指定您的 CRM 例項的 URL。在我們的例子中，由於我們使用的是 CRM 的線上版本，您必須提及該 URL。

**使用者名稱** - 您的 CRM Online 使用者名稱。

**密碼** - 您的 CRM Online 密碼。

**步驟 3** - 開啟此專案中的 **SimplifiedConnection.cs** 檔案及其內部的 Run 方法。

public void Run(StringconnectionString, boolpromptforDelete) {
   try {
      
      // Establish a connection to the organization web service using CrmConnection.
      Microsoft.Xrm.Client.CrmConnection connection =
         CrmConnection.Parse(connectionString);
      
      // Obtain an organization service proxy.
      // The using statement assures that the service proxy will be properly disposed.
      using(_orgService = new OrganizationService(connection)) {

         //Create any entity records this sample requires.
         CreateRequiredRecords();
         
         // Obtain information about the logged on user from the web service.
         Guid userid = ((WhoAmIResponse)_orgService.Execute(new WhoAmIRequest())).UserId;
         SystemUser systemUser = (SystemUser)_orgService.Retrieve("systemuser",userid,
            new ColumnSet(newstring[]{"firstname","lastname"}));
         
         Console.WriteLine("Logged on user is {0} {1}.",
            systemUser.FirstName,systemUser.LastName);

         // Retrieve the version of Microsoft Dynamics CRM.
         RetrieveVersionRequest versionRequest = new RetrieveVersionRequest();
         RetrieveVersionResponse versionResponse =
            (RetrieveVersionResponse)_orgService.Execute(versionRequest);
         Console.WriteLine("Microsoft Dynamics CRM version {0}.",
            versionResponse.Version);
         
         // Instantiate an account object. Note the use of option set
         enumerations defined in OptionSets.cs.
         
         // Refer to the Entity Metadata topic in the SDK documentation to
         determine which attributes must
         
         // be set for each entity.
         Account account = new Account{Name = "Fourth Coffee"};
         account.AccountCategoryCode = new OptionSetValue(
            (int)AccountAccountCateg oryCode.PreferredCustomer);
         account.CustomerTypeCode = new OptionSetValue(
            (int)AccountCustomerTypeCod e.Investor);
         
         // Create an account record named Fourth Coffee.
         _accountId = _orgService.Create(account);
         Console.Write("{0} {1} created, ",account.LogicalName,account.Name);
         
         // Retrieve the several attributes from the new account.
         ColumnSet cols = new ColumnSet(
            new String[]{"name","address1_postalcode","lastusedincampaign"});
         Account retrievedAccount =
            (Account)_orgService.Retrieve("account", _accountId, cols);
         Console.Write("retrieved, ");

         // Update the postal code attribute.
         retrievedAccount.Address1_PostalCode = "98052";

         // The address 2 postal code was set accidentally, so set it to null.
         retrievedAccount.Address2_PostalCode = null;

         // Shows use of a Money value.
         retrievedAccount.Revenue = new Money(5000000);

         // Shows use of a Boolean value.
         retrievedAccount.CreditOnHold = false;
         
         // Update the account record.
         _orgService.Update(retrievedAccount);
         Console.WriteLine("and updated.");
         
         // Delete any entity records this sample created.
         DeleteRequiredRecords(promptforDelete);
      } 
   } 
   // Catch any service fault exceptions that Microsoft Dynamics CRM throws.
   catch(FaultException<microsoft.xrm.sdk.organizationservicefault>) {

      // You can handle an exception here or pass it back to the calling method.
      throw;
   }
}

**步驟 4** - 此方法基本上演示了使用 CRM Web 服務的所有 CRUD 操作。程式碼首先建立一個組織例項，然後建立一個帳戶記錄，更新建立的記錄，然後最終刪除它。讓我們看一下這段程式碼的重要組成部分。要在此程式碼執行時檢視 CRM 中的即時更改，您可以逐步除錯此程式碼（如下所述），並同時檢視 CRM 中的更改。

**步驟 4.1** - 使用我們在 **步驟 2** 中修改的連線字串建立與組織的連線。

Microsoft.Xrm.Client.CrmConnection connection = CrmConnection.Parse(connectionString);

**步驟 4.2** - 獲取 CRM 組織 Web 服務的代理例項。

_orgService = new OrganizationService(connection) 

**步驟 4.3** - 建立一個新的帳戶實體物件並設定其名稱、AccountCategoryCode 和 CustomerTypeCode。

Account account = new Account{Name = "Fifth Coffee"}; 
account.AccountCategoryCode = new OptionSetValue(
   (int)AccountAccountCategoryCode.P referredCustomer); 
account.CustomerTypeCode = new OptionSetValue(
   (int)AccountCustomerTypeCode.Investor); 

**步驟 4.4** - 使用組織服務的 Create 方法建立新記錄。

_accountId = _orgService.Create(account); 

如果您導航到 CRM，您將看到一個新建立的帳戶記錄。

**步驟 4.5** - 建立帳戶後，服務將使用 Retrieve Web 服務方法從 CRM 檢索回記錄。

ColumnSet cols = new ColumnSet(new String[]{
   "name","address1_postalcode","lastusedincampaign"}); 
Account retrievedAccount = 
   (Account)_orgService.Retrieve("account", _accountId, cols); 

**步驟 4.6** - 獲取檢索到的記錄後，您可以設定記錄的更新值。

retrievedAccount.Address1_PostalCode = "98052"; 
retrievedAccount.Address2_PostalCode = null; 
retrievedAccount.Revenue = new Money(5000000); 
retrievedAccount.CreditOnHold = false; 

**步驟 4.7** - 設定記錄的更新值後，使用 Update Web 服務方法將記錄更新回 CRM 資料庫。

_orgService.Update(retrievedAccount); 

如果您在 CRM 中開啟該記錄，您將看到這些值已在那裡更新。

**步驟 4.8** - 最後，使用 Delete Web 服務方法刪除記錄。

_orgService.Delete(Account.EntityLogicalName, _accountId); 

如果您現在重新整理 CRM 中的同一記錄，您將看到該記錄不再可用，因為它已被刪除。

結論

在本章中，我們處理了 CRM 提供的兩個重要的 Web 服務，以及如何從外部應用程式使用這些 Web 服務執行各種 CRUD 操作的工作示例。