插件实战开发-新手入门教程-服务插件
https://wenku.my7c.com/link/s/lHP9c
说明：本文前提是开发机已经安装好金蝶云星空系统和金蝶BOS IDE。
本教程是“服务插件”（APP插件）的入门教程，与前一篇教程“单据插件”和“列表插件”有很多重复之处，但作为入门教程，我们还是将重复的部分保留在本文里，以便大家都能顺利完成这第一步。
服务插件运行时机
我们新手看不懂？看不懂没关系，有个印象就行，当我们有了一定的开发经验以后，就可以看懂。
金蝶云的真正价值是一个配置型的开发平台。我们平时99%都是在做服务插件的开发，1%是在做客户端插件。
那么服务插件到底能做什么呢？
服务插件可以对当前操作实现自定义的干预。又看不懂？我们举例子说明，例如：当用户在星空系统里，对某个单据进行“审核”（其他操作也行）操作时，调用第三方系统接口，将单据数据推送到第三方系统，并对第三方接口返回结果就行处理。这种场景非常常见，这种场景需求可以使用服务插件来完成。
再举个例子，当用户在星空系统里，对“采购订单”操作保存，但采购数量大于100时可以保存，金额大于10000时禁止保存。
还有很多场景可以使用服务插件来完成。当前我们在这里就不做展开，有个印象就可以了，我们现在最重要的是迈出第一步。
步骤：
1. 创建Visual C#类库
2. 添加星空系统类库的引用
3. 编写服务插件
4. 编译代码生成dll文件
5. 使用BOS注册插件
6. 重启IIS服务器
1.创建Visual C#类库
打开Visual Studio IDE，在启动窗口中选择“创建新项目”选项。如下图所示：
在Visual Studio IDE的项目类型列表中找到“类库(.NET Framework)”选项。如下图所示：
点击“下一步”按钮，配置项目信息。
【重要】项目名称是一个比较重要的配置项，金蝶官方在《二次开发规范》中有说明。
按照规范我们暂时将项目命名定为：
Test.K3Cloud.SCM.MyAppPlugin
【重要】框架选择 .NET Framework 4
具体配置如下图所示：
3.添加星空系统类库的引用
在Visual Studio IDE的解决方案资源管理器窗口中，选择“引用”，点击右键，呼出右键菜单，选择“添加引用”选项。打开“应用管理器”窗口，选择“Kingdee.BOS.dll和Kingdee.BOS.Core.dll”。
如果窗口列表中没有此类库，可以点击窗口下方的“浏览”按钮，在星空系统的安装目录中找到此类库文件。默认目录为：C:\Program Files (x86)\Kingdee\K3Cloud\WebSite\Bin
3.编写服务插件
服务插件支持的事件和调用顺序
| 事件 | 说明 |
|---|---|
| OnPrepareOperationServiceOption | 选项设置 |
| OnPreparePropertys | 加载指定字段到实体数据包里 |
| OnAddValidators | 添加自定义数据校验器 |
| BeforeDoSaveExecute | 在执行保存操作前触发 |
| BeforeExecuteOperationTransaction | 执行操作事务前事件，通知插件对要处理的数据进行排序等预处理（事务外触发） |
| BeginOperationTransaction | 操作事物前事件（事务内触发） |
| EndOperationTransaction | 操作事物后事件（事务内触发） |
| RollbackData | 内部事务执行失败后，调用回滚数据事件（事务外触发） |
| AfterExecuteOperationTransaction | 执行操作事务后事件，通知插件对象执行其它事务无关的业务逻辑（事务外触发） |
服务插件继承于 AbstractOperationServicePlugIn ，本教程中我们在EndOperationTransaction 事件中做实验。为了让大家的思路不中断，接下来的内容中，每次会给出全部的代码。基础代码如下：
using System;using System.Collections.Generic;using System.Linq;using System.Text;using Kingdee.BOS.Core.DynamicForm.PlugIn;using Kingdee.BOS.Core.DynamicForm.PlugIn.Args;namespace Test.K3Cloud.SCM.MyAppPlugin{
public class Class1: AbstractOperationServicePlugIn
{
public override void EndOperationTransaction(EndOperationTransactionArgs e)
{
base.EndOperationTransaction(e);
}
}}接下来，我们完成信息提示窗口方法。信息提示窗口，需要使用到金蝶其他类库文件。添加引用文件的方法，上面有讲。类库文件如下：
1.Kingdee.BOS.DataEntity.dll
2.Newtonsoft.Json.dll
Newtonsoft.Json.dll文件默认位于C:\Program Files (x86)\Kingdee\K3Cloud\WebSite\Bin\Newtonsoft.Json.dll
信息弹窗方法代码如下：
using System;using System.Collections.Generic;using System.Linq;using System.Text;using Kingdee.BOS;using Kingdee.BOS.Core.DynamicForm;using Kingdee.BOS.Core.DynamicForm.PlugIn;using Kingdee.BOS.Core.DynamicForm.PlugIn.Args;using Kingdee.BOS.Core.Interaction;using Newtonsoft.Json.Linq;namespace Test.K3Cloud.SCM.MyAppPlugin{
public class Class1: AbstractOperationServicePlugIn
{
public override void EndOperationTransaction(EndOperationTransactionArgs e)
{
base.EndOperationTransaction(e);
}
/// <summary> /// 信息提示窗口 /// </summary> /// <param name="context">上下文对象</param> /// <param name="spensorKey">窗口标识</param> /// <param name="ignore">状态</param> /// <param name="errorMsg">错误信息</param> /// <returns></returns> public static KDInteractionException ShowErrorMsg(Context context, string spensorKey, bool ignore, JArray errorMsg)
{
if (errorMsg.Count() != 2)
{
return null;
}
string titleMsg = "错误代码~|~错误信息";
string errMsg = "{0}~|~{1}";
K3DisplayerModel model = K3DisplayerModel.Create(context, titleMsg);
model.AddMessage(string.Format(errMsg, errorMsg[0].ToString(), errorMsg[1].ToString()));
model.Option.SetVariableValue(K3DisplayerModel.CST_FormTitle, "单据操作有以下错误，需要继续吗？");
model.OKButton.Caption = new LocaleValue("是");
model.CancelButton.Visible = model.OKButton.Visible = true;
model.CancelButton.Caption = new LocaleValue("否");
KDInteractionException ie = new KDInteractionException(spensorKey);
ie.InteractionContext.InteractionFormId = "BOS_K3Displayer";
ie.InteractionContext.K3DisplayerModel = model;
ie.InteractionContext.IsInteractive = true;
return ie;
}
}}接下来，我们在单据事件中调用信息弹窗的方法，以便我们可以在客户端界面上可以感知到服务插件的执行。
using System;using System.Collections.Generic;using System.Linq;using System.Text;using Kingdee.BOS;using Kingdee.BOS.Core.DynamicForm;using Kingdee.BOS.Core.DynamicForm.PlugIn;using Kingdee.BOS.Core.DynamicForm.PlugIn.Args;using Kingdee.BOS.Core.Interaction;using Newtonsoft.Json.Linq;namespace Test.K3Cloud.SCM.MyAppPlugin{
public class Class1: AbstractOperationServicePlugIn
{
// SpensorKey private const string SpensorKey = "DefaultSpensorKey";
public override void EndOperationTransaction(EndOperationTransactionArgs e)
{
base.EndOperationTransaction(e);
// 判断当用户操作“保存”动作时起效 if (FormOperation.OperationName == "保存")
{
/// 构造错误信息 JArray errMsg = new JArray {
new JValue("01"),
new JValue("这是一条提示信息")
};
bool ignore = false; // 窗口显示状态，默认不显示 Option.TryGetVariableValue(SpensorKey, out ignore);
if (!ignore && !Option.HasInteractionFlag(SpensorKey))
{
KDInteractionException ie = ShowErrorMsg(Context, SpensorKey, ignore, errMsg);
throw ie;
}
}
}
/// <summary> /// 信息提示窗口 /// </summary> /// <param name="context">上下文对象</param> /// <param name="spensorKey">窗口标识</param> /// <param name="ignore">状态</param> /// <param name="errorMsg">错误信息</param> /// <returns></returns> public static KDInteractionException ShowErrorMsg(Context context, string spensorKey, bool ignore, JArray errorMsg)
{
if (errorMsg.Count() != 2)
{
return null;
}
string titleMsg = "代码~|~信息";
string errMsg = "{0}~|~{1}";
K3DisplayerModel model = K3DisplayerModel.Create(context, titleMsg);
model.AddMessage(string.Format(errMsg, errorMsg[0].ToString(), errorMsg[1].ToString()));
model.Option.SetVariableValue(K3DisplayerModel.CST_FormTitle, "单据操作有以下信息出错，需要继续吗？");
model.OKButton.Caption = new LocaleValue("是");
model.CancelButton.Visible = model.OKButton.Visible = true;
model.CancelButton.Caption = new LocaleValue("否");
KDInteractionException ie = new KDInteractionException(spensorKey);
ie.InteractionContext.InteractionFormId = "BOS_K3Displayer";
ie.InteractionContext.K3DisplayerModel = model;
ie.InteractionContext.IsInteractive = true;
return ie;
}
}}4.编译代码生成dll文件
在Visual Studio IDE菜单栏中选择“项目”选项，选择 “Test.K3Cloud.SCM.MyAppPlugin属性”选项，打开“属性配置”窗口。选择窗口右侧的“生成”菜单选项，将输出路径设置为金蝶的安装目录的Website\bin目录。默认路径为：C:\Program Files (x86)\Kingdee\K3Cloud\WebSite\Bin配置完成之后，点击“保存”。如下图所示：
点击菜单中的“生成”选项，在下拉菜单中选择“生成Test.K3Cloud.SCM.MyAppPlugin”选项。
生成“Test.K3Cloud.SCM.MyAppPlugin”动态链接库文件。在Visual Studio IDE下方的输出窗口中显示生成成功，则说明Test.K3Cloud.SCM.MyAppPlugin.dll文件生成成功。如下图所示：
Test.K3Cloud.SCM.MyListPlugin.dll文件位于C:\Program Files (x86)\Kingdee\K3Cloud\WebSite\Bin目录。可以在此目录中找到。如下图所示：
5.使用BOS注册插件
打开【金蝶云星空集成开发平台】，在业务视图窗口，选择“供应链”选项，并在右侧的子系统中选择“采购管理”，选择完毕之后，点击“确定”按钮。如下图所示：
BOS的右侧“项目”视图窗口会加载出采购管理的基础资料和单据等对象。如下图所示：
在上面截图中“项目”视图的单据列表中，选择“采购订单”，点击右键，呼出右键菜单，选择“扩展”选项。根据星空系统的机制，系统默认的单据对象是只读状态，不允许修改和调整，只有扩展之后，才可以对单据继续修改调整。
在BOS的项目窗口中打开“采购订单”表单对象，在右下方的“属性”窗口中找到“操作列表”属性。打开“操作列表”窗口。如下图所示：
在“操作列表”窗口找到并选择“保存”动作。选中之后，点击窗口右侧的“编辑”按钮，打开“操作编辑”窗口。选择“操作编辑”窗口，下方的“其他控制”页签，找到“服务插件”表单控件。
点击“服务插件”打开“插件配置信息”窗口，在插件配置信息窗口，点击右侧的“注册”按钮，打开插件选择窗口。如下图所示：
点击“选择程序集”控件，在下拉菜单中选择“浏览”，在C:\Program Files (x86)\Kingdee\K3Cloud\WebSite\Bin目录找到Test.K3Cloud.SCM.MyAppPlugin.dll文件并选择。如下图所示：
上面是一套组合动作，大家应该能看得懂。
点击“插件配置信息”窗口的“确定”按钮。回到BOS主窗口，点击“保存”。等系统保存成功之后重启IIS服务。
6.重启IIS
打开IIS管理器。选择站点，然后点击右侧窗口中的“重新启动”按钮。重启IIS服务。每次代码更新，编译之后，都需要重启IIS服务。如下图所示：
重启完成之后，打开星空系统客户端的“采购订单”列表窗口。选择一个可以编辑保存的采购订单，进入修改页面。点击“保存”按钮，如果没有出错则弹出信息提示窗口。如下图所示：
此信息提示框的调用是在单据保存动作中调用的，受到事务保护。所以当用户点击“是”时，保存动作继续执行，当点击“否”时，信息提示函数返回一个异常，保存动作中断并且触发事务回滚。
以上为云星空系统服务插件开发的一个最简单示例。除自定义插件外，其他插件的开发都是遵循以上流程。
发星空系统插件和调试的过程中，每次更新都需要重启IIS服务，当然星空系统是支持“热更新”和“代码调试分析”的，本教程为了聚焦插件本身的开发流程，就没有将热更新和代码调试放到教程中。如果可能，后面会出教程来专门讲述这两个部分。
如果一次没有成功，没关系，万事开头难，大家跟着做多做几次，希望本教程能为帮助到大家！加油！！
作业：按照教程完成服务插件开发。
作者说明很详细！
插件实战开发-新手入门教程-服务插件
本文2024-09-16 18:20:19发表“云星空知识”栏目。
本文链接：https://wenku.my7c.com/article/kingdee-k3cloud-21498.html
