U8API开发手册C#版.docx
《U8API开发手册C#版.docx》由会员分享，可在线阅读，更多相关《U8API开发手册C#版.docx（44页珍藏版）》请在冰豆网上搜索。
U8API开发手册C#版
U8API开发手册
作者：
商平锋
版权所有：
用友软件股份有限公司
1.简介
U8API是为U8客户化应用开发提供的一套标准化的U8ERP业务编程接口。
是U8UAP二次开发体系的重要组成部分。
它包括一整套涵盖U8ERP采购、销售、库存、制造（规划中）、财务（规划中）、基本档案（规划中）等业务模块的API接口资源。
U8API的推出为U8标准产品更好的适应用户的个性化需求，更好的实现客户化交付提供了有力支持。
U8API按照U8ERP业务产品模块进行分类，并以U8主要业务实体（单据、档案、凭证）作为操作对象，提供了常用的基本操作。
比如：
对于库存的收发单据，提供“新增”、“审核”、“弃审”、“删除”、“装载”、“修改”六个API接口。
目前，U8API提供了供应链采购、销售、库存三个产品的所有单据的增删改、审核/弃审等API接口，后续版本会逐步将制造、财务、基本档案等模块的API纳入进来。
U8API通过“U8API资源管理器”对U8范围内所有API进行集中统一分类管理，形成了一套完整的U8API资源库。
U8API的使用者可以使用“U8API资源管理器”浏览、查看API及其接口定义，并可辅助进行代码生成（目前支持C#和VB语言）；API的开发者可以通过此工具发布、注册API，所有业务API都必须在“U8API资源管理器”中进行注册。
U8API还提供了一套运行时调用框架——U8APIBroker。
它是所有U8API的调用代理，用户要使用某个API只需调用U8APIBroker即可，无需直接访问真正的API。
U8APIBroker作为一个服务代理中间件，起到了隔离API的提供者与使用者的作用，降低了耦合依赖关系。
U8API与U8EAI接口从功能上看比较相识，但它们的特性有差别。
U8API采用传统的编程模型，更靠近底层，业务逻辑粒度更细，而且还需要或依赖一些特定的上下文环境，比如：
login、事务等；而U8EAI接口则是完全松耦合的，采用XML和请求/响应的消息传递模式，且业务粒度比较粗放。
这些特性的差别决定了它们的应用领域不同，U8API更适合于U8内部的功能扩展和客户个性化开发，而U8EAI则适合外部系统与U8之间以业务数据交换为特征的应用集成开发。
2.API应用
.1.API总体应用过程
2.1.1API浏览查找
在“开始”->“程序”->“用友ERP-U8”->“UAP”目录下找到“U8API资源管理器”，单击，登录，进入“U8API资源管理器”。
在左侧“U8API”树形节点下，找到某某模块，如“库存管理”模块（可以看到下面列有很多个单据，如盘点单、采购入库单等），展开要操作的单据，分两个子节点：
“事件”和“服务接口”，在“服务接口”下可以看到该单据提供的API接口，如“添加新单据”、“审核单据”等。
双击这些节点出现该API的详细描述，如下图2.1所示。
在节点上右键单击弹出“上下文菜单”，在“代码示例”菜单项上弹出下一级子菜单，单击它们，如单击“C#代码示例”则可以看到调用该API的C#示例代码，如下图2.2所示。
直接拷贝这些代码，然后在集成开发环境（IDE）中编辑和编译
这些代码，即能实现调用U8标准API。
利用这些代码示例时，请按照其中每一步骤的提示说明正确操作，如添加必要的引用、按照自动生成的代码填入正确的参数等。
正确使用则可以调用成功，否则会返回详细的错误信息。
以下代码中均以C#为例，VB语言请具体查看对应的VB代码示例部分。
图2.1接口描述
图2.2代码示例
2.1.2API调用过程
Ø组件引用
针对两种语言，需要引用不同的组件。
（1）C#：
%U8SOFT%\Interop\Interop.U8Login.dll、
%U8SOFT%\Interop\Interop.MSXML2.dll、%U8SOFT%\UFMOM\U8APIFramework\UFIDA.U8.U8APIFramework.dll、%U8SOFT%\UFMOM\U8APIFramework\UFIDA.U8.MomServiceCommon.dll、%U8SOFT%\UFMOM\U8APIFramework\UFIDA.U8.U8MOMAPIFramework.dll
如下图2.3、2.4、2.5所示。
（2）VB：
%U8SOFT%\UFMOM\U8APIFramework\UFIDA.U8.U8APIFramework.tlb、%U8SOFT%\UFMOM\U8APIFramework\UFIDA.U8.MomServiceCommon.tlb、%U8SOFT%\UFMOM\U8APIFramework\UFIDA.U8.U8MOMAPIFramework.tlb、
添加MicrosoftXMLv3.0引用
如下图2.6、2.7所示。
其中，%U8SOFT%表示U8-872的安装目录。
图2.3添加对U8Login.dll引用
图2.4添加对Interop.MSXML2.dll引用
图2.5添加对U8API框架类库引用（.dll）
图2.6添加对U8API框架类库引用（.tlb）
图2.7添加MicrosoftXMLv3.0引用
ØAPI调用
添加必要的引用后，可以直接利用自动生成的代码示例（支持C#和VB两种语言），结合API接口详细描述，填入必要的参数值，就可以调用U8API。
总体上，对U8API的调用分成七个步骤：
1）构造u8login对象并登陆；
2）构造环境上下文对象，传入login，并按需设置其它上下文参数；
3）设置API地址标识（Url）参数；
4）构造APIBroker；
5）API参数赋值；
6）调用API；
7）获取返回结果。
详细的API调用过程请看下文“API内容”中各个模块中介绍的“开发步骤”。
下面重点介绍几个关键要点和步骤：
环境上下文、API地址、APIBroker、普通参数赋值、BO参数赋值。
✓环境上下文
环境上下文指在调用U8API时需要初始化的调用环境，包括Login、事务、特殊的业务参数等。
环境上下文被初始化后，相关的环境参数会被业务API使用。
U8EnvContextenvContext=newU8EnvContext（）;
●Login
需要将U8Login对象传递给环境上下文，U8Login对象必须已经登录过。
envContext.U8Login=u8Login;
●事务
如果需要由外部发起事务，则可以发起事务的ADOConnection对象传递给环境上下文：
ADODB.ConnectionClassconn=newConnectionClass（）;
envContext.BizDbConnection=conn;
同时需要设置一个外部事务标记：
envContext.IsIndependenceTransaction=true;
●特殊业务参数
特殊业务参数指调用某些API需要设置的特定上下文参数，比如：
销售的API必须要设置如VoucherType上下文参数，设置方法为：
envContext.SetApiContext（"VoucherType",23）;
✓API地址
API地址是指API在U8API系统中的唯一标识，也叫API的URI，调用API时，需要通过API地址构建一个代表此API的Broker对象：
U8ApiAddressmyApiAddress=newU8ApiAddress（"U8API/PurchaseOrder/VoucherSave"）;
✓APIBroker
APIBroker是所有U8API的调用代理接口。
使用U8所有API都必须通过APIBroker间接调用。
APIBroker作为一个服务代理中间件，起到了隔离API的提供者与使用者的作用，降低了耦合依赖关系。
创建APIBroker必须传入API地址和环境上下文：
U8ApiBrokerbroker=newU8ApiBroker（myApiAddress,envContext）;
✓普通参数赋值
API参数分两种类型：
BO参数和普通参数。
普通参数是指非单据表头表体类型的参数，包括基本类型参数（String、Integer等）、知名对象参数（Connection、DOMDocument等）。
普通参数的赋值采用如下方式：
broker.AssignNormalValue（"voucherState",2）;
✓BO参数赋值
BO参数即单据表头或表体类型的参数。
对BO参数，支持两种方式传入，一种传BO对象，另一种传DOM对象。
以下分别介绍：
●传BO对象
给BO表头参数或表体参数赋值，推荐使用BO对象（BussinessObject）。
例如：
BusinessObjectDomHead=broker.GetBoParam（"DomHead"）;
DomHead.RowCount=10;//设置行数，不设置也可
//给BO对象的字段赋值，值可以是真实类型，也可以是无类型字符串
//以下代码示例只设置第一行值。
各字段定义详见API服务接口定义
/******************************以下是必输字段****************************/
DomHead[0]["poid"]="";//主关键字段，int类型
DomHead[0]["dpodate"]="";//日期，DateTime类型
DomHead[0]["cpoid"]="";//订单编号，string类型
……
/*****************************以下是非必输字段****************************/
DomHead[0]["ipresent"]="";//现存量，string类型
DomHead[0]["cmaketime"]="";//制单时间，DateTime类型
DomHead[0]["cmodifytime"]="";//修改时间，DateTime类型
……
在此种情况下U8API框架会对BO对象各字段进行参数校验。
对字段进行赋值时，值可以是真实类型，也可以是无类型字符串。
●传DOM对象
给BO表头参数或表体参数赋值，也支持直接传入DOM对象（DOMDocument）。
例如：
MSXML2.DOMDocumentClassdomHead=newMSXML2.DOMDocumentClass（）;
domHead.load（"domHead.xml"）;
broker.AssignNormalValue（"domHead",domHead）;
但是，在此种情况下U8API框架不会对DOM对象进行参数验证。
请在使用该方法之前，确保DOM对象的正确性。
2.1.3API典型应用场景
Ø执行单一操作
单一操作指一项任务只需要一个API完成，比如：
单据新增、审核/弃审、删除等单一操作。
这是API调用最常见的场景，只需按照API的接口规范构造参数直接调用即可。
Ø执行复合操作
复合操作，即一项任务由多个API的协作来完成。
比如，自定义的单据维护界面的主要逻辑，一般由以下四个步骤构成：
8）加载单据；
9）在编辑界面上显示；
10）用户修改单据字段；
11）提交保存。
以上步骤需要进行两次API调用：
1）加载单据时候调用“加载API”，以获取单据BO对象（或原始DOM对象）并在界面上展现；
2）用户在修改单据时其实就是在修改BO对象，用户保存单据时调用“保存API”，此时要将此BO对象传给“保存API”（而不用构造新的BO对象）。
代码示例：
首先，登陆；
//构造u8login对象并登陆
U8Login.clsLoginu8Login=newU8Login.clsLogin（）;
StringsSubId="AS";
StringsAccID="（default）@001";
StringsYear="2008";
StringsUserID="demo";
StringsPassword="";
StringsDate="2008-09-30";
StringsServer="localhost";
StringsSerial="";
if（!
u8Login.Login（refsSubId,refsAccID,refsYear,refsUserID,refsPassword,refsDate,refsServer,refsSerial））
{
Console.WriteLine（"登陆失败，原因：
"+u8Login.ShareString）;
Marshal.FinalReleaseComObject（u8Login）;
return;
}
然后，通过LOAD接口获取BO对象；
//构造环境上下文对象，传入login，并按需设置其它上下文参数
U8EnvContextenvContext=newU8EnvContext（）;
envContext.U8Login=u8Login;
//设置上下文参数
……
//设置API地址标识（Url）
U8ApiAddressmyApiAddress=newU8ApiAddress（“装载单据的地址标识”）;
//构造APIBroker
U8ApiBrokerbroker=newU8ApiBroker（myApiAddress,envContext）;
//API参数赋值
broker.AssignNormalValue（"参数名","参数值"）;
……
//调用LOAD接口API
if（!
broker.Invoke（））
{
//错误处理
ExceptionapiEx=broker.GetException（）;
if（apiEx!
=null）
{
if（apiExisMomSysException）
{
MomSysExceptionsysEx=apiExasMomSysException;
Console.WriteLine（"系统异常：
"+sysEx.Message）;
//todo:
异常处理
}
elseif（apiExisMomBizException）
{
MomBizExceptionbizEx=apiExasMomBizException;
Console.WriteLine（"API异常：
"+bizEx.Message）;
//todo:
异常处理
}
}
//结束本次调用，释放API资源
broker.Release（）;
return;
}
//获取表头或表体的BO对象，如果要取原始的XMLDOM对象结果，请使用GetResult（参数名）
BusinessObjectDomRet=broker.GetBoParam（"表头或表体参数名"）;
接着，BO对象经用户修改重新赋值,并传递给UPDATE接口提交保存；
//修改获取的BO对象，对需要更改的字段重新赋值
DomRet[0]["字段名"]=新的字段值;
……
//重新构造“新增或修改”API的地址标识
myApiAddress=newU8ApiAddress（"新增或修改”API的地址标识"）;
//重新构造APIBroker
broker=newU8ApiBroker（myApiAddress,envContext）;
//表头或表体参数赋值
broker.SetBoParam（"表头或表体参数名",DomRet）;
//API参数赋值
broker.AssignNormalValue（"参数名","参数值"）;
……
//调用UPDATE接口API
if（!
broker.Invoke（））
{
……
}
最后，获取返回结果。
//获取普通返回值
System.Stringresult=broker.GetReturnValue（）asSystem.String;
//获取out/inout参数值
……
//结束本次调用，释放API资源
broker.Release（）;
.2.API内容
.2.1采购管理
Ø功能介绍
为了支持U8二次开发对业务单据的开发，本功能提供了实现采购业务单据各种操作功能的编程接口。
使用采购管理的API开发接口，可以对库存管理中的采购到货单、采购普通发票、采购专用发票、采购订单、请购单、采购运费发票等单据进行审核、弃审、获取（或装载）、新增、修改、删除。
Ø使用环境
必须安装.NETFrameWork2.0；
必须安装U8-872版本的采购管理产品；
必须安装API适配器组件PUAPIConcrete.dll
Ø接口说明
采购管理二次开发接口说明：
⏹审核单据-ConfirmPO方法
参数：
domHead——单据表头，DOM对象，必输
API上下文：
VoucherType——单据类型，具体类型参看API上下文描述
bPositive——红蓝标识：
True,蓝字；False,红字
sBillType——为空串
sBusType——业务类型：
普通采购,直运采购,受托代销
⏹弃审单据-CancelconfirmPO方法
参数：
domHead——单据表头，DOM对象，必输
API上下文：
VoucherType——单据类型，具体类型参看API上下文描述
bPositive——红蓝标识：
True,蓝字；False,红字
sBillType——为空串
sBusType——业务类型：
普通采购,直运采购,受托代销
⏹装载单据-Load方法
参数：
DomHead——表头DOM对象
domBody——表体DOM对象
strWhere——过滤条件串
varVoucherID——单据主表ID
strLocateWhere——定位条件串
API上下文：
VoucherType——单据类型，具体类型参看API上下文描述
bPositive——红蓝标识：
True,蓝字；False,红字
sBillType——为空串
sBusType——业务类型：
普通采购,直运采购,受托代销
⏹删除单据-Delete方法
参数：
DomHead——表头DOM对象
domBody——表体DOM对象
CurDom——返回DOM格式错误信息
API上下文：
VoucherType——单据类型，具体类型参看API上下文描述
bPositive——红蓝标识：
True,蓝字；False,红字
sBillType——为空串
sBusType——业务类型：
普通采购,直运采购,受托代销
⏹新增或修改新单据-VoucherSave方法
参数：
DomHead——单据表头，DOM对象，必输
domBody——单据表体，DOM对象，必输
VoucherState——保存状态，必输。
2增加；1修改；0非编辑
curID——返回单据头ID
CurDom——返回DOM格式错误信息
UserMode——使用模式，0：
CS；1:
BS
API上下文：
VoucherType——单据类型，具体类型参看API上下文描述
bPositive——红蓝标识：
True,蓝字；False,红字
sBillType——为空串
sBusType——业务类型：
普通采购,直运采购,受托代销
Ø开发步骤
实现采购单据某一功能，主要有以下七个步骤：
1．构造u8login对象并登陆
声明和创建u8login类对象前应该先引用U8API类库中的Interop.U8Login.dll，代码示例如下：
U8Login.clsLoginu8Login=newU8Login.clsLogin（）;//声明u8login对象
StringsSubId="AS";//登陆
StringsAccID="（default）@001";
StringsYear="2008";
StringsUserID="demo";
StringsPassword="";
StringsDate="2008-09-30";
StringsServer="localhost";
StringsSerial="";
if（!
u8Login.Login（refsSubId,refsAccID,refsYear,refsUserID,refsPassword,refsDate,refsServer,refsSerial））
{
Console.WriteLine（"登陆失败，原因：
"+u8Login.ShareString）;
Marshal.FinalReleaseComObject（u8Login）;
return;
}
如果当前环境中有login对象则可以省去第一步。
2．构造环境上下文对象，传入login，并按需设置其它上下文参数
U8EnvContextenvContext=newU8EnvContext（）;//构造环境上下文对象
envContext.U8Login=u8Login;//传入login
//设置上下文参数
envContext.SetApiContext（"VoucherType",newint（））;//上下文数据类型：
int，含义：
单据类型
envContext.SetApiContext（"bPositive",newbool（））;//上下文数据类型：
bool，含义：
红蓝标识：
True,蓝字
envContext.SetApiContext（"sBillType",newstring（））;//上下文数据类型：
string，含义：
为空串
envContext.SetApiContext（"sBusType",newstring（））;//上下文数据类型：
string，含义：
业务类型：
普通采购,直运采购,受托代销
如果是外部事务，则需要传递ADO.Connection对象，并将IsIndependenceTransaction设置为true：
envContext.BizDbConnection=newADO.Connection（）;
envContext.IsIndependenceTransaction=true;
3．设置API地址标识（Url）参数
//如当前API“新增或修改”的地址标识为：
U8API/PurchaseOrder/VoucherSave
U8ApiAddressmyApiAddress=newU8ApiAddress（"U8API
升级会员 