https://vip.kingdee.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服务,当然星空系统是支持“热更新”和“代码调试分析”的,本教程为了聚焦插件本身的开发流程,就没有将热更新和代码调试放到教程中。如果可能,后面会出教程来专门讲述这两个部分。
如果一次没有成功,没关系,万事开头难,大家跟着做多做几次,希望本教程能为帮助到大家!加油!!
作业:按照教程完成服务插件开发。
推荐阅读