programming .net add-ins for pi processb › cmsa › 04 process book programming...2009/02/26 ·...

Copyright © 2009 OSIsoft, Inc.

PROGRAMMING .NET ADD-INS

FOR PI PROCESSBOOK

BUILDERS' CAFÉ WEBINAR SERIES


2

AGENDA

• Intro

• PI ProcessBook and its "programmatic hooks"

• Using Visual Studio to create an add-in

• Templates to make it even easier

• Packaging and Deploying the Add-In

• Conclusion and Q&A


3

PRESENTERS

• Steve Pilon, vCampus Team Member

• Laurie Dieffenbach, Product Manager at OSIsoft

• Eugene Resnick, Development Lead for PI Clients

• John Sintilas, Senior Developer on the PI Clients team


4

VCAMPUS-EXCLUSIVE WEBINARS

• The "Builders' Café" Webinar Series

• Submit your ideas here:


PI PROCESSBOOK AND ITS

"PROGRAMMATIC HOOKS"


6

PI PROCESSBOOK

• User-friendly tool to graphically represent data

– Data from PI, AF, custom and relational data sources

• Already deployed widely and used by thousands of people

– From the plant floor to CxO's


7

WHY PROCESSBOOK ADD-INS?

• Easy to code and deploy

• Application-wide instead of display-specific (VBA)

• Extend access to non-PI and non-Relational data

• By extending the PB UI (vs. standalone app), end-users stay in a familiar environment

• Customers:

– Give more power/flexibility in your end-users' hands

• Partners:

– Open up new business opportunities


8

GREAT ADD-IN EXAMPLES

• Visiant Pimsoft– UC 2007, Monterey

(http://www.osisoft.com/Resources/Multimedia/User+Conference+2007/MO-02-04D.htm)

– 3D Navigation

• Data South Systems (DSS)– http://www.datasouthsystems.com/

– Add-ins that convert DCS (and other) graphics to ProcessBook displays

• Exele– www.exele.com

– ProcessTemplates evaluates batch parameters

http://www.osisoft.com/Resources/Multimedia/User+Conference+2007/MO-02-04D.htm






http://www.datasouthsystems.com/

http://www.exele.com/


9

PB'S PROGRAMMATIC HOOKS

Object Model.NET Interop Assemblies

vCampus Library: PI ProcessBook VBA Language Reference


10

EXTENDING THE UI

Docked WindowContext Menu

Command Bar (Buttons, Combobox, etc.)

Menu


CREATE AN ADD-INWITH VISUAL STUDIO


12

WHAT'S AN ADD-IN, REALLY?

• Class that implements the IDTExtensibility interface– IDisposable interface recommended

C#

VB.NET

• During startup: OnConnection()

• During shutdown: OnDisconnection()

• Not used: OnAddinsUpdate(), OnBeginShutdown()OnStartupComplete()

IDTExtensiblity

OnConnection()

OnStartupComplete()OnAddinsUpdate()

OnBeginShutdown()

OnDisconnection()


13

THE CODE…


14

MAKING YOUR ADD-IN LOAD IN PB

• Registry Key: HKLM\Software\PISystem\PI - ProcessBook

• Assembly must be registered (regasm)

• Assembly should be located in the \PIPC\ProcBook directory

• Dependencies

Key Values used by ProcessBook

Name corresponds to namespace + class


15

ADD-IN LIFECYCLE IN PB

OOnConnection()

IDTExtensibility

Startup

Operation

void m_app_DisplayActivate(Display aDisplay)…

Shutdown

OnDisconnection()

IDTExtensibility

O

PB Events


TEMPLATES TO MAKE IT EVEN

EASIER


17

4 ADD-IN TEMPLATES

• Available for VS2005

– Working on upgrade for VS2008

• Provided as 8 .ZIP files + 8 .DOC files

– 4 for C# and 4 for VB.NET

1. Simple Add-In

2. Toolbar Add-In

3. Docking Window Add-In

4. Custom Data Set Add-In


18

USING THE TEMPLATES IN VISUAL STUDIO

• Copy the .ZIP files to:

– My Documents\Visual Studio 2008\Templates\Project Templates\Visual C# (and/or Visual Basic)


19

SIMPLE ADD-IN

• Invisible add-in

• Can react to events from ProcessBook

– Application (15 events)

• Connection, Displays, etc.

– Display (44 events)

• Connection, Data, Symbols, etc.

– ProcBook (3 events)

• Before/After Save, New Display

– Layers class, Symbol classes, Trend class, etc.


20

SIMPLE ADD-IN – THE CODE


21

BEST PRACTICES

•Event handlers should return quickly

•Connect to servers in DockWindow.Show()

•Reference counting

– Marshal.ReleaseComObject(object)

– Obtain a reference at every level

• Not recommended: – Symbol sym = pbApp.ActiveDisplay.Symbols(1);

• Recommended:– Display disp = pbApp.ActiveDisplay;

– Symbol sym = disp.Symbols(1);

• PI ActiveView compatibility: See the “PI ProcessBook Add-ins and PI ActiveView, Making them work together” white paper in tech support downloads

•Garbage Collection: GC.Collect() in OnDisconnect() and Timer

•ComVisible(true) attribute should only be set for the Connect class

•Check “Register for COM Interop” in the project settings Build tab


22

TOOLBAR ADD-IN

• Creates a toolbar and a dialog window for user interaction

1. Application.CommandBars

2. PBCommandBar.Controls

3. PBCommandBarControl:item on a toolbar


23

TOOLBAR ADD-IN – THE CODE


24

DOCKING WINDOW ADD-IN

• Creates a docking window for user interaction1. Application.PBDockWindows

2. PBDockWindow.Views

3. PBControlView:displays an ActiveX Control

• Recommended to implementa positioningsave/restoremechanism

– Registry or config file


25

DOCKING WINDOW ADD-IN – THE CODE


26

CUSTOM DATA SETS 101 – 1/2

• Additional data retrieval methods for dynamic symbols (trend, value, bar, etc.)

• Configurable

Tools > Data Sets...

Edit...


27

CUSTOM DATA SETS 101 – 2/2

• Invoked from dynamic symbols

• Configurable columns


28

CUSTOM DATA SET ADD-IN

• Application.Datasets.Add(...)

• Class added as dataset must implement the IDataProvider3 interface


29

CUSTOM DATASET: TERMINOLOGY

• Configuration String

• Dataset Name

• Column

• Placeholder

• Datapoint

• PIValues Collection (PI SDK)


30

IDATAPROVIDER3 INTERFACE

void Terminate()

bool HasPlaceholderConfiguration()

void Initialize(PBObjLib.Dataset ds)

void ShowPlaceholderConfiguration(DataPoint dp)

bool HasColumnConfiguration()

bool ShowColumnConfiguration(Columns cols, DataPoint dp)

bool IsColumnValid(DataPoint dp)

void GetColumnAttributes(ref values, DataPoint dp)

bool HasConfiguration()

void ShowConfiguration()

string GetMenuItem()

void GetProviderTime(DataPoint dp, ref PITimeServer.IClockSource clocksource)

void GetData(ref PIValues pivalues, DataPoint dp, int starttime, int endtime, int maxvalues)

void Refresh()


31

CONFIGURATION ENTRY POINTS

Menu Item:

string GetMenuItem()

Dataset Configurationbool HasConfiguration()

void ShowConfiguration()

Startup: void Initialize(PBObjLib.Dataset ds)

Shutdown: void Terminate()

ColumnConfigurationbool HasColumnConfiguration()

void ShowColumnConfiguration()


32

DATA ACCESS ENTRY POINTS

OOnConnection()

IDTExtensibility

OnConnection

{

CustomDataset DS = new CustomDataset();

m_PBApp.Datasets.Add("Random”, ,…);

…

}

void GetColumnAttributes(…)

void Refresh(…)

{

…

DS.PISDKUpdateData()

}

void GetData(…)


PACKAGING AND

DEPLOYING THE ADD-IN


34

PACKAGING/DEPLOYING AN ADD-IN

• Using the "setup package" creator of your choice:

1. Verify that PI ProcessBook is installed

2. Copy .DLLs to the \PIPC\ProcBook folder

3. Register add-ins in the Windows Registry

• The following pages show a basic example with Visual Studio 2008 (additional checking required)


35

SETUP PROJECT

• Create a "Setup Project" in Visual Studio


36

PROJECT OUTPUT

• Add a "Project Output" (the .DLL file) to the Setup Project


37

DO NOT INSTALL DEPENDENCIES

• Exclude the OSIsoft dependencies from the list of files to install


38

DEFAULT LOCATION

• Select the default location for "Application Folder"


39

FILE/DEPENDENCY SEARCH

• Add a "File Search" to look for dependencies

– Example: ProcBook.exe, version 3.1+


40

LAUNCH CONDITION

• Add a "Launch Condition" using the "File Search" added previously


41

REGISTRY KEYS

• Create the required registry keys


42

THE END

Compile, deploy and make your ProcessBook users

even happier


CONCLUSION


44

ADDITIONAL RESOURCES

• "Show Me How" Training Webinars

– [11-Dec-08] ProcessBook v3.1 Training

– [01-Jun-06] Intro to ProcessBook Scripting - Valuable Macros with 5 lines of Code

– [13-Jul-06] How to Build an Add-In to PI ProcessBook (VB6)

• Instructor-led or Computer-based Training

– PI ProcessBook, PI DataLink and RtWebParts

• vCampus Discussion Forums!


45

Q & A


46

HOW TO CONTACT US

1. vCampus Discussion Forums

2. http://vCampus.osisoft.com > Contact Us

3. [email protected]

http://vcampus.osisoft.com/

mailto:[email protected]


47

VCAMPUS-EXCLUSIVE WEBINARS

• The "Builders' Café" Webinar Series

• Submit your ideas here:


48

NEXT VCAMPUS WEBINAR