AVEVA .NET Quick Start Guide

AVEVA .NET快速入門引導

eryar@163.com

一、概述 Introduction

AVEVA提供.Net的二次開發(fā)接口，可使有C#編程經(jīng)驗的軟件工程師使用Visual Studio來對AVEVA的工廠(Plant)設(shè)計和船舶(Marine)設(shè)計產(chǎn)品進行二次開發(fā)。使用.NET不僅可以對原來的PDMS進行二次開發(fā)，還可以對整合后的AVEVA Marine中的Hull Design、Hull Drafting等原來屬于Tribon的程序進行二次開發(fā)。

使用PML二次開發(fā)要受限于AVEVA提供的PML對象，可使用的資源有限。而使用.Net來進行二次開發(fā)，不僅可以利用AVEVA提供的類庫，還可以利用很多資源，開發(fā)效率更高。

如要對AVEVA進行二次開發(fā)去滿足PDM或CIMS等管理軟件的數(shù)據(jù)格式，使用PML可能就有些受限，而使用.NET則可以滿足任何要求。

還有一個代碼加密問題。對于PML，AVEVA也有提供加密程序PML Publisher來保證PML源代碼的安全問題。使用.NET開發(fā)，提供給用戶的就是個DLL，相對而言安全些。雖然也可通過有關(guān)工具可以得到DLL中的源代碼。

當掌握了.NET和PML后，可根據(jù)需要選擇合適的、快速的開發(fā)方法。

本文僅供使用C#進行AVEVA .NET二次開發(fā)的愛好者入門學習參考使用，若你是AVEVA .NET開發(fā)高手，歡迎多提寶貴意見和建議。由于本人水平有限，定有錯誤之處，歡迎批評指正。若有任何意見、建議，都可以與我交流：eryar@163.com。

二、.NET 二次開發(fā)架構(gòu) .NET Customisation Architecture

引入微軟的.NET技術(shù)來對AVEVA進行二次開發(fā)，為AVEVA的二次開發(fā)打開了一個全新的世界，也便于其它系統(tǒng)與AVEVA產(chǎn)品的集成。.NET API可以訪問產(chǎn)品的各方面，包括圖形用戶界面(Graphical User Interface)，數(shù)據(jù)庫(Database)和幾何庫(Geometry)。

作為AVEVA持續(xù)進步(continual progression)方針的一部分，引入的.NET二次開發(fā)也可以在PML中使用。通過PML.NET這個加強的PML可以調(diào)用.NET的程序，加強了二次開發(fā)能力。

Figure 2.1 .NET customisation Architecture

上圖所示為使用.NET二次開發(fā)的兩種方式。一種是使用.NET插件；另一種是使用PML.NET。兩種方式的機制都可以使用程序被動態(tài)加載到使用的模塊中。

2．1 通用程序框架接口 Common Application Framework Interfaces

通用程序框架(CAF)是提供給程序員使用支持程序開發(fā)和自定義開發(fā)各種功能的一個擴展框架。CAF的基本功能由以下兩個組件提供：

u Aveva.AppliationFramework.dll;

u Aveva.AppliationFramework.Presentation.dll;

Namespace: Aveva.ApplicationFramework

u AddinManager: 這個類提供對程序框架插件管理的屬性和方法；

u ServiceManager: 這個類定義了程序框架發(fā)布服務(wù)的接口；

u SettingsManager: 這個類提供了程序設(shè)置的管理的屬性和方法；

Namespace: Aveva.ApplicationFramework.Presentation

u CommandBarManager: 提供使用CAF程序的菜單和命令欄的能力。還可以從用戶接口文件(User Interface Customisation)中載入菜單和命令欄定義。

u CommandManager: 這個類定義了接口來管理命令對象，命令對象是與工具條或其它用戶接口關(guān)聯(lián)的對象。使用工具將會使用其相關(guān)聯(lián)的命令對象執(zhí)行。即命令模式。

u ResourceManager: 對本地資源文件的管理類。使用ResourceManager提供的方法可以使用資源文件包含的各種資源，如字符串、圖像、光標、圖標等。

u WindowManager: 提供訪問主程窗口、狀態(tài)欄和一系列MDI和浮動窗口。也提供了使用這些窗口包含用戶控件的方法。

2．2 數(shù)據(jù)庫接口 Database Interfaces

與數(shù)據(jù)庫相關(guān)的接口由下列組件提供：

u Aveva.Pdms.Database.dll;

u PDMSFilters.dll

Namespace: Aveva.Pdms.Database

u DatabaseService：這個類僅有功能就是打開一個工程；

u DbAttribute：這個類有個功能：

n 類的實例可以用來標識和傳遞屬性；

n 提供可以獲得屬性元數(shù)據(jù)的方法，如類型、尺寸、名稱、等等。對系統(tǒng)屬性和自定義屬性(UDA)也可用。

u DB：提供打開DB的相關(guān)信息；

u DbElement：類的實例用來表示一個元素。這是對數(shù)據(jù)庫進行讀寫的一個主要的類。方法涉及：

n 創(chuàng)建元素；

n 刪除元素；

n 復制；

n 獲取/設(shè)置屬性和規(guī)則；

n 數(shù)據(jù)的導航；

n evaluating database expressions.

u DbElementType：類有兩個功能：

n 類的實例用來表示元素類型；

n 也可獲取元素類型的元數(shù)據(jù)；

u DbEvents：這個類包含處理數(shù)據(jù)庫的機制。如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：當數(shù)據(jù)庫改變時觸發(fā)的事件；

u MDB：對MDB的操作，如：savework, getwork；

u Table：各種類訪問內(nèi)部Dabacon表，如name table；

u Project：主要方法是用來打開MDB；

2．3 幾何庫接口 Geometry Interfaces

與幾何庫相關(guān)的接口由下列組件提供：

u AVEVA.Pdms.Geometry.dll

提供與幾何計算相關(guān)的類，請參考相關(guān)文檔。

2．4 共享接口 Shared Interfaces

一些常用的接口由下列組件提供：

u Aveva.Pdms.Shared.dll

提供當前元素(current element)、選擇改變事件(selection changed events)和數(shù)據(jù)列表(Data listing)功能。

2．5 功能接口 Utilities Interfaces

功能接口由下列組件提供：

u Aveva.Pdms.Ultilitis.dll

提供了消息、字符串、跟蹤、單位和重做功能。還提供了使用命令窗口的方法，但是對其支持不是很好。

2．6 圖形接口 Graphics Interfaces

提供訪問圖形列表(drawlist)和顏色的接口由下列組件提供：

u Aveva.Pdms.Graphics.dll

上述是對使用AVEVA的.NET開發(fā)的一個概要介紹，也許還是很抽象。本文將會以一個具體例子來實現(xiàn)使用.NET進行二次開發(fā)的過程。（.NET開發(fā)的組件PML也可調(diào)用。）在例子中將會介紹.NET接口的使用方法。若理解了這個簡單例子后，對上述介紹也會有更感性的認識。關(guān)于這些接口中屬性和方法的定義，請參考文后列舉的參考資料。

三、怎樣開發(fā)插件 How to Write an Addin

Figure 3.1 Writing a .NET Addin

如上圖所示，描述了開發(fā).NET插件的主要步驟，及對程序的配置使其加載CAF的插件。

u 編寫.NET程序，生成動態(tài)庫；

u 將生成的動態(tài)庫復制到安裝目錄；

u 在相關(guān)的配置文件中添加插件信息，以使相關(guān)模塊可以加載插件；

u 自定義調(diào)用插件的菜單或命令欄；

以下對二次開發(fā)的方式進行介紹：

3．1 IAddin接口

Figure 3.2 IAddin Interface

區(qū)別AVEVA的.NET插件與其它.NET組件的關(guān)鍵點就是：AVEVA的.NET插件都包含對IAddin接口實現(xiàn)的類。當CAF加載和啟動插件時，會詢問這個插件對IAddin接口的實現(xiàn)類，創(chuàng)建這個類的實例并調(diào)用IAddin.Start方法。

如下程序為實現(xiàn)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．窗口的創(chuàng)建

一個插件通常是通過用戶接口（Graphical User Interface）將其功能暴露給用戶使用。這些用戶接口一般是菜單或命令欄。有時插件開發(fā)人員希望插件的用戶接口在浮動的窗口中或是MDI的一個子窗口。CAF的WindowManager可以用來創(chuàng)建這兩種類型的窗口：

Figure 3.3 Use WindowManager to Create Window

上述代碼中使用了ServiceManager.GetService方法來獲取WindowManager功能，并使用WindowManager的CreateDockedWindow方法創(chuàng)建一個浮動窗口來放置AttributeListControl。函數(shù)CreateDockedWindow的第一個參數(shù)：Key，是窗口惟一的標識符。為了避免沖突，推薦的命名方式為：<公司名>.<插件名>.<窗口名>。

使用WindowManager.CreateMdiWindow方法可以創(chuàng)建多文檔窗口MDI（Multiple Document Interface）。

2．IWindow接口

類DockedWindow和MdiWindow都是IWindow接口的實現(xiàn)，都有如下方法和屬性：

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：浮動窗口和多文檔窗口也支持一些事件，如關(guān)閉Closed、當前激活狀態(tài)Activated、未激活狀態(tài)Deactivated、重設(shè)窗口大小Resized。

WindowManager Events：WindowManager也支持兩個事件：

u System.EventHandler WindowLayoutLoaded：當加載窗口布局時觸發(fā)；

u WindowEventHandler WindowAdded：當創(chuàng)建浮動窗口或多文檔窗口時觸發(fā)；

3． 狀態(tài)欄 The StatusBar

CAF也提供狀態(tài)欄的接口，如下圖所示：

Figure 3.1 The StatusBar

狀態(tài)欄是通過WindowManager的屬性StatusBar來設(shè)置的。

  1: // Add a new panel to contain the project name.
  2: StatusBar statusBar = windowManager.StatusBar;

狀態(tài)欄有如下屬性：

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的集合屬性可以創(chuàng)建常見的Panels。如下所示為在狀態(tài)欄上創(chuàng)建文字。

Figure 3.1 Add TextPanel to the StatusBar

StatusBarTextPanel對象也支持PanelClick和PanelDoubleClick事件。具體請參考相關(guān)幫助文檔。

4．插件命令 Addin Commands

用戶使用插件的功能通常是通過菜單或右鍵菜單或工具欄上的按鈕來實現(xiàn)的。通用程序框架CAF提供了一個接口CommandBarManager來創(chuàng)建菜單、命令欄及其它包含的各種類型的按鈕。這些工具支持傳統(tǒng)的菜單響應(yīng)方式，即由程序員來提供各種響應(yīng)函數(shù)。盡管傳統(tǒng)的方式CAF還支持，但是不推薦。通用程序框架還支持用一種類似XML的文件來定義菜單、命令欄及其上的工具按鈕。通過加載用戶接口自定義文件（User Interface Customisation）方便程序的開發(fā)。

5．配置模塊使其加載插件 Configuring a Module to Load an Addin

插件程序?qū)懞弥缶褪且屇硞€模塊加載它。每個模塊都有一個在啟動時加載插件的配置文件。插件默認路徑是執(zhí)行程序的路徑。配置插件的文件名形式為：<模塊名>Addins.xml。例如：設(shè)計Design模塊的插件配置文件名為：DesignAddins.xml，文件內(nèi)容如下所示。插件默認路徑也是執(zhí)行程序所在目錄，當然你也可以指定插件的完整路徑。如果不想修改安裝目錄下的這些插件配置文件，可以使用環(huán)境變量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二次開發(fā)架構(gòu)和常用的開發(fā)接口有個大概認識之后，現(xiàn)在將以一個具體的程序來詳細介紹開發(fā)過程。通過動手實踐會加深上述內(nèi)容的認識。

1．創(chuàng)建新的工程

Figure 4.1 Create a New Project

創(chuàng)建一個C#類庫的工程，命名為HelloAddin。

2．添加需要使用的引用庫

Figure 4.2 Add Reference Library

根據(jù)上文的介紹，添加引用的庫。這里用到了兩個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，這也是插件與其它動態(tài)庫組件的區(qū)別。打開IAddin，可以看到這個接口有如下內(nèi)容：

  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: }

所以派生的插件類都要重寫這幾個虛函數(shù)。當插件被加載時，函數(shù)Start將會被調(diào)用。所以我在Start函數(shù)加只顯示一個消息框。當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．調(diào)試程序

調(diào)試程序的方式也許有些笨拙，但也是實用的。若你有更好的方法，請不吝賜教。調(diào)試的方法也是利用上述消息框來阻塞，使加載停滯不前，這時可以使用Visual Studio中的調(diào)試，附加到進程就可以了。

當出現(xiàn)上述消息框時，使附加到進程，選擇marodes.exe即可。如下圖所示：

Figure 4.8 Debug for the HelloAddin

附加進程后對消息框ok后即可進入到插件中的斷點處。

五、 結(jié)論

上文的工程是使用AVEVA的CAF二次開發(fā)最簡單的程序。這個程序什么事情也做不了。關(guān)于使用.NET對AVEVA進行二次開發(fā)的詳細教程請參考：《.NET Customisation User Guide》。

關(guān)于更詳細的例子，請參考AVEVA提供的示例代碼：AttributeBrowserAddin和ExamplesAddin。

u 示例工程：AttributeBrowserAddin。本程序?qū)崿F(xiàn)了一個簡單的屬性查看列表。其中實現(xiàn)了插件命令對象，即通過響應(yīng)工具條上的按鈕來控制窗口的可見性。

u 示例工程：ExamplesAddin。本程序?qū)崿F(xiàn)的對設(shè)計數(shù)據(jù)元素的訪問和控制，并在提供了一個配置插件被加載的文件：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

eryar@163.com

Shanghai China

2012-11-03