Pdms Pmlnet Basics

PML II and PML.NET, which one now? 2013JUN

5 By rbasniak / In PML II, PML Language, PML.NET / Comments(1)

Introduction One of the most waited news from PDMS 12, at least for those who work with code development, is the possibility to create new tools using the Microsoft .NET technology. Despite the fact that PML is a powerful language inside PDMS, it flaws in the lack of basic resources like a debug tool, a graphical interface to create forms and the possibility of communicating with third party software in practical way. The new .NET APIs fulfill these lacks from PML and yet open a whole new world of possibilities for development of new interfaces with other software or just software customization. Microsoft began the development of the .NET framework in the early 90’s, but the first beta version was released only 10 years later. Nowadays it’s on version 4.0, however PDMS supports only version 3.5.

Pros The .NET has a premise like Java, where the code is developed for a platform and not a specific hardware like most programming languages. It’s possible because the code is compiled twice. The first compilation occurs when the user compiles its code, for the CLR language (Common Language Runtime). The next compilation occurs when the software is executed and it’s compiled for the hardware it’s running on. One great advantage of this is the fact that the code can be written in many different languages. By the time when this article was written, it supported more than 20 languages. In theory you can develop in any of these languages, however Aveva only supports C#. Off course if you want, you can code in VB.NET or any other .NET you feel comfortable. Another pro of this framework is that it has a very large amount of ready to use libraries. This speed up a lot the code development because the developer doesn’t have to bother coding solutions that are consolidated and well known for years. In my opinion, the two most critic PML issues were the lack of a graphical user interface to create forms and a debug tool. These problems are solved if you use an IDE (Integrated Development Environment) for .NET as Microsft Visual

Studio, developed by Microsoft and with all tools any developer may need. The major drawback is its price, which begins around 700,00 USD. That’s why I would like to tell you about this amazing open source software: SharpDevelop. It has all features you’ll use for addin development and sometimes they are even better than their Visual Studio counterparts. Now that I already gave an overview of the .NET framework and its advantages, let’s talk more specifically about PDMS. The development with .NET is based on DLLS, in other words, the code is compiled to a .dll file and not a .exe one. This .dll file is called by PDMS when it’s opened (it’s very like the addins system used over the years by other general CAD/CAE software). My greatest disappoint here is that Aveva didn’t make available APIs to access PDMS through executable applications (.exe), like is done by Solidworks, AutoCAD and even Microsoft Office. This way you would be able to develop an external application that would connects to PDMS and interact. Not that it make the APIs useless, but it would be a really nice feature to have.

What can be done o

o

o

We can split addins development into 3 groups: Tools and customization development: here it’s possible to create tools to automate boring tasks or make the creation of new elements easier. Pretty much the same kind of things you would do with PML. The new developed feature must be accessed through a menu or command bar, which is to be created inside PDMS. My next article will explain how to configure PDMS to make use of this kind of addin. Code for pseudo attributes: PMDS 12 introduced one great feature to the UDAs system: now you can create UDAs that will work as pseudo attributes. This kind of attribute doesn’t work like normal attributes, where the user must type a value. Pseudo attributes are calculated whenever the user queries its value. One pseudo attribute I’ll use as example is BRWEI. You never insert the branch’s weight, but if you type Q BRWEI on a branch, there it is: the weight of that branch. Every time you query this attribute, PDMS calculates the value and then show to you. Now it’s possible to create such attributes with UDAs. The code used to evaluate the attribute will be plugged into PDMS as an addin. Object to be called inside PML code: it’s possible to develop DLLs containing objects that can be called inside PML functions. This brings some of the .NET functionality inside PML. A very nice example is an open file dialog. If done in PML you have to take care of its graphical interface, all its features and so on. Also there is the drawback that the form will never look or work like a default Windows open file dialog. This is bad for new PDMS users and I’ve seen such things creating barriers between them and PDMS. But

why reinvent the wheel? Now you can call a .NET DLL provided by Aveva that calls the Windows standard open file dialog and you can use it within your PML code.

Cons Until now I only wrote about good things, but like everything else in life, this also has some cons. One I already told, which is the fact that Aveva didn’t make available APIs to access PDMS through external applications. But in my opinion, the major bad thing about it is that the available APIs basically allow us to navigate through the database, create, delete, change attributes and collect elements. Features like clipping, view manipulations and graphical interaction are completely inaccessible by .NET. Let’s make something clear here: it’s possível to send commands that would be normally used through the command line to PDMS. However the classes that allow us to do this have a description telling that they’re for Aveva use only (in the .NET, because they don’t even appear on the manuals). This feature would solve the above problem, but because of this I’m not considering these classes on serious aplications due the fact that they could be blocked from us at any time on future releases. If you have discovered those classes and want to use them, do this knowing that can be consequences in the near future. Another thing I found really annoying is that when PDMS is opened, it locks the addin’s .dll file and it can’t be erased or modified. This costs a huge amount of development time, especially if you are still learning it, because every time you have to recompile the code, you must close PDMS and then open it again once the code is compiled.

Final words I’ve been seeing people that want to learn PDMS development, and do not you PML, asking if they should go and start learning with .NET. My personal answer is no! PML knowledge will make you see clearer how PDMS and customization works. For those who already know PML and would like to begin learning .NET development for PDMS, it’s essential to have a basic knowledge about C# (or the .NET language of your choice), DLL programming and SharpDevelop (or Visual Studio). So I recommend these links: 

Visual Studio 2010, A Beginner’s Guide by C# Station



Creating and using C# DLLs by K. Balaji



Creating C# Class Library (DLL) Using Visual Studio .NET by Mahesh Chand Next step is to study the PDMS APIs. By now the only resource about it is the .NET Customization User Guide (where’s our Reference Manual Aveva?). To conclude, the .NET development did not make PML obsolete and do not substitute it since there are lots of things you can do with PML that you can’t still do with .NET. However, it opened a whole new world of possibilities when we think about data exchange with third party software.

How to install and configure a PDMS 12 addin mments(0)

Introduction I’m back with a new article related to the new .NET framework. Today’s article is more of a tutorial explaining how to install and then configure a PDMS 12 addin made in .NET. We’ll need an addin to use as example. I made a very simple addin for this purpose. This addin can be used to model trasitions from rectangular sections to circular ones for equipments. We’ll install this addin in PDMS and then configure it to expose its interface to the end user. This will be done with a menu and a commandbar. To download the addin just scroll to the end of this page, it’s totally free.

Making the addin visible to PDMS Each PDMS module is an application by itself, in other words Lexicon is an application, Paragon is another, Design is a third one and so on. When a module is loading, PDMS will load some standard addins from Aveva. The definition of which addin will be loaded is done through some .xml files located inside the PDMS executable folder. These files are named according the module associated with them, e.g. the file that defines which addins are loaded in Paragon is called ParagonAddins.xml, the one for Draft is called DraftAddins.xml and so on.

Picture 1 – Contents of DesignAddins.xml file

The file we are looking for is DesignAddins.xml, since the addin I made is supposed to be used with Design. This file has a very simple structure, as can be seen at Picture 1. For our addin to be loaded what we need is only add a new entry with the name of our addin’s .dll file. That done the only thing we shall do would be to put a copy of the .dll (DrawTransition.dll) inside this folder. However we’ll do the things a little bit different here. I’d say that edit the original PDMS files is not a good practice because you would have to replicate these changes to every PC with PDMS installed and you would have to redo the same changes after each PDMS reinstall or even update. Because of this we’ll make some changes to allow all addin setup or modification accessible to every user over the network. This can be done creating some environment variables that will point to other folders.

Modifying the setup to run over the network First we need to create the folder structure to store the addins and the interface customization files. Create the structure shown on Picture 2 somewhere on the network.

Picture 2 – Folders to store and configure addins

Here I created the folders on the drive D:, so don’t forget to change it to your directory when needed.

There are many ways of setting up these environment variables. For this tutorial we’ll put them in the PDMS .bat file. Right click on the shortcut you use to open PDMS e choose Edit. Windows will find the right file and open to you. In the beginning of the file insert these two lines: Shell

1 set CAF_UIC_PATH=D:\pml.net\interface\config 2 set CAF_ADDINS_PATH=D\:pml.net\addins\config

The CAF_ADDINS_PATH variable informs PDMS where it should search for the addin to load. The CAF_UIC_PATH variable informs PDMS where it should search for saved interface customization files. Now we’re going to copy each module’s addin and interface configuration files. Unfortunately these environment variables aren’t like PMLLIB, where it’s possible to put only the modified files on the new folder and PDMS will search for the others on the installation folder. So we have to copy ALL files called Addins.xml (DesignAddins.xml, ParagonAddins.xml, SchematicsAddins.xml, etc) to the …\pml.net\addins\config folder and ALL files called Customization.xml (DesignCustomization.xml, ParagonCustomization.xml, DraftCustomization.xml, etc) to the …\pml.net\interface\config folder. Copy the DrawTransition_v????.dll file to the …\pml.net\addins\dll folder. Open the DesignAddins.xml on the Notepad and add one more line, like shown on the Picture 3, pointing the folder where you put the DrawTransition_v????.dll file. Note that you have to type exactly the same name as the dll you’re using (there’s one dll for each PDMS version), and do not type the file extension.

Picture 3 – Edited DesignAddins.xml file

Now let’s create a new .uic file to save our menus, buttons and commandbars. Open Notepad and type the following: Shell

1 2 3 4 5 6 7 8 9 1 0 1 1

1.0 3dMacro

Save the file as 3dMacro.uic on the …\pml.net\interface\uic folder. Se preferir pode baixar o arquivo diretamente clicando aqui. Watch out if your Windows is set up to hide file extensions. If yes it will add a .txt extension on your file’s name. It won’t appear to you but the .uic file won’t work. Now we only have to inform PDMS about this new .uic file. Open the …\pml.net\interface\config\DesignCustomization.xml file on the Notepad and change it as show on Picture 4.

Figura 4 – Edited DesignCustomization.xml file

Now the addin is installed and will be loaded in Design. Open PDMS and watch the console window for any errors (the DOS window that starts with PDMS). If you see any error or PDMS does not load, redo the previous steps to see if you haven’t missed anything. What we have to do now is expose the addin interface to the user. In PDMS 12 is possible to create menus and commandbars through the interface. We’ll create a menu and a commandbar that will allow the user to open the addin window.

Creating the command button Right click any menu or commandbar and pick Customize. The window shown in Picture 5 will appear.

Picture 5 – Window used to customize menus and commandbars

Let’s make a little break to explain this window. A) This list allows you to choose which customization file will be edited. B) In this area we can find the user defined menus and commandbars. By default these items are divided in three categories: 

per user



per project



per module C) This area stores the user defined commands which can be inserted in the commandbars and menus. D) The selected item’s properties will be shown here. Some may be read only and cannot be edited by the user. First we’ll create a command which will give the user a direct access to the addin interface. For this tutorial we’ll save these changes to the .uic file that we just created. If you followed all steps correctly, at the Active Customization File there will be the option 3D Macro Tools. Right click on the middle portion of the window and pick New > Button. The new button will the shown on this middle area and its properties on the right panel. Change the Name property to .DrawTransition, the Caption property to Draw Transition v1.0 and the tooltip to Create rectangular to circular transitions. Click on the Command property and three dots will be visible (Picture 6).

Picture 6 – Creating the new button

Click on the dot button and choose Core on the next window. If the addin was correctly set up, a 3D Macro item will be available. Click on the little plus sign, choose the 3dMacro.Free.DrawTransition.Show option and click OK (Picture 7).

Picture 7 – Picking the button’s command

To the Icon property select the picture which will show in the button and in the menu. Now that the button is created, we need to create the menu and the command bar to use it.

Creating the menu and the command bar Right click the Menubar item and pick New Menu. A new menu called Menu1 is created right below this item. Click it to show its properties on the right side. Change the Name to 3dMacroMainMenu and the Caption to 3D Macro. Right click the Command Bars item and pic New CommandBar. A new bar is created right below this item. Click it to show its properties on the right side. Change the Name to 3dMacroMainToolbar and the Caption to 3D Macro Tools. Now we’ll link the button to the menu and to the command bar. Drag the .DrawTransition button to the 3dMacroMainMenu. Repeat this operation but now drag it to th 3dMacroMainToolbar.

Picture 8 – Linking the button to the menu and to the command bar

Click OK to go back to PDMS. If you followed all steps above, it will be possible to see a new command bar and the new 3D Macro menu. The bar will appear anywhere around your already existing bars, so you’ll have to look for it.

Picture 9 – New menu and command bar

Observe that we created only on button and it was used to the bar as well to the menu. In other words, it’s not necessary to create multiple buttons if they do the same thing. Now you can access the addin either through the menu or through the command bar. If you need help to use this new tool, click on Help… inside the addin window.

Conclusion In this article we could see the new system to addin access and user interface customization. The creation of new menus is not tied to the use of new addins. You can also run your old PML macros, because as you can see on the window from Picture 7 there’s a Macro option where you can call the macro you want to execute for the new item. Up to today there was always the need to know PML 1 or 2 to create new menus. On this new version Aveva made this process a lot more user friendly and open

to nearly all users, not only administrators. And the best part: can be done in a user basis, without change the company’s customizations. And don’t forget: you can use the set up made here to install any addin from now on. You only have to copy the .dll addin file into the …\pml.net\addins\dll and change the .xml file of the module you want the addin to be used from.

Setting up .NET to run addins from network ments(0)

Introduction In case you can’t run PDMS 12addins through your local network, chances are that you need to change the .NET security configuration. .NET introduced a new set of permissions called Code Access Security (CAS). With CAS it doesn’t matter that the user is allowed to do an operation, the application itself must be allowed too. To exemplify let’s say you have full access to modify the Windows registry and you will run an application that changes the registry. Usually that would be ok, but how much you can trust this application? What if there are malicious code? It’s here that the .NET comes in. That’s why it’s common to find applications that run perfectly on your PC, but when you try to run them over your local network they don’t work anymore. This new security system works with zones, and each one has different access restrictions. Your PC and your network are two different zones and because this they have different permission levels. On .NET 1 and 2 the CAS works, in a very simplified way, as described above. But in .NET 3.5 SP1 it’s not necessary to change the security levels anymore. So, if I compile my code targeting Framework 3.5 SP1 is it all solved? Unfortunately it’s not how it works. Your addin will use Aveva’s DLLs, which I suppose, may be compiled with version 2.0 and even 1.1 of .NET Framework. I say that because even if I change my code to target Framework 3.5 SP1 I still get the security error eventually. Then the only way out is the good old key combination: Ctrl + Alt + Del. Luckily there’s a solution: change the trust level of your network zone to Full Trust. The disadvantage is that you must do this to every client PC which will run PDMS 12 addins through network and you must have administration privileges. But the configuration itself is very simple and takes only a few seconds. Remember that you must setup both 1.1 and 2.0 versions of .NET Framework. If you setup only one of them you will end up getting the security errors. In the 2.0 version there are two ways of doing this, feel free to pick the one you feel more comfortable with.

Setting up CAS on .NET 1.1 through Control Panel Control Panel click on Administrative Tools and select Microsoft .NET Framework 1.1 Configuration. Select My Computer > Runtime Security Policy > Machine > Code Groups > All_Code. On

Setting up CAS on .NET 2.0 through Control Panel A problem rises on version 2.0: the utility to setup this version only comes with the SDK version of .NET 2.0 Framework. So, if your machine has the utility you’ll see it on Control Panel together with the 1.1 one. If you don’t have it, don’t panic, you can setup this through DOS command line.

Setting up CAS on .NET 1.1 through DOS command line Click Start, Run. Type CMD and then click OK. Type the following commands: C: CD C:WINDOWSMicrosoft.NETFrameworkv2.0.50727 CASPOL -machine -chggroup LocalIntranet_Zone FullTrust Done. Now your computer is ready to run any PDMS DLL from your local network.

Conclusion Despite the fact that .NET 3.5sp1 doesn’t need to configure the security levels to run code from network, some PDMS DLLs may be compiled with older versions of .NET, and because of this when you run your addin you end up getting security errors. To solve this it’s necessary to classify your local intranet to a level of full trust to any code which runs from network. That configuration must be done to each computer but this way you can put all your addins in a central repository in you network and then when you need to add more addins or update old ones, you do it in one place only. For more information on PDMS 12 addins and how to install and configure one, see How to install and configure a PDMS 12 addin.

Setting up your PMLLIB y rbasniak / In PML II, PML Language / Comments(4)

Introduction I’ve seen that many people still get confused when setting up the PMLLIB to add customizations to PDMS. PML II files can have one of these 3 extensions: 

PMLFRM: for graphical interfaces (forms)



PMLFNC: for functions that doesn’t have a graphical interface



PMLOBJ: for new objects (classes) created by the user Theses files must be in some special place so PDMS can see them, and this place is the PMLLIB.

What is the PMLLIB? Is a folder or a set of folders where PDMS will look for PML II files when it needs it.

How does the PMLLIB work? When you try to run a PML II file PDMS will look for it in one of the PMLLIB folders. For instance, if you type show !!genprimitives in the command window, PDMS needs to find a file called genprimitives.pmlfrm somewhere in the PMLLIB.

To discover which folders following command in PDMS:

are

set

in

your

PMLLIB

you

have

to

type

the

Q EVAR PMLLIB

If you have more than one folder in your PMLLIB, PDMS will first look for the file in the first folder in the PMLLIB. If it does not find it there, it’ll try the second one and so on, until ir finds it or the folders in PMLLIB end. Inside each of the PMLLIB folder there’s one file called pml.index. This file is a list of all files in that folder, so PDMS doesn’t actually look for the file in the folders, but in this index file. If the file is in the folder but not listed in the pml.index, then it doesn not exist to PDMS. Because of this, each time you add a new file to the PMLLIB you hate to type the following command in PDMS:

PML REHASH ALL

This command should update all pml.index files in your PMLLIB. But what really happens is that in some situations it does not do it and PDMS can’t find the new files. In these situations what you have to do is erase the pml.index file from that particular PMLLIB and only then use the rehash command in PDMS. When you do this PDMS will not find the index file and will have to recreate it.

How to add a new path to the PMLLIB This is done editing the .bat file used to start PDMS. There can be some variations on these steps since almost no one uses the original PDMS bat files. In this example we’ll assume the original PDMS bat files. PMLLIB is set up in the evars.bat file, that is located in the same folder where PDMS is installed. You should look for the following line in the file:

set pmllib=%pdmsexe%pmllib\

Now change it, addin a new path at the end of this line:

set pmllib=%pdmsexe%pmllib\ C:\MyPMLLIB\

You’re done. Now PDMS will look for PM II files in its installed folder and in the folder MyPMLLIB. Don’t forget to use the rehash command each time you add a new file to one of the PMLLIB folder and erase the pml.index files if needed.

Setting up .NET to run addins from network mments(0)

Introduction In case you can’t run PDMS 12addins through your local network, chances are that you need to change the .NET security configuration. .NET introduced a new set of permissions called Code Access Security (CAS). With CAS it doesn’t matter that the user is allowed to do an operation, the application itself must be allowed too. To exemplify let’s say you have full access to modify the Windows registry and you will run an application that changes the registry. Usually that would be ok, but how much you can trust this application? What if there are malicious code? It’s here that the .NET comes in. That’s why it’s common to find applications that run perfectly on your PC, but when you try to run them over your local network they don’t work anymore. This new security system works with zones, and each one has different access restrictions. Your PC and your network are two different zones and because this they have different permission levels. On .NET 1 and 2 the CAS works, in a very simplified way, as described above. But in .NET 3.5 SP1 it’s not necessary to change the security levels anymore. So, if I compile my code targeting Framework 3.5 SP1 is it all solved? Unfortunately it’s not how it works. Your addin will use Aveva’s DLLs, which I suppose, may be compiled with version 2.0 and even 1.1 of .NET Framework. I say that because even if I change my code to target Framework 3.5 SP1 I still get the security error eventually. Then the only way out is the good old key combination: Ctrl + Alt + Del.

Luckily there’s a solution: change the trust level of your network zone to Full Trust. The disadvantage is that you must do this to every client PC which will run PDMS 12 addins through network and you must have administration privileges. But the configuration itself is very simple and takes only a few seconds. Remember that you must setup both 1.1 and 2.0 versions of .NET Framework. If you setup only one of them you will end up getting the security errors. In the 2.0 version there are two ways of doing this, feel free to pick the one you feel more comfortable with.

Setting up CAS on .NET 1.1 through Control Panel Control Panel click on Administrative Tools and select Microsoft .NET Framework 1.1 Configuration. Select My Computer > Runtime Security Policy > Machine > Code Groups > All_Code. On

Setting up CAS on .NET 2.0 through Control Panel A problem rises on version 2.0: the utility to setup this version only comes with the SDK version of .NET 2.0 Framework. So, if your machine has the utility you’ll see it on Control Panel together with the 1.1 one. If you don’t have it, don’t panic, you can setup this through DOS command line.

Setting up CAS on .NET 1.1 through DOS command line Click Start, Run. Type CMD and then click OK. Type the following commands: C: CD C:WINDOWSMicrosoft.NETFrameworkv2.0.50727 CASPOL -machine -chggroup LocalIntranet_Zone FullTrust Done. Now your computer is ready to run any PDMS DLL from your local network.

Conclusion

Despite the fact that .NET 3.5sp1 doesn’t need to configure the security levels to run code from network, some PDMS DLLs may be compiled with older versions of .NET, and because of this when you run your addin you end up getting security errors. To solve this it’s necessary to classify your local intranet to a level of full trust to any code which runs from network. That configuration must be done to each computer but this way you can put all your addins in a central repository in you network and then when you need to add more addins or update old ones, you do it in one place only. For more information on PDMS 12 addins and how to install and configure one, see How to install and configure a PDMS 12 addin.

Requirements for developing with PDMS

Introduction In the how to create Before

last posts we saw how to setup PDMS to run addins created with .NET and allow all users to access them through menus and toolbars. Now we will an addin from scratch, including all source code. we start coding we need to check if our system meets the requirements.

System requirements I think I don’t have to tell you that the first item is PDMS. You don’t actually need PDMS to develop the addin, but if you need to test it, then

you’ll need PDMS. You can only develop addins for PDMS 12.x series. Everything I do in these series of tutorials will be considering PDMS 12.1 SP2. Since PML.NET is new, it’s changing a little between Service Packs and if you are using older versions of PDMS there might be some changes you’ll have to make for your own. Another requirement is a development interface and the chosen one is SharpDevelop because it´s free and have the same basic functionality as Visual Studio. You can download the 4.3 version clicking here. Your machine must have .NET 4.0 Full Runtine, which you can download here, and .NET 3.5 SP1 Runtime, which you can download here. SharpDevelop will need administrator rights for installation, but after it´s installed you can copy it to a pendrive and it will run as portable software in any machine that has the runtime installed.

Conclusion There are the basic requirements to develop for PDMS using .NET. If you have Visual Studio you can use it instead of SharpDevelop, both are very alike and you will not have any trouble in following the tutorials with any of them. The main SharpDevelop advantage, besides the price, is that you can use it as portable software. Next week I’ll be back with a new part of these series.

Creating an DLL library

Introduction Before we start coding and digging in details about PML.NET we need first to learn some basics of SharpDevelop and .NET.

Creating a C# Project

Open SharpDevelop and click File > New > Solution. In the ‘New Project’ window select C# in Categories, Class Library in Templates and in the Name field type TestProject. In the Location field select a folder to save your new project. In the upper right corner select .NET Framework 3.5 (only the 3.5 version, not the Cliente Profile version). This is a very important step, because the addin won’t work if you select the .NET 4.0 or newer. Your window should look like this:

Picture 1 – New Project window

We will not type any code here, because your goal today is to learn how to create and compile the Project, and the auto generated code if enough for it.

1 2 3 4 5 6 7 8

using System; using System.Collections.Generic; namespace TestProject { /// /// Description of MyClass ///

9 public class MyClass 10 { 11 12 } 13 }

Compiling your DLL Go to Build > Build Solution menu. If you followed correctly to here, you’ll see a message in the lower left corner of the window telling you the project was successfully built.

Picture 2 – Message telling you the project was successfully built

Now right click the “Test Project” in the Project panel and select “Open Output Folder”. A Windows Explorer window will be opened and you should see the DLL file we just created. By default it´s located in the bin\debug folder in the path you chose for your project.

Picture 4 – Opening the output folder

What was generated 

You should see 2 files: TestProject.dll: this is our final product and the file we need. To work on PDMS it must be copied to the folder where your addins are located. If you



don’t know where is it, type Q EVAR ‘CAF_ADDINS_PATH’ in the PDMS Command Window. If the result was a blank line you have to setup it. If you need help on this step, click here. Obviously it won´t work in PDMS, since we didn´t type any code yet, but don’t worry we’ll get there. TestProject.pdb: this file is used by .NET to help debbuging you code and you don’t have to do anything with it. When developing na addin, each time you recompile your code you have to update the old version in the CAF_ADDINS_PATH and PDMS must be closed to do it.

Conclusion This ends this week’s material. They’re very basic steps and most of you probably already know it, but since we have readers of all knowledge levels I decided to do this in bay steps so everyone can learn and keep following the examples. If you have any question, that’s why the comments session is at the end of the page. basniak / In PML Language, PML.NET / Comments(0)

Introduction We already know how to compile a DLL library and now we start digging in the steps needed to turn it in something that PDMS can understand. Every time you create a new project you’ll have to follow today’s steps. If you have any doubt on how to create a new C# project, click here. The classes we need to use when developing an addin do not exist in Windows, so we need to add their library references to our projects. These libraries are in the same folder where PDMS was installed.

Adding references to the libraries

    

Create a new C #Project, then go to Project menu, and choose Add Reference. Go to the .NET Assembly Browser tab and click the Browse button. Navigate to the folder you installed PDMS and choose these files: Aveva.ApplicationFramework.dll Aveva.ApplicationFramework.Presentation.dll Aveva.Pdms.Database.dll Aveva.Pdms.Geometry.dll Aveva.Pdms.Shared.dll

 

Aveva.Pdms.Utilities.dll PDMSFilter.dll Your Projects panel should look likes the one on Picture 1.

Picture 1 – Aveva’s libraries added to your project

You will not always use all these libraries and sometimes you may even add others, but these are the most common.

Avoiding local copies of the DLLs Now select one of the libraries and in the Properties panel change the Local Copy property to False.

Picture 2 – Changing the Local Copy property

Now that your Project is setup we can start coding, but it is something for the next week’s material.If you let this as True, every time you compile you DLL, SharpDevelop will copy them to your output folder, which is nor desirable.

Introduction I’m back with a new article related to the new .NET framework. Today’s article is more of a tutorial explaining how to install and then configure a PDMS 12 addin made in .NET. We’ll need an addin to use as example. I made a very simple addin for this purpose. This addin can be used to model trasitions from rectangular sections to circular ones for equipments. We’ll install this addin in PDMS and then configure it to expose its interface to the end user. This will be done with a menu and a commandbar. To download the addin just scroll to the end of this page, it’s totally free.

Making the addin visible to PDMS Each PDMS module is an application by itself, in other words Lexicon is an application, Paragon is another, Design is a third one and so on. When a module is loading, PDMS will load some standard addins from Aveva. The definition of which addin will be loaded is done through some .xml files located inside the PDMS executable folder. These files are named according the module associated with them, e.g. the file that defines which addins are loaded in Paragon is called ParagonAddins.xml, the one for Draft is called DraftAddins.xml and so on.

Picture 1 – Contents of DesignAddins.xml file

The file we are looking for is DesignAddins.xml, since the addin I made is supposed to be used with Design. This file has a very simple structure, as can be seen at Picture 1. For our addin to be loaded what we need is only add a new entry with the name of our addin’s .dll file. That done the only thing we shall do would be to put a copy of the .dll (DrawTransition.dll) inside this folder. However we’ll do the things a little bit different here. I’d say that edit the original PDMS files is not a good practice because you would have to replicate these changes to every PC with PDMS installed and you would have to redo the same changes after each PDMS reinstall or even update. Because of this we’ll make some changes to allow all addin setup or modification accessible to every user over the network. This can be done creating some environment variables that will point to other folders.

Modifying the setup to run over the network First we need to create the folder structure to store the addins and the interface customization files. Create the structure shown on Picture 2 somewhere on the network.

Picture 2 – Folders to store and configure addins

Here I created the folders on the drive D:, so don’t forget to change it to your directory when needed. There are many ways of setting up these environment variables. For this tutorial we’ll put them in the PDMS .bat file. Right click on the shortcut you use to open PDMS e choose Edit. Windows will find the right file and open to you. In the beginning of the file insert these two lines: Shell

1 set CAF_UIC_PATH=D:\pml.net\interface\config

2 set CAF_ADDINS_PATH=D\:pml.net\addins\config

The CAF_ADDINS_PATH variable informs PDMS where it should search for the addin to load. The CAF_UIC_PATH variable informs PDMS where it should search for saved interface customization files. Now we’re going to copy each module’s addin and interface configuration files. Unfortunately these environment variables aren’t like PMLLIB, where it’s possible to put only the modified files on the new folder and PDMS will search for the others on the installation folder. So we have to copy ALL files called Addins.xml (DesignAddins.xml, ParagonAddins.xml, SchematicsAddins.xml, etc) to the …\pml.net\addins\config folder and ALL files called Customization.xml (DesignCustomization.xml, ParagonCustomization.xml, DraftCustomization.xml, etc) to the …\pml.net\interface\config folder. Copy the DrawTransition_v????.dll file to the …\pml.net\addins\dll folder. Open the DesignAddins.xml on the Notepad and add one more line, like shown on the Picture 3, pointing the folder where you put the DrawTransition_v????.dll file. Note that you have to type exactly the same name as the dll you’re using (there’s one dll for each PDMS version), and do not type the file extension.

Picture 3 – Edited DesignAddins.xml file

Now let’s create a new .uic file to save our menus, buttons and commandbars. Open Notepad and type the following: Shell

1 2 1.0 3dMacro

Save the file as 3dMacro.uic on the …\pml.net\interface\uic folder. Se preferir pode baixar o arquivo diretamente clicando aqui. Watch out if your Windows is set up to hide file extensions. If yes it will add a .txt extension on your file’s name. It won’t appear to you but the .uic file won’t work. Now we only have to inform PDMS about this new .uic file. Open the …\pml.net\interface\config\DesignCustomization.xml file on the Notepad and change it as show on Picture 4.

Figura 4 – Edited DesignCustomization.xml file

Now the addin is installed and will be loaded in Design. Open PDMS and watch the console window for any errors (the DOS window that starts with PDMS). If you see any error or PDMS does not load, redo the previous steps to see if you haven’t missed anything. What we have to do now is expose the addin interface to the user. In PDMS 12 is possible to create menus and commandbars through the interface. We’ll create a menu and a commandbar that will allow the user to open the addin window.

Creating the command button Right click any menu or commandbar and pick Customize. The window shown in Picture 5 will appear.

Picture 5 – Window used to customize menus and commandbars

Let’s make a little break to explain this window. A) This list allows you to choose which customization file will be edited. B) In this area we can find the user defined menus and commandbars. By default these items are divided in three categories: 

per user



per project



per module C) This area stores the user defined commands which can be inserted in the commandbars and menus. D) The selected item’s properties will be shown here. Some may be read only and cannot be edited by the user. First we’ll create a command which will give the user a direct access to the addin interface. For this tutorial we’ll save these changes to the .uic file that we just created. If you followed all steps correctly, at the Active Customization File there will be the option 3D Macro Tools. Right click on the middle portion of the window and pick New > Button. The new button will the shown on this middle area and its properties on the right panel. Change the Name property to .DrawTransition, the Caption property to Draw Transition v1.0 and the tooltip to Create rectangular to circular transitions. Click on the Command property and three dots will be visible (Picture 6).

Picture 6 – Creating the new button

Click on the dot button and choose Core on the next window. If the addin was correctly set up, a 3D Macro item will be available. Click on the little plus sign, choose the 3dMacro.Free.DrawTransition.Show option and click OK (Picture 7).

Picture 7 – Picking the button’s command

To the Icon property select the picture which will show in the button and in the menu.

Now that the button is created, we need to create the menu and the command bar to use it.

Creating the menu and the command bar Right click the Menubar item and pick New Menu. A new menu called Menu1 is created right below this item. Click it to show its properties on the right side. Change the Name to 3dMacroMainMenu and the Caption to 3D Macro. Right click the Command Bars item and pic New CommandBar. A new bar is created right below this item. Click it to show its properties on the right side. Change the Name to 3dMacroMainToolbar and the Caption to 3D Macro Tools. Now we’ll link the button to the menu and to the command bar. Drag the .DrawTransition button to the 3dMacroMainMenu. Repeat this operation but now drag it to th 3dMacroMainToolbar.

Picture 8 – Linking the button to the menu and to the command bar

Click OK to go back to PDMS. If you followed all steps above, it will be possible to see a new command bar and the new 3D Macro menu. The bar will appear anywhere around your already existing bars, so you’ll have to look for it.

Picture 9 – New menu and command bar

Observe that we created only on button and it was used to the bar as well to the menu. In other words, it’s not necessary to create multiple buttons if they do the same thing.

Now you can access the addin either through the menu or through the command bar. If you need help to use this new tool, click on Help… inside the addin window.

Conclusion In this article we could see the new system to addin access and user interface customization. The creation of new menus is not tied to the use of new addins. You can also run your old PML macros, because as you can see on the window from Picture 7 there’s a Macro option where you can call the macro you want to execute for the new item. Up to today there was always the need to know PML 1 or 2 to create new menus. On this new version Aveva made this process a lot more user friendly and open to nearly all users, not only administrators. And the best part: can be done in a user basis, without change the company’s customizations. And don’t forget: you can use the set up made here to install any addin from now on. You only have to copy the .dll addin file into the …\pml.net\addins\dll and change the .xml file of the module you want the addin to be used from.

Introduction I can guess that most of you are eager for typing some come, and all I can tell if that this time finally arrived. The addin we’ll create in this 4 parts post will have only the essential code to work on PDMS and a very simple feature that will inform the current element name in PDMS. Nevertheless you’ll learn how to read PDMS attributes, which is very useful to know.

Creating the project Create a new solution in SharpDevelop called SimpleAddin. Click here if you do not know how to do this step. Add the references to the Aveva’s libraries like I explained here. On the Project panel right click the MyClass.cs file and choose rename. Type SimpleAddin.cs as the new name and open it with double click.

Picture 1 – Renaming the class file

Coding Create some using statements for the libraries you added as reference:

Change the class namespace to _3dMacro.Pdms.Addins.Tutorials.SimpleAddin

Change the class name to SimpleAddin and implement the IAddin interface for it.

Inside the SimpleAddin class create a property called Description, which will return the addin’s description when asked.

public string Description 1 { 2 get { return "3D Macro | PML.NET Tutorial 1: Building a very simple addin | ®3D Macro 3 2013"; } 4 }

Still in the SimpleAddin class create a property called Name that will return the addin name. This name must be unique and you can’t have two addins with the same name running in PDMS.

Now create a method called Start which will be called when PDMS loads the addin. When the user clicks on the button or menu that you’ll create in PDMS for this addin, what will be called is the command associated with this addin. The class responsible for managing these commands is called CommandManager, so the Start method must do this: 

Create a variable that poinst to CommandManager class



Create the commands you want to be accessible by the user



Inform CommandManger that these commands exist

5 6 7

public void Start(ServiceManager sm) { CommandManager cm = (CommandManager)sm.GetService(typeof(CommandManager)); Command c = new GetCurrentElementName(); cm.Commands.Add(c); }

To finish the class, create a method called Stop. This method is called when PDMS stops the addin, for instance, when it´s closed.

This is the final version of the SimpleAddin class:

1 2 3 4 5 6 7 8 9 1 0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 1 8 1 9 2 0 2

using System; using System.Collections.Generic; using using using using using

Aveva.ApplicationFramework; Aveva.ApplicationFramework.Presentation; Aveva.Pdms.Shared; Aveva.Pdms.Database; Aveva.Pdms.Geometry;

namespace _3dMacro.Pdms.Addins.Tutorials.SimpleAddin { /// /// Main class for my first addin /// public class SimpleAddin : IAddin { /// /// Description that will be shown to the user /// public string Description { get { return "3D Macro | PML.NET Tutorial 1: Building a very simple addin | ®3D Macro 2013"; } } /// /// Name of the addin /// public string Name { get { return "3dMacroSimpleAddin"; } }

1 2 /// 2 /// Run once per PDMS section, when the addin is loaded 2 /// 3 /// ServiceManager object. PDMS will take care of it 2 public void Start(ServiceManager sm) 4 { 2 #region Addin commands declaration area 5 2 CommandManager cm = 6 (CommandManager)sm.GetService(typeof(CommandManager)); 2 7 Command c = new GetCurrentElementName(); 2 cm.Commands.Add(c); 8 2 #endregion 9 } 3 0 /// 3 /// Run once per PDMS section, when PDMS is closed or module is changed 1 /// 3 public void Stop() 2 { 3 3 } 3 } 4 3 5 3 6 3 7 3 8 3 9 4 0 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 5 0 5 1

5 2 5 3 5 4 5 5 5 6 5 7

Final words In the Start method the command is being created from a class called GetCurrentElementName. This class does not exist yet and will be responsible for reading the current element name and then sending a message to the user. Since this class is not created yet you can’t compile today’s example. Next week we’ll finish it and then you’ll be able to compile the addin and run it in PDMS. Save your project because next week we’ll start from this point. y rbasniak / In PML Language, PML.NET / Comments(0)

Introduction Last week we started a new addin from scratch. We created the class responsible for exposing the commands the user will be able to call. Today we’re going to create the last class we need so this addin can be compiled and used. It’s this class that will do the real work, which in our example, is show a message to the user with the current element name.

Inserting a new class into your project Open the SimpleAddin.sln project we created in part 1. Create a new empty file that will be the GetCurrentElementName class, go to File menu, New > File. In the New File dialog select C# under Categories and Empty File under Templates.

In the File Name field type GetCurrentElementName.cs and click Create.

Coding Add the using statements to Aveva’s namespaces. C#

1 2 3 4 5

using using using using using

Aveva.ApplicationFramework; Aveva.ApplicationFramework.Presentation; Aveva.Pdms.Shared; Aveva.Pdms.Database; Aveva.Pdms.Geometry;

Define the namespace and create a class called GetCurrentElementName that inherits from the Command class. C#

1 namespace _3dMacro.Pdms.Addins.Tutorials.SimpleAddin

C#

1 public class GetCurrentElementName : Command 2{ 3}

Inside this class create the constructor method, which must have the same name of the class. Tell PDMS how the user will be able to call this class from PDMS. This is done through the Key property. This value must be unique inside PDMS. C#

1 public GetCurrentElementName() 2{ 3 this.Key = "3dMacro.Tutorial.SimpleAddin.GetCurrentElementName"; 4}

Create the Execute method, which will be run when the command defined in the Key property is called. This method must read the name attribute from the current element in PDMS and then send a message to the user with the name. C#

public override void Execute() 1 { 2 string name = CurrentElement.Element.GetAsString(DbAttributeInstance.NAME); 3 4 System.Windows.Forms.MessageBox.Show("The current selected element name is: " + 5 name); 6 }

The message will be sent by the MessageBox class. This class is stored in the System.Windows.Forms library, so you have to add a reference to this library. Click the Project menu and choose Add Reference. In the dialog that will open select the assembly System.Windows.Forms (version 2.0.0) and click OK. This is the final version of the GetCurrentElementName class:

1 2 3 4 5 6 7 8 9 1 0 1 1

using System; using System.Collections.Generic; using using using using using

Aveva.ApplicationFramework; Aveva.ApplicationFramework.Presentation; Aveva.Pdms.Shared; Aveva.Pdms.Database; Aveva.Pdms.Geometry;

namespace _3dMacro.Pdms.Addins.Tutorials.SimpleAddin { public class GetCurrentElementName : Command {

1 2 1 3 1 4 1 5 public GetCurrentElementName() 1 { 6 this.Key = "3dMacro.Tutorial.SimpleAddin.GetCurrentElementName"; 1 } 7 1 public override void Execute() 8 { 1 string name = 9 CurrentElement.Element.GetAsString(DbAttributeInstance.NAME); 2 0 System.Windows.Forms.MessageBox.Show("The current selected element 2 name is: " + name); 1 } 2 } 2 } 2 3 2 4 2 5 2 6

Testing your addin Now that your addin is finished you can compile it. If you need any help on this step see this post. If you didn’t get any error messages it’s done. Now you have to load it in PDMS and then expose it to the user through a button or menu item. We already saw how to do it here. When you’re going to choose the command to your button, there should be the command GetCurrentElementName under the namespace 3dMacro.Tutorial.SimpleAddin. Now select any element and click the button you just created. The addin will show you a message with the element’s name.

Conclusion

Like I said in part 1 this addin is very simple in functionality, because this series’ goal is to show you the basic code to create a PDMS addin. You can download the compiled addin at the end of this page, but remember, this will only work in PDMS 12.1 SP2. If you’re using other PDMS version you’ll have to download the source code, change Aveva’s libraries references to your PDMS version and then compile it. If you’re having trouble to compile the source code, don’t worry in the following weeks I’ll make a post about how to compile source code downloaded from this site.

Introduction This is the last part of a 3 part series. You can check part 1 here and part 2 here. In this last part I’ll explain to you how and what happens when our addin is loaded in PDMS. I think it’s a very important thing to know if you plan to develop your own addins and even to help you track what’s wrong if your addins aren’t being loaded by PDMS.

How an addin is loaded and run

 

 

The image above tries to show how the addin we developed is loaded by PDMS. The events that happens are listed below: User opens PDMS in the Design module PDMS looks for an environment variable called CAF_ADDINS_PATH. If it exists it tries do read the DesignAddins.xml, otherwise it will use the file that is in the installation folder This file contains an entry with a DLL filename and path of each addin that should be loaded. It’s this way that PDMS knows where our addin file is PDMS loads the DLL and search for a method called Start

 

    

PDMS runs the Start method, which points to a Command class PDMS reads the Command class, which tells PDMS that there is a new command available to the users. This is done through the Key property. Now the addin is loaded and can be used by any user. The user should have a button or menu do call the addin. The events that happens when it happens is described below: User clicks the button (which was created pointing to the same value as our Key property in the class) PDMS searches in its stored commands to see to which class that command belongs to PDMS finds that the command is from our GetCurrentElementName class PDMS runs the Execute method from that class Addin do its job Now let us understand the Execute method, which is where the addin does what he is supposed to do. The CurrentElement class stores all information about the currently selected element in PDMS (CE). From it we get an instance of the CE through the Element property. To finish we call the method GetAsString, which reads an attribute value and convert it to a string. This method takes as parameter the name of the attribute we want to read. Whenever you need a reference to an attribute you can use the DbAttributeInstance. It contains references to nearly all PDMS attributes. In our example, we used the NAME attribute. To finish we send a message to the user with the value we read from the attribute. Agora vamos entender o código do método Execute, que é onde o addin realmente faz o que se propõe.

Conclusion This is the end of this series. I hope you enjoyed and learned a little bit about PDMS development. In the future, I will get deeper in how to read the many types of PDMS attributes. I also plan to make another series expanding this addin, adding a graphical interface to it. Keep reading and visiting me every week.