练习 - 编写您的第一个插件

30 分钟

在本应用场景中，组织需要确保以一致的格式输入电话号码数据。为了实现这一目标，您将创建一个在创建/更新时运行的插件，该插件在将电话号码保存到 Dataverse 之前，会从电话号码中去除所有非数字字符。然后，您将创建另一个插件，该插件将在联系人检索/检索多个时运行，以重新格式化电话号码，使其包含括号和破折号（如果数据存在）。

练习 1：创建/更新插件

在本练习中，您将创建一个插件，该插件将在创建和更新时运行。本插件将从电话号码中去除所有非数字字符。

每个练习都包括应用场景和学习目标。应用场景描述了练习的目的，同时列出了目标并具有要点。

注意

如果您没有 Dynamics 365 SDK 工具，请参阅从 NuGet 下载工具进行下载。

任务 1：创建插件

启动 Visual Studio 2022。
选择文件 > 新建 > 项目。
选择类库 (.NET Framework)，然后选择下一步。
输入 D365PackageProject 作为项目名称，选择保存项目的位置，选择 .NET Framework 4.6.2 作为框架，然后选择创建。
右键单击项目，然后选择管理 NuGet 包。
选择浏览选项卡，搜索并选择 microsoft.crmsdk.coreassemblies，然后选择安装。
阅读许可条款，如果同意，请选择接受。
关闭 NuGet 包管理器。
右键单击 Class1.cs，然后单击删除。
右键单击项目，然后选择添加 > 类。
命名新类 PreOperationFormatPhoneCreateUpdate，然后选择添加。

将 using 语句添加到新类中，如下所示：

 using Microsoft.Xrm.Sdk;

 using System.Text.RegularExpressions;

将该类设为公共类，并实施 IPlugin 接口。
实施接口成员。

您的类现在应如下图所示。

任务 2：格式化电话号码

从服务提供商处获取执行上下文。用下面的代码片段替换 Execute 方法中的异常。

 IPluginExecutionContext context =
 (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

检查目标的输入参数。将以下代码片段添加到 Execute 方法中。

 if (!context.InputParameters.ContainsKey("Target"))

 throw new InvalidPluginExecutionException("No target found");

将以下代码片段添加到 Execute 方法中。该代码片段将从输入参数中获取目标实体，然后检查其属性是否包含 telephone1（联系人的商务电话、客户的电话）。
```
 var entity = context.InputParameters["Target"] as Entity;

 if (!entity.Attributes.Contains("telephone1"))

 return;
```
将以下代码片段添加到 Execute 函数中。本代码片段将删除用户提供的电话号码中的所有非数字字符。
```
 string phoneNumber = (string)entity["telephone1"];

 var formattedNumber = Regex.Replace(phoneNumber, @"[^\d]", "");
```
将 telephone1 设置为格式化的电话号码。将以下代码片段添加到 Execute 方法中。
```
 entity["telephone1"] = formattedNumber;
```
Execute 方法现在应该类似于下图。
右键单击该项目并选择属性。
选择签名选项卡，选中标记为为程序集签名 的框，然后选择新建密钥文件。
在密钥文件名字段中输入 contoso.snk，清除使用密码保护我的密钥文件复选框，然后选择确定。
关闭属性选项卡。
构建项目，并确保构建成功。

任务 3：注册插件和步骤

注意

如果您没有 Dynamics 365 SDK 工具，请参阅从 NuGet 下载工具进行下载。

启动 Plug-in Registration Tool 应用程序。
选择创建新连接。
选择 Office 365，选中显示高级复选框，提供您的凭据，然后选择登录。
选择注册，然后选择注册新程序集。
选择浏览。
转到您创建的类库的 Bin > Debug 文件夹，选择 D365PackageProject.dll，然后选择打开。
选择注册所选插件。
选择确定。
展开新注册的程序集。
右键单击插件，然后选择注册新步骤。
为消息选择创建，为主要实体选择联系人。
为执行的事件管道阶段选择 PreOperation，然后选择注册新步骤。
选择关闭。
右键单击插件，然后再次选择注册新步骤。
为消息选择更新，为主要实体选择联系人，然后选择属性查找。
清除全选复选框，选择商务电话复选框，然后选择确定。
为执行的事件管道阶段选择 PreOperation，然后选择注册新步骤。

任务 4：测试插件

转到您的 Maker Portal 并确保选择正确的环境。
选择应用并启动筹款活动应用程序。
选择仪表板并打开其中一个联系人。
选择 + 新建。
分别在名字、姓氏和商务电话中输入测试、联系人和 (123)-555-0100，然后选择保存。

应该保存记录，并且商务电话应该只显示数字值。
将商务电话更改为 001-123-555-0100 并等待几秒钟。

记录应该更新，并且商务电话应该只显示数字值。

练习 2：创建/检索多个插件

在本练习中，您将创建一个插件，该插件将在检索时和检索多个时运行。该插件将括号和破折号添加到电话号码。

每个练习都包括应用场景和学习目标。应用场景描述了练习的目的，同时列出了目标并具有要点。

任务 1：创建插件

启动 Visual Studio。
打开您在练习 1 中创建的项目。
右键单击该项目并选择添加 > 类。
在名称字段中，为该类别输入 PostOperationFormatPhoneOnRetrieveMultiple，然后选择添加。
将 using 语句添加到新类中，如下所示：
```
 using Microsoft.Xrm.Sdk;
```
将该类设为公共类，并实施 IPlugin 接口。
实施接口成员。您的类现在应如下图所示。

任务 2：为检索设置电话号码格式

从服务提供商处获取执行上下文。用下面的代码片段替换 Execute 方法中的异常。

 IPluginExecutionContext context =
 (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

检查消息名称是 Retrieve 还是 RetrieveMultiple。将以下代码片段添加到 Execute 方法中。

 if (context.MessageName.Equals("Retrieve"))	
 {

 }	
 else if(context.MessageName.Equals("RetrieveMultiple"))	
 {

 }

检查输出参数是否包含业务实体，以及它是否是一种实体。将以下代码片段粘贴到 if retrieve 条件中。

 if (!context.OutputParameters.Contains("BusinessEntity") && context.OutputParameters["BusinessEntity"] is Entity)
 throw new InvalidPluginExecutionException("No business entity found");

获取实体并检查它是否包含电话 1 字段。在 if retrieve 条件中添加以下代码片段。

 var entity = (Entity)context.OutputParameters["BusinessEntity"];

 if (!entity.Attributes.Contains("telephone1"))	
     return;

将以下代码片段添加到 if retrieve 条件中。该代码片段尝试将 telephone1 解析为 long，如果解析不成功，将返回。
```
 if (!long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))

 return;
```

通过添加括号和破折号来格式化电话号码。在 if retrieve 条件中添加以下代码片段。

 var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
 entity["telephone1"] = formattedNumber;

Execute 方法的检索部分现在应该类似于下图。

任务 3：格式化电话号码以使用 retrieve multiple

将以下代码片段添加到 retrieve multiple 条件内部。该代码片段将检查输出参数是否包含 BusinessEntityCollection，以及它是否属于 EntityCollection 类型。

 if(!context.OutputParameters.Contains("BusinessEntityCollection") && context.OutputParameters ["BusinessEntityCollection"] is EntityCollection)
     throw new InvalidPluginExecutionException("No business entity collection found");

从输出参数中获取实体集合。在 retrieve multiple 条件中添加以下代码片段。

 var entityCollection = (EntityCollection)context.OutputParameters["BusinessEntityCollection"];

循环访问实体集合中的每个实体。

 foreach (var entity in entityCollection.Entities)	
 {

 }

在 foreach 条件中添加以下代码片段。该片段将执行与 retrieve 条件相同的操作。

 if (entity.Attributes.Contains("telephone1") && entity["telephone1"] != null)
 {
    if (long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))
    {
        var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
        entity["telephone1"] = formattedNumber;
    }
 }

Execute 方法的 retrieve multiple 部分现在应该类似于下图。

重新构建项目，并确保构建成功。

任务 4：更新插件程序集和注册步骤

启动 Plug-in Registration Tool 并选择创建新连接。
选择 Office 365，选择显示高级，提供您的凭据，然后选择登录。
选择您在练习 1 中注册的程序集，然后选择更新。
选择浏览。
转到项目的 debug 文件夹，选择 D365PackageProject.dll，然后选择打开。
选择插件，然后选择更新所选插件。
选择确定。
右键单击新插件，然后选择注册新步骤。
为消息选择 Retrieve，为主要实体选择联系人，然后为执行的事件管道阶段选择 PostOperation。确保您为执行模式选择了同步，然后选择注册新步骤。
右键单击插件，然后再次选择注册新步骤。
为消息选择 RetrieveMultiple，为主要实体选择联系人，然后为执行的事件管道阶段选择 PostOperation。确保您为执行模式选择了同步，然后选择注册新步骤。