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.dllMicrosoft.Crm.Sdk.Proxy.dll这些程序集可以在 CRM SDK 包的Bin文件夹中找到。

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提供了八种方法,允许您对系统和自定义实体以及组织元数据执行所有常见操作

先生编号 方法及说明
1

IOrganizationService.Create

创建一个记录。

2

IOrganizationService.更新

更新现有记录。

3

I组织服务。取回

检索一条记录。

4

I组织服务。检索多个

检索记录集合。

5

I组织服务。删除

删除一条记录。

6

I组织服务。联系

在记录之间创建链接。

7

IOrganizationService.解除关联

删除记录之间的链接。

8

IOrganizationService.执行

用于常见记录处理以及特殊处理,例如案例解决、重复检测等。

网络服务示例

为了了解 CRM 中的 Web 服务如何工作,我们将查看 CRM SDK 提供的示例。在此示例中,我们将创建一个新的帐户记录,对其进行更新,最后使用 CRM IOrganizationService Web 服务将其删除。

步骤 1 - 打开您提取 CRM SDK 的文件夹。现在,通过浏览到以下位置打开 QuickStartCS.sln 解决方案:SDK\SampleCode\CS\QuickStart

MSCRM Web 服务示例步骤 1

步骤 2 - 我们将探索带有简化连接的快速入门项目。打开该项目中的app.config。默认情况下,该文件中的connectionStrings部分将被注释。

MSCRM Web 服务示例步骤 2

由此,取消注释第一个连接字符串键并编辑以下三个详细信息 -

Url - 指定 CRM 实例的 URL。在我们的例子中,由于我们使用的是 CRM 的在线版本,因此您必须提及该 URL。

用户名- 您的 CRM Online 用户名。

密码- 您的 CRM Online 密码。

MSCRM Web 服务示例步骤 2 2

步骤 3 - 打开此项目中的SimplifiedConnection.cs文件和其中的 Runmethod。

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,您将看到新创建的帐户记录。

MSCRM Web 服务示例步骤 4_4

步骤 4.5 - 创建帐户后,服务将使用检索 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 - 设置记录的更新值后,使用更新 Web 服务方法将记录更新回 CRM 数据库。

_orgService.Update(retrievedAccount); 

如果您在 CRM 中打开记录,您将看到这些值已更新。

MSCRM Web 服务示例步骤 4_7

步骤 4.8 - 最后,使用删除 Web 服务方法删除记录。

_orgService.Delete(Account.EntityLogicalName, _accountId); 

如果您现在在 CRM 中刷新相同的记录,您将看到该记录不再可用,因为它已被删除。

MSCRM Web 服务示例步骤 4_8

结论

在本章中,我们讨论了 CRM 提供的两个重要的 Web 服务,以及如何从外部应用程序使用这些 Web 服务来执行各种 CRUD 操作的工作示例。