Dynamics 365中开发和注册插件介绍

我是微软Dynamics 365 & Power Platform方面的工程师罗勇，也是2015年7月到2018年6月连续三年Dynamics CRM/Business Solutions方面的微软最有价值专家(Microsoft MVP)，欢迎关注我的微信公众号 MSFTDynamics365erLuoYong ，回复380或者20191124可方便获取本文，同时可以在第一间得到我发布的最新博文信息，follow me!

前面的博文讲了些客户端编程，但是对于重要的数据，一般需要服务器端再做一次校验，常用的手段就是插件和实时工作流，今天我讲一下插件，官方文档请参考 Write a plug-in 和 Register a plug-in 等。

首先需要创建一个 .NET Framework 的 Class Library项目，记得 Framework选择 .NET Framework 4.6.2 。当然，为不同版本的Dynamics 365 Customer Engagement选择的Framework不尽相同，请根据官方文档说明，我这个示例是为 V9.X 版本做的示例。

首先通过NuGet添加对Microsoft.CrmSdk.CoreAssemblies的引用，如下图，当然也要选择合适的版本。如果不能上网的话，就需要添加对 Microsoft.Xrm.Sdk.dll 和 Microsoft.Crm.Sdk.Proxy.dll 的引用。

一般我会删除生成的Class1.cs文件，而是使用固定的命名方式来命名。比如我这个插件步骤将会注册在ly_WorkOrder实体的Create消息的Pre阶段，我就会新建一个 PreWorkOrderCreate.cs 的文件来撰写业务逻辑，当然这个类必须继承 Microsoft.Xrm.Sdk.IPlugin 接口，我使用的代码如下：常见的是获取组织服务和跟踪服务，其中插件日志的使用请参考我的博文：Dynamics CRM 2015/2016新特性之三十四：有了插件日志，调试插件so easy! ，若要使用映像(Image)，请参考我的博文：Dynamics 365 CE Update消息PostOperation阶段Image的尝试  和  Dynamics 365 CE在Pre Delete插件中应用Image 。记得若要抛出用户可见可理解的异常文本，请使用throw new InvalidPluginExecutionException。

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Query;
using System;
using System.ServiceModel;
using System.Text;

namespace PluginDemo
{
    public class PreWorkOrderCreate : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
            //获取日志服务
            ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
            //写一些日志，方便跟踪
            tracingService.Trace($"Enter PreWorkOrderCreate on {DateTime.UtcNow.ToString()}");
            IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
            if (context.InputParameters.Contains("Target") && context.InputParameters["Target"] is Entity)
            {
                //插件针对的当前实体记录，对于Pre Create来讲，该对象包括了所有设置的字段值，若字段没有设置值，在该对象中会不存在
                Entity currentEntity = (Entity)context.InputParameters["Target"];
                //获取组织服务
                IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
                IOrganizationService orgSvc = serviceFactory.CreateOrganizationService(context.UserId);
                int provinceValue = Int32.MaxValue;
                int cityValue = Int32.MaxValue;
                string buName = string.Empty;
                //首先获取要做校验的值
                //记得先确认该属性存在值再获取其值，否则容易引发异常
                if (currentEntity.Contains("ly_province"))
                {
                    provinceValue = currentEntity.GetAttributeValue<OptionSetValue>("ly_province").Value;
                }
                if (currentEntity.Contains("ly_city"))
                {
                    cityValue = currentEntity.GetAttributeValue<OptionSetValue>("ly_city").Value;
                }
                var userEntity = orgSvc.Retrieve("systemuser", context.UserId, new ColumnSet("businessunitid"));
                //每个系统用户肯定都设置了业务部门，我这里只是例行检查这个字段存在值
                if (userEntity.Contains("businessunitid"))
                {
                    buName = userEntity.GetAttributeValue<EntityReference>("businessunitid").Name;
                    if(buName == "Demo")
                    {
                        //省份字段用户选择了值才校验
                        if(provinceValue != Int32.MaxValue)
                        {
                            if(provinceValue != 430000)
                            {
                                throw new InvalidPluginExecutionException($"省份字段值选择有误!");
                            }
                            else
                            {
                                //城市字段用户选择了值才做校验
                                if(cityValue != Int32.MaxValue)
                                {
                                    if (cityValue >= provinceValue && cityValue < provinceValue + 10000)
                                    {
                                        tracingService.Trace($"城市字段选择了值，且属于正确的省份!");
                                    }
                                    else
                                    {
                                        throw new InvalidPluginExecutionException($"城市字段值选择有误!");
                                    }
                                }
                            }
                        }
                    }
                    else if(buName == "Sub Unit")
                    {
                        //省份字段用户选择了值才校验
                        if (provinceValue != Int32.MaxValue)
                        {
                            if (provinceValue != 440000)
                            {
                                throw new InvalidPluginExecutionException($"省份字段值选择有误!");
                            }
                            else
                            {
                                //城市字段用户选择了值才做校验
                                if (cityValue != Int32.MaxValue)
                                {
                                    if (cityValue >= provinceValue && cityValue < provinceValue + 10000)
                                    {
                                        tracingService.Trace($"城市字段选择了值，且属于正确的省份!");
                                    }
                                    else
                                    {
                                        throw new InvalidPluginExecutionException($"城市字段值选择有误!");
                                    }
                                }
                            }
                        }
                    }
                }
                else
                {
                    throw new InvalidPluginExecutionException($"系统异常，当前用户(userid={context.UserId})的业务部门没有设置!");
                }
            }
            tracingService.Trace($"Leave PreWorkOrderCreate on {DateTime.UtcNow.ToString()}");
        }
    }
}

记得一定要给该插件/自定义工作流活动程序集签名，在Visual Studio中右击该项目，选择属性(Properties) >  签名(Signing)，选中 Sign the assembly，我这里新建一个Key file。

Key file我的设置如下，为了简便，我就不设置密码保护了，保存后编译插件项目，确定没有编译错误。

然后需要使用插件注册工具将其注册到Dynamics 365中，工具的下载请参考我的博文 下载Dynamics 365 Customer Engagement 工具 。双击其中的 PluginRegistrationPluginRegistration.exe 文件。点击【CREATE NEW CONNECTION】，以便连接到Dynamics 365，下面这个截图是连接到我自己的做了面向互联网部署(IFD)的环境示例。

如果是连接到Dynamics 365 Customer Engagement Online,请参考下图：

点击【Register】 > 【Register New Assembly】。

选择前面步骤编译生成的插件程序集，Isolation Mode一般建议选择Sandbox，而且Dynamics Customer Engagement Onine也只能选择Sandbox，强烈建议选择存储到Database，点击【Register Selected Plugins】按钮，如果看不到该按钮，是你的电脑分辨率太低所致，就用Tab键盘来辅助操作吧。

如果没有错误的话会弹出类似如下对话框：

还需要右击创建的Plugin，选择【Register New Step】按钮。

我这里设置如下，是注册在lw_workorder的Create消息的PreOperation阶段，其余的就不一一解释了，请参考官方文档，点击【Register New Step】按钮。

注册成功后可以看到最终的结果类似如下：

剩下的工作就是测试了，使用InvalidPluginExecutionException抛出的异常信息在界面显示效果如下：