AVEVA PMLNet Guide
eryar@163.com
Abstract. AVEVA PMLNet allows you to instantitate and invoke methods on .NET objects from PML proxy objects. The PML proxy objects behave just like any other PML object. The paper gives a hello world example to demenstrate the PMLNet usage.
Key Words. AVEVA, PMLNet, PML, AVEVA .Net, C#, Managed C++
1. Introduction
AVEVA PMLNet允許在PML代理對(duì)象中實(shí)例化或調(diào)用.Net對(duì)象的方法。代理PML對(duì)象的定義通過(guò).NET類(lèi)運(yùn)行時(shí)創(chuàng)建出來(lái)，其與.Net類(lèi)有類(lèi)似的方法；代理PML類(lèi)方法的參數(shù)只能是指定的幾種，這幾種類(lèi)型的參數(shù)與.Net類(lèi)型對(duì)應(yīng)。代理PML對(duì)象的用法及功能表現(xiàn)與其他PML對(duì)象相同。
可被PML調(diào)用的組件（即動(dòng)態(tài)庫(kù)dll）通過(guò)命令I(lǐng)MPORT加載到AVEVA PDMS/Marine中來(lái)。組件可由任意.Net語(yǔ)言來(lái)定義，例如：Managed C++（托管C++）、C#或VB .NET等。PMLNet通過(guò)反射（reflection）來(lái)加載指定的組件。PMLNet引擎（Engine）只會(huì)加載包含有自定義屬性標(biāo)記PMLNetCallable的組件中的類(lèi)和方法。為了在.Net類(lèi)中定義代理PML類(lèi)必須滿(mǎn)足一定的條件（rules）。
綜上所述，在滿(mǎn)足PMLNet一定條件下創(chuàng)建的.Net組件中的類(lèi)是可以被PML使用的，即可以在PML代碼中調(diào)用.Net組件中的資源。通過(guò)這種方式，可以獲得以下幾點(diǎn)優(yōu)勢(shì)：
v 在簡(jiǎn)單易學(xué)的PML中使用.Net庫(kù)中的海量資源，如Excel的讀寫(xiě)庫(kù)等；
v 程序關(guān)鍵部分用.Net實(shí)現(xiàn)，代碼的保密性相對(duì)PML而言要好很多；
v 由于PMLNet引擎支持.Net的組件，即C++、VB.Net寫(xiě)的庫(kù)都可以被PML調(diào)用；
本文主要通過(guò)一個(gè)簡(jiǎn)單例子來(lái)說(shuō)明PML代理類(lèi)的定義方法，掌握后可以擴(kuò)展到在PML中使用托管C++，代碼保密性更好且速度更快。這樣就可以在PML中應(yīng)用更廣泛的資源，來(lái)提高程序的開(kāi)發(fā)效率。
由于本人水平所限，文中的錯(cuò)誤不妥之處在所難免，敬請(qǐng)不吝指教，將不勝感激。歡迎討論交流，共同進(jìn)步。
2.Design Details
下圖所示為如何在PDMS/Marine中使用PMLNet實(shí)現(xiàn)自定義。有一些.NET API可以用來(lái)訪(fǎng)問(wèn)當(dāng)前數(shù)據(jù)庫(kù)任務(wù)，顯示列表drawlist，幾何geometry和其他功能。用戶(hù)可以通過(guò)C#的API來(lái)訪(fǎng)問(wèn)PDMS/Marine，但是直接在C#中調(diào)用PML是不可能的（It is not possible to directly to call PML from C#）。然而AVEVA提供了一個(gè)事件機(jī)制來(lái)允許PML去訂閱（subscrible）C#發(fā)出的事件（events），如下圖虛線(xiàn)所示。
Figure 2.1 Using PMLNet
使用PMLNet有如下限制：
v 只有標(biāo)記了PMLNetCallable且滿(mǎn)足一定條件的.Net類(lèi)才能被PML調(diào)用；
v 模塊切換并不保留.NET對(duì)象，核心的C++或FORTRAN對(duì)象在模塊切換時(shí)也不會(huì)被保留；
v PML調(diào)用.NET方法時(shí)只能傳入指定類(lèi)型的變量，其他類(lèi)型不支持，如DIRECTION, ORIENTATION等；
v 在.NET中調(diào)用PML是不允許的，唯一的辦法就是通過(guò).NET的事件來(lái)調(diào)用PML；
v It is not possible to enter ‘partial’ namespaces as you might in C# and expect them to be concatenated；
并不是所有的PML對(duì)象都可以傳遞到所調(diào)用的.NET方法中去，只有下表的PML類(lèi)型的變量可以傳遞到調(diào)用.NET對(duì)象的方法中去：
Figure 2.2 Only PML variables types maybe passed to methods of .NET class
3.Using PMLNet
AVEVA提供了一個(gè)簡(jiǎn)單的PMLNet例子，程序名為PMLNetExample，將這個(gè)例子的代碼例出如下所示：
using System;
using System.Collections.Generic;
using System.Text;
using System.Windows.Forms;
using System.Collections;
using Aveva.PDMS.PMLNet;
namespace Aveva.Pdms.Examples
{
[PMLNetCallable()]
public class PMLNetExample
{
[PMLNetCallable()]
public event PMLNetDelegate.PMLNetEventHandler PMLNetExampleEvent;
[PMLNetCallable()]
public PMLNetExample()
{
}
[PMLNetCallable()]
public void Assign(PMLNetExample that)
{
//No state
}
[PMLNetCallable()]
public void RaiseExampleEvent()
{
ArrayList args = new ArrayList();
args.Add("ExampleEvent");
if (PMLNetExampleEvent != null)
PMLNetExampleEvent(args);
}
[PMLNetCallable()]
public void Method()
{
MessageBox.Show("Called Method");
}
}
}
如上述代碼所示，需要暴露給PML的方法或?qū)傩远家獦?biāo)記上PMLNetCallable。將上述代碼編譯后生成一個(gè)組件放到PDMS/Marine的安裝目錄下，就可以寫(xiě)一個(gè)PML小程序來(lái)測(cè)試效果了。
在CommandWindow中輸入如下圖所示的命令：
Figure 3.1 Using PML proxy object in PML
在PML中使用代理PML對(duì)象主要分為以下步驟：
v 使用IMPORT命令導(dǎo)入組件；
import 'PMLNetExample'
其中PMLNetExample是生成的dll組件名；
v 引入命名空間；
using namespace 'Aveva.Pdms.Examples'
命名空間的名稱(chēng)與C#中命名空間對(duì)應(yīng)；
v 實(shí)例化類(lèi)對(duì)象；
!a = object PMLNetExample()
實(shí)例化類(lèi)對(duì)象的方式與其他PML對(duì)象一樣。
v 調(diào)用對(duì)象方法；
!a.method()
調(diào)用對(duì)象的方法也和PML對(duì)象一樣，得到結(jié)果如下圖所示：
Figure 3.2 Test PML proxy object method
4.Rules for Calling .NET
想要在PML中調(diào)用.NET類(lèi)對(duì)象，就必須遵守一定的規(guī)則。這些規(guī)則如下：
v 可被PML調(diào)用的.NET組件必須由PMLNetCallable標(biāo)記且位于%PDMSEXE%目錄中；
v .NET組件中只有類(lèi)可以被PML使用，結(jié)構(gòu)體、接口及枚舉除外；
v .NET組件中需要被PML調(diào)用的類(lèi)必須由PMLNetCallable標(biāo)記；
v .NET組件中需要被PML調(diào)用的方法必須由PMLNetCallable標(biāo)記；
v .NET組件中需要被PML調(diào)用的方法的參數(shù)類(lèi)型必須為指定的幾種類(lèi)型；
Figure 4.1 Only PML variables types maybe passed to methods of .NET class
v .NET組件中需要被PML調(diào)用的類(lèi)和方法必須是公有的；
v .NET組件中需要被PML調(diào)用的方法不支持默認(rèn)參數(shù)的定義；
v .NET組件中需要被PML調(diào)用的類(lèi)和方法名稱(chēng)是區(qū)分大小寫(xiě)的；
v .NET組件中需要被PML調(diào)用的類(lèi)中必須要有Assign()方法；
v .NET組件中需要被PML調(diào)用的類(lèi)必須有一個(gè)由PMLNetCallable標(biāo)記的公有的默認(rèn)構(gòu)造函數(shù)；
如果沒(méi)有遵守上述條件之一，當(dāng)加載相應(yīng)的組件時(shí)就會(huì)報(bào)出錯(cuò)誤，錯(cuò)誤信息如下所示：
(46,87) PML: Object definition for XXX could not be found.
5.Conclusion
綜上所述，在PML中調(diào)用.NET組件中的類(lèi)還是很方便的，只要滿(mǎn)足PML代理類(lèi)定義的一些規(guī)則就可以了。
由于.NET組件中的類(lèi)是由.NET語(yǔ)言實(shí)現(xiàn)的，所以托管C++、C#及VB.NET編寫(xiě)的組件都可以包裝成代理PML類(lèi)，進(jìn)而被PML調(diào)用。這種方式就更加擴(kuò)大了PML可使用的資源，如C++的庫(kù)都可以在PML中使用，且代碼更保密，不易查看源碼。
在PML中調(diào)用.NET組件中類(lèi)是可行的，但直接在C#中調(diào)用PML卻是不可行的。AVEVA也提供了在C#中調(diào)用PML的方式：即通過(guò)事件訂閱，詳細(xì)請(qǐng)參考文檔。
6. References
1. AVEVA .NET Customisation User Guide
2. Example of PML Callable: PMLNetExample
3. AVEVA Software Customisation Guide
4. AVEVA Software Customisation Reference Manual
5. AVEVA Data Access Routines User Guide