AVEVA .NET Quick Start Guide
AVEVA .NET快速入門引導
eryar@163.com
一、概述 Introduction
AVEVA提供.Net的二次開發接口，可使有C#編程經驗的軟件工程師使用Visual Studio來對AVEVA的工廠(Plant)設計和船舶(Marine)設計產品進行二次開發。使用.NET不僅可以對原來的PDMS進行二次開發，還可以對整合后的AVEVA Marine中的Hull Design、Hull Drafting等原來屬于Tribon的程序進行二次開發。
使用PML二次開發要受限于AVEVA提供的PML對象，可使用的資源有限。而使用.Net來進行二次開發，不僅可以利用AVEVA提供的類庫，還可以利用很多資源，開發效率更高。
如要對AVEVA進行二次開發去滿足PDM或CIMS等管理軟件的數據格式，使用PML可能就有些受限，而使用.NET則可以滿足任何要求。
還有一個代碼加密問題。對于PML，AVEVA也有提供加密程序PML Publisher來保證PML源代碼的安全問題。使用.NET開發，提供給用戶的就是個DLL，相對而言安全些。雖然也可通過有關工具可以得到DLL中的源代碼。
當掌握了.NET和PML后，可根據需要選擇合適的、快速的開發方法。
本文僅供使用C#進行AVEVA .NET二次開發的愛好者入門學習參考使用，若你是AVEVA .NET開發高手，歡迎多提寶貴意見和建議。由于本人水平有限，定有錯誤之處，歡迎批評指正。若有任何意見、建議，都可以與我交流：eryar@163.com。
二、.NET 二次開發架構 .NET Customisation Architecture
引入微軟的.NET技術來對AVEVA進行二次開發，為AVEVA的二次開發打開了一個全新的世界，也便于其它系統與AVEVA產品的集成。.NET API可以訪問產品的各方面，包括圖形用戶界面(Graphical User Interface)，數據庫(Database)和幾何庫(Geometry)。
作為AVEVA持續進步(continual progression)方針的一部分，引入的.NET二次開發也可以在PML中使用。通過PML.NET這個加強的PML可以調用.NET的程序，加強了二次開發能力。
Figure 2.1 .NET customisation Architecture
上圖所示為使用.NET二次開發的兩種方式。一種是使用.NET插件；另一種是使用PML.NET。兩種方式的機制都可以使用程序被動態加載到使用的模塊中。
2．1 通用程序框架接口 Common Application Framework Interfaces
通用程序框架(CAF)是提供給程序員使用支持程序開發和自定義開發各種功能的一個擴展框架。CAF的基本功能由以下兩個組件提供：
u Aveva.AppliationFramework.dll;
u Aveva.AppliationFramework.Presentation.dll;
Namespace: Aveva.ApplicationFramework
u AddinManager: 這個類提供對程序框架插件管理的屬性和方法；
u ServiceManager: 這個類定義了程序框架發布服務的接口；
u SettingsManager: 這個類提供了程序設置的管理的屬性和方法；
Namespace: Aveva.ApplicationFramework.Presentation
u CommandBarManager: 提供使用CAF程序的菜單和命令欄的能力。還可以從用戶接口文件(User Interface Customisation)中載入菜單和命令欄定義。
u CommandManager: 這個類定義了接口來管理命令對象，命令對象是與工具條或其它用戶接口關聯的對象。使用工具將會使用其相關聯的命令對象執行。即命令模式。
u ResourceManager: 對本地資源文件的管理類。使用ResourceManager提供的方法可以使用資源文件包含的各種資源，如字符串、圖像、光標、圖標等。
u WindowManager: 提供訪問主程窗口、狀態欄和一系列MDI和浮動窗口。也提供了使用這些窗口包含用戶控件的方法。
2．2 數據庫接口 Database Interfaces
與數據庫相關的接口由下列組件提供：
u Aveva.Pdms.Database.dll;
u PDMSFilters.dll
Namespace: Aveva.Pdms.Database
u DatabaseService：這個類僅有功能就是打開一個工程；
u DbAttribute：這個類有個功能：
n 類的實例可以用來標識和傳遞屬性；
n 提供可以獲得屬性元數據的方法，如類型、尺寸、名稱、等等。對系統屬性和自定義屬性(UDA)也可用。
u DB：提供打開DB的相關信息；
u DbElement：類的實例用來表示一個元素。這是對數據庫進行讀寫的一個主要的類。方法涉及：
n 創建元素；
n 刪除元素；
n 復制；
n 獲取/設置屬性和規則；
n 數據的導航；
n evaluating database expressions.
u DbElementType：類有兩個功能：
n 類的實例用來表示元素類型；
n 也可獲取元素類型的元數據；
u DbEvents：這個類包含處理數據庫的機制。如savework, getwork, undo, redo, flush, refresh, drop等。
u DbExpression：
u DbPseudoAttribute：This Class allows pseudo attribute code to be plugged in for UDAs；
u DbRule：Class to hold a database rule；
u DbUserChanges：當數據庫改變時觸發的事件；
u MDB：對MDB的操作，如：savework, getwork；
u Table：各種類訪問內部Dabacon表，如name table；
u Project：主要方法是用來打開MDB；
2．3 幾何庫接口 Geometry Interfaces
與幾何庫相關的接口由下列組件提供：
u AVEVA.Pdms.Geometry.dll
提供與幾何計算相關的類，請參考相關文檔。
2．4 共享接口 Shared Interfaces
一些常用的接口由下列組件提供：
u Aveva.Pdms.Shared.dll
提供當前元素(current element)、選擇改變事件(selection changed events)和數據列表(Data listing)功能。
2．5 功能接口 Utilities Interfaces
功能接口由下列組件提供：
u Aveva.Pdms.Ultilitis.dll
提供了消息、字符串、跟蹤、單位和重做功能。還提供了使用命令窗口的方法，但是對其支持不是很好。
2．6 圖形接口 Graphics Interfaces
提供訪問圖形列表(drawlist)和顏色的接口由下列組件提供：
u Aveva.Pdms.Graphics.dll
上述是對使用AVEVA的.NET開發的一個概要介紹，也許還是很抽象。本文將會以一個具體例子來實現使用.NET進行二次開發的過程。（.NET開發的組件PML也可調用。）在例子中將會介紹.NET接口的使用方法。若理解了這個簡單例子后，對上述介紹也會有更感性的認識。關于這些接口中屬性和方法的定義，請參考文后列舉的參考資料。
三、怎樣開發插件 How to Write an Addin
Figure 3.1 Writing a .NET Addin
如上圖所示，描述了開發.NET插件的主要步驟，及對程序的配置使其加載CAF的插件。
u 編寫.NET程序，生成動態庫；
u 將生成的動態庫復制到安裝目錄；
u 在相關的配置文件中添加插件信息，以使相關模塊可以加載插件；
u 自定義調用插件的菜單或命令欄；
以下對二次開發的方式進行介紹：
3．1 IAddin接口
Figure 3.2 IAddin Interface
區別AVEVA的.NET插件與其它.NET組件的關鍵點就是：AVEVA的.NET插件都包含對IAddin接口實現的類。當CAF加載和啟動插件時，會詢問這個插件對IAddin接口的實現類，創建這個類的實例并調用IAddin.Start方法。
如下程序為實現IAddin接口類的簡單例子：
1: using System;
2: using System.Collections.Generic;
3: using System.Text;
4: // Add additional using statements
5: using Aveva.ApplicationFramework;
6: using Aveva.ApplicationFramework.Presentation;
7: using Aveva.Pdms.Shared;
8: using Aveva.Pdms.Database;
9:
10: namespace Aveva.Presentation.AttributeBrowserAddin
11: {
12: public class AttributeBrowserAddin : IAddin
13: {
14: private DockedWindow attributeListWindow;
15: private AttributeListControl attributeListControl;
16: #region IAddin Members
17:
18: public string Description
19: {
20: get
21: {
22: return "Provides a simple attribute browser";
23: }
24: }
25:
26: public string Name
27: {
28: get
29: {
30: return "AttributeBrowserAddin";
31: }
32: }
33:
34: public void Start(ServiceManager serviceManager)
35: {
36: System.Windows.Forms.MessageBox.Show("Blcok");
37:
38: // Create Addins Windows
39: // Get the WindowManager service
40: WindowManager windowManager = (WindowManager)serviceManager.GetService(typeof(WindowManager));
41: attributeListControl = new AttributeListControl();
42: // Create a docked window to host an AttributeListControl
43: attributeListWindow = windowManager.CreateDockedWindow("Aveva.AttributeBrowser.AttributeList", "Attributes", attributeListControl, DockedPosition.Right);
44: attributeListWindow.Width = 200;
45: // Docked windows created at addin start should ensure their layout is saved between sessions.
46: attributeListWindow.SaveLayout = true;
47:
48: // Create and register addins commands
49: // Get the CommandManager
50: CommandManager commandManager = (CommandManager)serviceManager.GetService(typeof(CommandManager));
51: ShowAttributeBrowserCommand showCommand = new ShowAttributeBrowserCommand(attributeListWindow);
52: commandManager.Commands.Add(showCommand);
53:
54: // Add event handler for current element changed event.
55: CurrentElement.CurrentElementChanged += new CurrentElementChangedEventHandler(CurrentElement_CurrentElementChanged);
56:
57: // Get the ResourceManager service.
58: ResourceManager resourceManager = (ResourceManager)serviceManager.GetService(typeof(ResourceManager));
59: resourceManager.LoadResourceFile("AttributeBrowserAddin");
60:
61: // Add a new panel to contain the project name.
62: StatusBar statusBar = windowManager.StatusBar;
63: StatusBarTextPanel projectNamePanel = statusBar.Panels.AddTextPanel("Aveva.ProjectName", "Project : " + Project.CurrentProject.Name);
64: projectNamePanel.SizingMode = PanelSizingMode.Automatic;
65: // Get the panel image from the addins resource file.
66: projectNamePanel.Image = resourceManager.GetImage("ID_PROJECT_ICON");
67:
68: // Load a UIC file for the AttributeBrowser.
69: CommandBarManager commandBarManager = (CommandBarManager)serviceManager.GetService(typeof(CommandBarManager));
70: commandBarManager.AddUICustomizationFile("AttributeBrowser.uic", "AttributeBrowser");
71: }
72:
73: void CurrentElement_CurrentElementChanged(object sender, CurrentElementChangedEventArgs e)
74: {
75: // Set the window title to the name of the element.
76: string windowTitle = "Attributes of element " + CurrentElement.Element.GetAsString(DbAttributeInstance.FLNM);
77: attributeListWindow.Title = windowTitle;
78: // Clear attribute list
79: attributeListControl.Clear();
80: // Populate the attribute list with attributes of the current element
81: foreach (DbAttribute attribute in CurrentElement.Element.GetAttributes())
82: {
83: attributeListControl.AddAttribute(attribute.Name, CurrentElement.Element.GetAsString(attribute));
84: }
85:
86: }
87:
88: public void Stop()
89: {
90: }
91:
92: #endregion
93: }
94: }
95:
3．2 The WindowManager
1．窗口的創建
一個插件通常是通過用戶接口（Graphical User Interface）將其功能暴露給用戶使用。這些用戶接口一般是菜單或命令欄。有時插件開發人員希望插件的用戶接口在浮動的窗口中或是MDI的一個子窗口。CAF的WindowManager可以用來創建這兩種類型的窗口：
Figure 3.3 Use WindowManager to Create Window
上述代碼中使用了ServiceManager.GetService方法來獲取WindowManager功能，并使用WindowManager的CreateDockedWindow方法創建一個浮動窗口來放置AttributeListControl。函數CreateDockedWindow的第一個參數：Key，是窗口惟一的標識符。為了避免沖突，推薦的命名方式為：<公司名>.<插件名>.<窗口名>。
使用WindowManager.CreateMdiWindow方法可以創建多文檔窗口MDI（Multiple Document Interface）。
2．IWindow接口
類DockedWindow和MdiWindow都是IWindow接口的實現，都有如下方法和屬性：
u void Hide() Conceals the window from the user
u void Show() Displays the window to the user
u void Float() Displays the window as a floating window
u void Dock() Docks the window within the main window
u void Close() Destroys the window removing it from the windows collection.
u System.Windows.Forms.Control Control 取得窗口上的控件；
u bool Enabled: Gets or sets whether the window is enabled.
u bool Floatable: Gets or sets whether the window is floatable.
u int Height: Gets or sets the height of the window.
u bool IsFloating: Gets the floating state of a window.
u string Key: Gets the Key of the window in the WindowsCollection.
u string Title: Gets or sets the title/caption of the window.
u bool Visible: Gets or sets the visible state of the window.
u int Width: Gets or sets the width of the window.
u Size Maximum Size: Get or set the maximum size of the window.
u Size Minimum Size: Get or set the minimum size of the window.
窗口事件Window Events：浮動窗口和多文檔窗口也支持一些事件，如關閉Closed、當前激活狀態Activated、未激活狀態Deactivated、重設窗口大小Resized。
WindowManager Events：WindowManager也支持兩個事件：
u System.EventHandler WindowLayoutLoaded：當加載窗口布局時觸發；
u WindowEventHandler WindowAdded：當創建浮動窗口或多文檔窗口時觸發；
3． 狀態欄 The StatusBar
CAF也提供狀態欄的接口，如下圖所示：
Figure 3.1 The StatusBar
狀態欄是通過WindowManager的屬性StatusBar來設置的。
1: // Add a new panel to contain the project name.
2: StatusBar statusBar = windowManager.StatusBar;
狀態欄有如下屬性：
u bool Visible - Gets or sets the visibility of the StatusBar.
u string Text - Gets or sets the text to display in the default StatusBar text pane.
u int Progress - Gets or sets the progress bar value [0-100]. If this is set to 0 then the progress bar is hidden.
u string ProgressText - Text to describe the action being tracked by the progress bar.
u bool ShowDateTime - Gets or sets whether the Date and Time should be displayed on the StatusBar.
u bool ShowCapsLock - Gets or sets whether the panel showing the CapsLock state is displayed on the StatusBar.
u bool ShowNumLock - Gets or sets whether the panel showing the NumLock state is displayed on the StatusBar.
u bool ShowScrollLock - Gets or sets whether the panel showing the ScrollLock state is displayed on the StatusBar.
u bool ShowInsertMode - Gets or sets whether the panel showing the InsertMode is displayed on the statusbar.
u StatusBarPanelsCollection Panels - Gets the collection of application defined StatusBar panels.
使用StatusBar的集合屬性可以創建常見的Panels。如下所示為在狀態欄上創建文字。
Figure 3.1 Add TextPanel to the StatusBar
StatusBarTextPanel對象也支持PanelClick和PanelDoubleClick事件。具體請參考相關幫助文檔。
4．插件命令 Addin Commands
用戶使用插件的功能通常是通過菜單或右鍵菜單或工具欄上的按鈕來實現的。通用程序框架CAF提供了一個接口CommandBarManager來創建菜單、命令欄及其它包含的各種類型的按鈕。這些工具支持傳統的菜單響應方式，即由程序員來提供各種響應函數。盡管傳統的方式CAF還支持，但是不推薦。通用程序框架還支持用一種類似XML的文件來定義菜單、命令欄及其上的工具按鈕。通過加載用戶接口自定義文件（User Interface Customisation）方便程序的開發。
5．配置模塊使其加載插件 Configuring a Module to Load an Addin
插件程序寫好之后就是要讓某個模塊加載它。每個模塊都有一個在啟動時加載插件的配置文件。插件默認路徑是執行程序的路徑。配置插件的文件名形式為：<模塊名>Addins.xml。例如：設計Design模塊的插件配置文件名為：DesignAddins.xml，文件內容如下所示。插件默認路徑也是執行程序所在目錄，當然你也可以指定插件的完整路徑。如果不想修改安裝目錄下的這些插件配置文件，可以使用環境變量CAF_ADDINS_PATH來重新指定插件配置文件的路徑。
1: <?xml version="1.0" encoding="utf-8"?>
2: <ArrayOfString xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
3: <string>ExplorerAddin</string>
4: <string>DrawListAddin</string>
5: <string>MyDataAddin</string>
6: <string>HistoryAddin</string>
7: <string>ReferenceListAddin</string>
8: <string>PipeCheckAddin</string>
9: <string>OutputAddin</string>
10: <string>FindAddin</string>
11: <string>LinksAddin</string>
12: <string>AttributesAddin</string>
13: <string>C:\Documents and Settings\User1\My Documents\Visual Studio 2005\AttributeBrowserAddin\AttributeBrowserAddin\bin\Debug\AttributeBrowserAddin</string>
14: </ArrayOfString>
15:
四、Hello World示例程序
對AVEVA的.NET二次開發架構和常用的開發接口有個大概認識之后，現在將以一個具體的程序來詳細介紹開發過程。通過動手實踐會加深上述內容的認識。
1．創建新的工程
Figure 4.1 Create a New Project
創建一個C#類庫的工程，命名為HelloAddin。
2．添加需要使用的引用庫
Figure 4.2 Add Reference Library
根據上文的介紹，添加引用的庫。這里用到了兩個AVEVA的庫，添加方式如下圖所示：
Figure 4.3 Add AVEVA .NET Library
為了使用消息框還需要添加.Net的庫：System.Windows.Forms。
3．編寫程序代碼
1: using System;
2: using System.Collections.Generic;
3: using System.Text;
4:
5: // Add additional using statements
6: using Aveva.ApplicationFramework;
7: using Aveva.ApplicationFramework.Presentation;
8:
9: namespace Aveva.Presentation.HelloAddin
10: {
11: public class HelloAddin : IAddin
12: {
13: #region IAddin Members
14:
15: public string Description
16: {
17: get
18: {
19: return "AVEVA .NET Hello World program!";
20: }
21: }
22:
23: public string Name
24: {
25: get
26: {
27: return "HelloAddin";
28: }
29: }
30:
31: public void Start(ServiceManager serviceManager)
32: {
33: // Show a Hello World message box.
34: System.Windows.Forms.MessageBox.Show("Hello AVEVA .NET!");
35: }
36:
37: public void Stop()
38: {
39: //
40: }
41:
42: #endregion
43: }
44: }
因為AVEVA中的.NET插件都是派生自接口：IAddin，這也是插件與其它動態庫組件的區別。打開IAddin，可以看到這個接口有如下內容：
1: using System;
2:
3: namespace Aveva.ApplicationFramework
4: {
5: public interface IAddin
6: {
7: string Description { get; }
8: string Name { get; }
9: void Start(ServiceManager serviceManager);
10: void Stop();
11: }
12: }
所以派生的插件類都要重寫這幾個虛函數。當插件被加載時，函數Start將會被調用。所以我在Start函數加只顯示一個消息框。當HelloAddin被加載時，會彈出“Hello AVEVA .NET!”的消息框。
4．將插件生成到AVEVA安裝目錄
Figure 4.4 Modify Assembly Output Path
將會在AVEVA安裝目錄生成：HelloAddin.dll。
5．配置加載插件文件
在安裝目錄下有個OutfittingAddins.xml是用來配置Outfitting模塊插件的文件。各模塊配置插件的名稱已在前文中介紹過了。
Figure 4.5 Configure the Addins.xml file to load the Addin
用文本編輯工具打開這個插件配置文件，在其中添加上示例插件：HelloAddin。如下圖所示：
Figure 4.6 Add HelloAddin to the Addin Configure file
6．啟動程序
Figure 4.7 Startup Window of the HelloAddin
選擇Outfitting模塊，啟動程序，這個插件將被加載，如上圖所示。
7．調試程序
調試程序的方式也許有些笨拙，但也是實用的。若你有更好的方法，請不吝賜教。調試的方法也是利用上述消息框來阻塞，使加載停滯不前，這時可以使用Visual Studio中的調試，附加到進程就可以了。
當出現上述消息框時，使附加到進程，選擇marodes.exe即可。如下圖所示：
Figure 4.8 Debug for the HelloAddin
附加進程后對消息框ok后即可進入到插件中的斷點處。
五、 結論
上文的工程是使用AVEVA的CAF二次開發最簡單的程序。這個程序什么事情也做不了。關于使用.NET對AVEVA進行二次開發的詳細教程請參考：《.NET Customisation User Guide》。
關于更詳細的例子，請參考AVEVA提供的示例代碼：AttributeBrowserAddin和ExamplesAddin。
u 示例工程：AttributeBrowserAddin。本程序實現了一個簡單的屬性查看列表。其中實現了插件命令對象，即通過響應工具條上的按鈕來控制窗口的可見性。
u 示例工程：ExamplesAddin。本程序實現的對設計數據元素的訪問和控制，并在提供了一個配置插件被加載的文件：DesignAddins.xml。
六、 參考資料
1．AVEVA .NET Customisation User Guide
2．Sample Code: AttributeBrowserAddin
3．Sample Code: ExamplesAddin
4．.NET Interface Reference Files: Aveva.ApplicationFramework.chm
5．.Net Interface Reference File: Aveva.Pdms.chm
6．.Net Interface Reference File: Aveva.Pdms.Database.chm
7．.Net Interface Reference File: Aveva.Pdms.Database.Filters.chm
8．.Net Interface Reference File: Aveva.Pdms.Design.chm
9．.Net Interface Reference File: Aveva.Pdms.Geometry.chm
10．.Net Interface Reference File: Aveva.Pdms.Graphics.chm
11．.Net Interface Reference File: Aveva.Pdms.Maths.Geometry.chm
12．.Net Interface Reference File: Aveva.Pdms.Piping.chm
13．.Net Interface Reference File: Aveva.Pdms.Shared.chm
14．.Net Interface Reference File: Aveva.Pdms.Standalone.chm
15．.Net Interface Reference File: Aveva.Pdms.Utilities.chm
16．AVEVA Marine .NET Interface：.NETmarAPI.chm
PDF Version and Source Code: AVEVA .NET Quick Start Guide
eryar@163.com
Shanghai China
2012-11-03