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代理對象中實例化或調用.Net對象的方法。代理PML對象的定義通過.NET類運行時創建出來，其與.Net類有類似的方法；代理PML類方法的參數只能是指定的幾種，這幾種類型的參數與.Net類型對應。代理PML對象的用法及功能表現與其他PML對象相同。
可被PML調用的組件（即動態庫dll）通過命令IMPORT加載到AVEVA PDMS/Marine中來。組件可由任意.Net語言來定義，例如：Managed C++（托管C++）、C#或VB .NET等。PMLNet通過反射（reflection）來加載指定的組件。PMLNet引擎（Engine）只會加載包含有自定義屬性標記PMLNetCallable的組件中的類和方法。為了在.Net類中定義代理PML類必須滿足一定的條件（rules）。
綜上所述，在滿足PMLNet一定條件下創建的.Net組件中的類是可以被PML使用的，即可以在PML代碼中調用.Net組件中的資源。通過這種方式，可以獲得以下幾點優勢：
v 在簡單易學的PML中使用.Net庫中的海量資源，如Excel的讀寫庫等；
v 程序關鍵部分用.Net實現，代碼的保密性相對PML而言要好很多；
v 由于PMLNet引擎支持.Net的組件，即C++、VB.Net寫的庫都可以被PML調用；
本文主要通過一個簡單例子來說明PML代理類的定義方法，掌握后可以擴展到在PML中使用托管C++，代碼保密性更好且速度更快。這樣就可以在PML中應用更廣泛的資源，來提高程序的開發效率。
由于本人水平所限，文中的錯誤不妥之處在所難免，敬請不吝指教，將不勝感激。歡迎討論交流，共同進步。
2.Design Details
下圖所示為如何在PDMS/Marine中使用PMLNet實現自定義。有一些.NET API可以用來訪問當前數據庫任務，顯示列表drawlist，幾何geometry和其他功能。用戶可以通過C#的API來訪問PDMS/Marine，但是直接在C#中調用PML是不可能的（It is not possible to directly to call PML from C#）。然而AVEVA提供了一個事件機制來允許PML去訂閱（subscrible）C#發出的事件（events），如下圖虛線所示。
Figure 2.1 Using PMLNet
使用PMLNet有如下限制：
v 只有標記了PMLNetCallable且滿足一定條件的.Net類才能被PML調用；
v 模塊切換并不保留.NET對象，核心的C++或FORTRAN對象在模塊切換時也不會被保留；
v PML調用.NET方法時只能傳入指定類型的變量，其他類型不支持，如DIRECTION, ORIENTATION等；
v 在.NET中調用PML是不允許的，唯一的辦法就是通過.NET的事件來調用PML；
v It is not possible to enter ‘partial’ namespaces as you might in C# and expect them to be concatenated；
并不是所有的PML對象都可以傳遞到所調用的.NET方法中去，只有下表的PML類型的變量可以傳遞到調用.NET對象的方法中去：
Figure 2.2 Only PML variables types maybe passed to methods of .NET class
3.Using PMLNet
AVEVA提供了一個簡單的PMLNet例子，程序名為PMLNetExample，將這個例子的代碼例出如下所示：
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的方法或屬性都要標記上PMLNetCallable。將上述代碼編譯后生成一個組件放到PDMS/Marine的安裝目錄下，就可以寫一個PML小程序來測試效果了。
在CommandWindow中輸入如下圖所示的命令：
Figure 3.1 Using PML proxy object in PML
在PML中使用代理PML對象主要分為以下步驟：
v 使用IMPORT命令導入組件；
import 'PMLNetExample'
其中PMLNetExample是生成的dll組件名；
v 引入命名空間；
using namespace 'Aveva.Pdms.Examples'
命名空間的名稱與C#中命名空間對應；
v 實例化類對象；
!a = object PMLNetExample()
實例化類對象的方式與其他PML對象一樣。
v 調用對象方法；
!a.method()
調用對象的方法也和PML對象一樣，得到結果如下圖所示：
Figure 3.2 Test PML proxy object method
4.Rules for Calling .NET
想要在PML中調用.NET類對象，就必須遵守一定的規則。這些規則如下：
v 可被PML調用的.NET組件必須由PMLNetCallable標記且位于%PDMSEXE%目錄中；
v .NET組件中只有類可以被PML使用，結構體、接口及枚舉除外；
v .NET組件中需要被PML調用的類必須由PMLNetCallable標記；
v .NET組件中需要被PML調用的方法必須由PMLNetCallable標記；
v .NET組件中需要被PML調用的方法的參數類型必須為指定的幾種類型；
Figure 4.1 Only PML variables types maybe passed to methods of .NET class
v .NET組件中需要被PML調用的類和方法必須是公有的；
v .NET組件中需要被PML調用的方法不支持默認參數的定義；
v .NET組件中需要被PML調用的類和方法名稱是區分大小寫的；
v .NET組件中需要被PML調用的類中必須要有Assign()方法；
v .NET組件中需要被PML調用的類必須有一個由PMLNetCallable標記的公有的默認構造函數；
如果沒有遵守上述條件之一，當加載相應的組件時就會報出錯誤，錯誤信息如下所示：
(46,87) PML: Object definition for XXX could not be found.
5.Conclusion
綜上所述，在PML中調用.NET組件中的類還是很方便的，只要滿足PML代理類定義的一些規則就可以了。
由于.NET組件中的類是由.NET語言實現的，所以托管C++、C#及VB.NET編寫的組件都可以包裝成代理PML類，進而被PML調用。這種方式就更加擴大了PML可使用的資源，如C++的庫都可以在PML中使用，且代碼更保密，不易查看源碼。
在PML中調用.NET組件中類是可行的，但直接在C#中調用PML卻是不可行的。AVEVA也提供了在C#中調用PML的方式：即通過事件訂閱，詳細請參考文檔。
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