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

Web 服务示例

要了解 CRM 中的 Web 服务如何工作，我们将查看 CRM SDK 提供的示例。在此示例中，我们将使用 CRM IOrganizationService Web 服务创建一个新的帐户记录、更新它，然后最终将其删除。

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

步骤 2 − 我们将探索 QuickStart 和 Simplified Connection 项目。在此项目中打开 app.config。默认情况下，此文件中的 connectionStrings 部分将被注释掉。

从这里，取消注释第一个连接字符串键并编辑以下三个详细信息 −

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

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

密码 −您的 CRM Online 密码。

步骤 3 − 打开此项目中的 SimplifiedConnection.cs 文件，并在其中运行 Runmethod。

public void Run(StringconnectionString, boolpromptforDelete) {
   try {
      
        // 使用 CrmConnection 建立与组织 Web 服务的连接。
        Microsoft.Xrm.Client.CrmConnection connection =
        CrmConnection.Parse(connectionString);
        
        // 获取组织服务代理。
        // using 语句确保服务代理将被正确处置。
        using(_orgService = new OrganizationService(connection)) {
        
        // 创建此示例所需的任何实体记录。
        CreateRequiredRecords();
        
        // 从 Web 服务获取有关已登录用户的信息。
        Guid userid = ((WhoAmIResponse)_orgService.Execute(new WhoAmIRequest())).UserId;
        SystemUser systemUser = (SystemUser)_orgService.Retrieve("systemuser",userid,
        new ColumnSet(newstring[]{"firstname","lastname"}));
        
        Console.WriteLine("已登录用户为 {0} {1}。",
        systemUser.FirstName,systemUser.LastName);
        
        // 检索 Microsoft Dynamics CRM 的版本。
        RetrieveVersionRequest versionRequest = new RetrieveVersionRequest();
        RetrieveVersionResponse versionResponse =
        (RetrieveVersionResponse)_orgService.Execute(versionRequest);
        Console.WriteLine("Microsoft Dynamics CRM version {0}.",
        versionResponse.Version);
        
        // 实例化一个帐户对象。请注意 OptionSets.cs 中定义的选项集枚举的使用。
        
        // 请参阅 SDK 文档中的实体元数据主题，以确定必须为每个实体设置哪些属性。
        Account account = new Account{Name = "Fourth Coffee"};
        account.AccountCategoryCode = new OptionSetValue(
        (int)AccountAccountCategoryCode.PreferredCustomer);
        account.CustomerTypeCode = new OptionSetValue(
        (int)AccountCustomerTypeCod e.Investor);
        
        // 创建名为 Fourth Coffee 的帐户记录。
        _accountId = _orgService.Create(account);
        Console.Write("{0} {1} created, ",account.LogicalName,account.Name);
        
        // 从新帐户中检索几个属性。
        ColumnSet cols = new ColumnSet(
        new String[]{"name","address1_postalcode","lastusedincampaign"});
        Account removedAccount =
        (Account)_orgService.Retrieve("account", _accountId, cols);
        Console.Write("retrieved, ");
        
        // 更新邮政编码属性。
        removedAccount.Address1_PostalCode = "98052";
        
        // 地址 2 的邮政编码是意外设置的，因此将其设置为 null。
        removedAccount.Address2_PostalCode = null;
        
        // 显示 Money 值的使用。
        retrievedAccount.Revenue = new Money(5000000);
        
        // 显示布尔值的使用。
        retrievedAccount.CreditOnHold = false;
        
        // 更新帐户记录。
        _orgService.Update(retrievedAccount);
        Console.WriteLine("and updated.");
        
        // 删除此示例创建的任何实体记录。
        DeleteRequiredRecords(promptforDelete);
      } 
   } 
    // 捕获 Microsoft Dynamics CRM 引发的任何服务故障异常。
    catch(FaultException<microsoft.xrm.sdk.organizationservicefault>) {
    
        // 您可以在此处处理异常或将其传递回调用方法。
        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 − 创建一个新的 Account 实体对象并设置其 Name、AccountCategoryCode 和 CustomerTypeCode。

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

Step 4.4 − Creates the new record using the Create method of organization service.

_accountId = _orgService.Create(account); 

如果您导航到 CRM，您将看到新创建的帐户记录。

步骤 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);
r​​etrievedAccount.CreditOnHold = false;

步骤 4.7 − 设置记录的更新值后，使用更新 Web 服务方法将记录更新回 CRM 数据库。

_orgService.Update(retrievedAccount);

如果您在 CRM 中打开记录，您将看到这些值在那里更新。

步骤 4.8 − 最后，使用 Delete Web 服务方法删除记录。

_orgService.Delete(Account.EntityLogicalName, _accountId);

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

结论

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