authorit word publishing template · 2020. 8. 6. · powermill plugin training introduction ......

PowerMILL Plugin Training Introduction

1 Copyright @ Delcam.PLC

Why use a Plugin? There are many procedures on offer to automate tasks within PowerMILL including

Macros, the Custom Software Core and Plugins each with strengths and

weaknesses.

Macros are easy and quick to write and allow a number of tasks to be carried out

quickly, however they offer limited flexibility, have to be called and can only have

limited user interfaces.

Custom Software Core is a set of assemblies that can be requested from Delcam and

contain methods for issuing a number of commands to PowerMILL, they offer good

flexibility, the ability to open instances of PowerMILL and PowerSHAPE and transfer

files between the 2 and the ability to create user interfaces to issue commands.

However these programs have to be called externally from PowerMILL, respond to

user actions within PowerMILL and can’t be easily associated with a particular

instance of PowerMILL if multiple instances are open.

Contact your sales partner about getting access to Custom Software Core.

Plugins offer the most options for interaction with PowerMILL, offering the ability to

respond to user actions within PowerMILL, parent the programme within a particular

instance of PowerMILL as well as issuing commands. However they can be difficult

to write, requiring knowledge of the available interactions with PowerMILL and can

cause PowerMILL to crash if the Plugin is not correctly written.

These options are not mutually exclusive and can be used in conjunction with the

others, for example a Plugin can use the assemblies of the Custom Software Core

and can be used to call a macro within PowerMILL if desired.

Requirements Before this course is undertaken there are a series of criteria that must be met

Programming Ability This training manual assumes a good understanding of C# programming and all

instructions are written for C# .NET. It is possible to write Plugins in other .NET

languages however C# provides the most flexible and professional solutions.

It also allows Delcam to provide a greater level of support to people developing

Plugins through the online forum.

Introduction


Copyright @ Delcam.PLC 2

Software Requirements To create Plugins for PowerMILL you will require a suite of development tools such

as Visual Studio. For individual automation processes Visual Studio express will be

capable of providing all the resources required to create the assembly files required

to create a fully functional PowerMILL Plugin.

PowerMILL Version Plugin functionality is included with all versions of PowerMILL since PowerMILL 2012

R2 and is included as standard functionality within PowerMILL requiring no

additional modules.

Locations of Useful Resources There is additional information about creating Plugins included with every Install of PowerMILL, this information can be found in Program Files Delcam PowerMILL

file plugins.

Here you’ll find 4 folders

Documentation this contains a series of reference and instruction documents

designed to assist you with writing a PowerMILL plugin in either C# or VB .NET

languages although more support is available for C#. The documentation also

describes the process required to create the PowerMILL.dll file that will be used

in the exercises in this manual.

Framework this contains the framework for simplifying the communication with

PowerMILL and will be used throughout this document, it is recommended that

this project is copied and included in the resource folder of any plugin created.

Do not edit the framework, even if it is copied into a separate folder as this may

cause issues when running the Plugin in PowerMILL.

Installers this folder contains installers for some existing solutions including the

text creator as well as the surrogate installers that will allow debugging of the

Plugin while it is open in the PowerMILL window.

Solutions this folder contains some example plugins used in the notes in

documentation and the text creator plugin in an editable form to allow you to

view an example of implemented code.



The Plugin Manager The Plugin manager allows the user a range of controls over the Plugins that have

been registered with PowerMILL.

The Plugin Manager can be opened any time PowerMILL is running from the Tools

menu and selecting Plugins.

This form has several sections to it:

1 The name and status of each of the Plugins that have been registered with

PowerMILL.

The status icon to the left of the name indicates whether or not the Plugin is

enabled or disabled, the green circle indicates the plugin is enabled while the red

circle indicates that it is disabled.

Additional icons indicating that the Plugin is corrupt or incompatible with the

current version of PowerMILL are also options.

2 Information about the plugin such as it’s name, description, location, author and

Global Unique Identifier (GUID).

3 Options to enable or disable the Plugins.

Disabling Plugins could potentially improve PowerMILL’s performance or

remove unnecessary items from the user interface, depending on the

Plugins functionality, without removing the Plugin entirely.

4 Access to any existing options menu. This will call the Options form, designed

with the Plugin solution, allowing changes to be made to the operation of the

Plugin without increasing the Plugin’s presence in the user interface.



It is up to the user to provide a method to maintain the options between

separate PowerMILL instances if this is desired.

Below the enable/disable/options is information about the operation of the plugins.

5 If the surrogate is installed (described later under Debugging in PowerMILL) there

is a checkbox offering the facility to use the surrogate.

6 A warning message to inform the user that the surrogate host is running.

7 The Plugin log file, this contains information about when the Plugins were loaded

and what events they are subscribed to in PowerMILL, the Plugin manager also

provides users with the ability to clear this file for convenience.

The PowerMILL Type Library To access the functionality of PowerMILL the Plugin will require a reference to the

PowerMILL type library and this must be created from the pmill.exe using the Microsoft SDK tool tlbimp.exe.



For convenience the most recent Type library has been included in the PowerMILL

Plugin Training Resources directory and this stage can be skipped. However

modifications are made to the PowerMILL Type library between releases and any

plugins should be written using the most recent type library to ensure access to the

most up to date COM functionality of PowerMILL.

1 Locate the directories containing the pmill.exe file and the tlbimp.exe.

This will take the form of C:\Program Files\Delcam\PowerMILL 19.0.10\sys\exec64

and C:\Program Files (x86)\Microsoft SDKs\Windows\v8.1A\bin\NETFX 4.5.1 Tools\x64

respectively

2 Open a new Command prompt and change the working directory to the directory containing pmill.exe.

3 Add the directory containing the TlbImp.exe to the system path using the

command line:

SET PATH=%PATH%;C:\Program Files (x86)\Microsoft SDKs\Windows\v8.1A\bin\NETFX 4.5.1 Tools\x64

4 Create a strong name file for the PowerMILL assembly by creating a Strong

Name Key File using the command line:

sn.exe -k key_pair.snk

5 Create the assembly for the PowerMILL Type Library using the command line:

tlbimp.exe pmill.exe /keyfile:key_pair.snk /asmversion:13.1.04

6 Locate the newly created PowerMILL.dll assembly.

By default the TlbImp.exe will create the PowerMILL Type in the current

directory, in this instance the PowerMILL executable folder.

7 Move the PowerMILL.dll assembly to a convenient and identifiable location to

facilitate reuse of the assembly in any developed plugin.

PowerMILL Plugin Training Framework


The framework simplifies the process of connecting a Plugin to PowerMILL and

simplifies the process required to include a User interface in the main PowerMILL

User Interface. Additionally it provides facilities and tools to gain access to a number

of other useful abilities that can be used within PowerMILL to add options to the

plugin, Process commands issued from within PowerMILL, have a constantly visible

pane in the main PowerMILL user interface allowing quick access to the abilities of

the Plugin.

The framework is found with the other plugin resources in the location described in

the Location of Useful Resources section.

This framework provides base classes that implement the required interfaces, and

tools to manage events, panes, translation, and other common tasks.

The framework builds into a self-contained strong named assembly you can include

as a reference to the plugin project. The framework is also available as a Visual

Studio Project, which can be included in the Visual Studio Solution.

This document will demonstrate how to include the framework in your Plugin

Solution.

Exercise To demonstrate the functionality and implementation of the Framework this exercise

will describe the process used to start a new Plugin using the Framework.

1 Open Visual Studio and begin a new project. Expand the Templates menu from

the Installed menu. Expand Visual C# and select Windows or Windows Desktop.

From the available options select Class Library. Name it

“UsingthePluginFramework” and save it to the PluginTraining directory on the C

drive. Creating the directory if necessary.

Ensure the file is saved to a suitable location. Moving the created files and

folders later may cause serious problems!

Framework



2 Copy the Framework40 folder from the PowerMILL Plugin Training Resources

directory, supplied with the training notes, and create a new copy in

C:\PluginTraining\UsingthePluginFramework.

If the Framework version from the PowerMILL Program files is used then a

reference to the PowerMILL Type library will have to be added. However

the version of the framework included in the PowerMILL Plugin

Training resources already contains the required reference.

3 Right click on the solution name in the Solution Explorer in Visual Studio and select Add Existing Project. Use the file explorer to navigate to

C:\PluginTraining\UsingthePluginFramework\PluginFramework40 and select the

PluginFramework.csproj to load in. This will add PluginFramework to the Solution

Explorer.

4 Add a reference to the PluginFramework project from the Assembly tab in the

Add Reference dialog. Also add references to System.xaml and

System.Windows.Forms, if these references don’t already exist.

To add a reference to a project: Expand the project tree in the Solution Explorer. Right click on the References section and select Add Reference.

The Assemblies tab contains standard .NET assemblies. The Solution tab

contains entities within the solution itself that can be referenced, such as

other projects. The COM tab contains libraries created by installed

programs that allow automation of some of their processes. The Browse

tab allows the user to locate specific assemblies that may have been

created internally.

5 Copy the assembly file PowerMILL.dll from the Resources directory into the

Debug directory of your project and add it as a reference to this project through

the Browse dialog.

6 Add PluginFramework as an assembly reference to the UsingthePluginFramework

class, then add the namespaces

using PowerMILL;

using Delcam.Plugins.Framework;

to the start of the program.

7 Add a parent class to Class1 by adding “:PluginFrameworkWithPanes” to the line

with the class definition on it.



8 Right click on the word PluginFrameworkWithPanes and select Implement Abstract

Class this will add code to your Class1 that will allow you to supply information

about the Plugin to PowerMILL.

Implementing the abstract code adds a set of methods and properties to Class1

allowing you to issue information about the Plugin to PowerMILL.



Method/Property Implementation

string PluginName Returns the name of the plugin used in the Plugin control menu. string PluginAuthor Returns the name of the Plugin’s author or company. string PluginDescription Returns a description of the Plugins functionality or intended use. string PluginIconPath Returns a path to the plugins icon so it can be used in the Plugin

menu. Version PluginVersion Returns the Plugin version number, this takes the type Version. bool PluginHasOptions Returns true if you want to include an options form with the

plugin. If this is true the virtual function void DisplayOptionsForm() should be modified with an override.

Version PowerMILLVersion Returns the PowerMILL version number the plugin was developed using. The Plugin will work with subsequent versions, however it will not work with earlier versions to avoid trying to use features that don’t exist in the earlier version.

string PluginAssemblyName Returns the name of the Plugin’s assembly file. Guid PluginGUID Returns the plugin’s GUID. void register_panes() Method called to register panes with the parent class.

9 Right click on the UsingthePluginFramework namespace in the Solution Explorer

and select Add New Folder. Name the new folder “Images”.

10 In the resources directory locate the Images folder and drag the png file

plugin_icon.png into the Images folder in the Solution Explorer so that it is added

to the solution.

Any image used as an icon for a PowerMILL Plugin should be 32 by 32 pixels.

11 Edit the return values so PowerMILL will receive the following information:

Plugin Name: “Implementing the Base Classes”

Plugin Author: “{Your Initials}”

Plugin Description: “Plugin to demonstrate the use of the base classes within the

Plugin Framework to supply information to PowerMILL”

Plugin Version: Version 1.0.0

PowerMILL Version: 16.0.9

Plugin Assembly Name: UsingthePluginFramework.dll



PluginIconPath: “Images/plugin_icon.png”

The code to do this is included on the page 7.

The finished Visual Studio Project is saved in the Chapter1end directory in the

PowerMILL Plugin Training Resources directory.

namespace UsingthePluginFramework { public class Class1 :PluginFrameworkWithPanes { protected override void register_panes() { throw new NotImplementedException(); } public override string PluginName { get { return "Implementing the Base Classes"; } } public override string PluginAuthor { get { return "Your Initials"; } } public override string PluginDescription { get { return "Plugin to demonstrate the use of the base classes within the Plugin Framework to supply information to PowerMILL"; } } public override string PluginIconPath { get { throw new NotImplementedException(); } } public override Version PluginVersion { get { return new Version(1,0,0); } } public override Version PowerMILLVersion { get { return new Version(16,0,18); } } public override bool PluginHasOptions { get { throw new NotImplementedException(); } } public override string PluginAssemblyName { get { return "UsingthePluginFramework.dll"; } } public override Guid PluginGuid { get { throw new NotImplementedException(); } } }

}



Base Classes When you started typing PluginFrameworkWithPanes you probably noticed that

Visual Studio offered a list of autocomplete options to include as the base class.

There are 4 options for interacting with PowerMILL:

1 PluginFrameworkWithoutPanes: This class provides resources for creating a

Plugin that does not have a pane that can be used in the main PowerMILL

interface

2 PluginFrameworkWithPanes: This class provides resources for creating a Plugin

with a pane that is permanently docked in the Plugin window in the PowerMILL

interface.

3 PluginFrameworkWithPanesAndTabs: This class provides resources for creating a

Plugin with a pane that is permanently docked in the Plugin window in the

PowerMILL interface.

4 PluginFrameworkNoPowerMILL: This is used for testing and debugging the

Plugin.

The correct base class to use for the Plugin will depend on the design and

requirements of the plugin interface and should be decided in advance.

Each of the base classes has a common interface, IPluginCommunicationsInterface

and have a number of useful properties to make communicating with PowerMILL

possible and straight forward.

Properties Description

string Token Returns the token used when communicating with PowerMILL.

PluginServices Services Returns the interface used to communicate directly with PowerMILL.

IntPtr? ParentWindow Returns a reference to PowerMILL's main window. This is essentially a HWND. Note that it's a nullable type.

EventManager EventUtils Returns a reference to the event manager used to subscribe to events.

string PluginAssemblyName Returns the plugin's assembly name. Guid PluginGuid Returns the plugin's Global Unique Identifier. string PluginInstallPath Returns the plugins full install path. TranslationManager TranslationUtils Returns the plugin's translation manager. bool ConnectedToPowerMILL Returns true for both of the 'normal' base

classes, but false for the version of the base class that's designed for testing the plugin separately from PowerMILL.

If the plugin is not connected to PowerMILL then these properties should not be used, therefore it is important to use the ConnectedToPowerMILL bool to check the

connection before using any of the other commands.

IPluginCommunications also provides a number of methods to allow you to issue

commands to PowerMILL or request information from PowerMILL, listed in the table

below.



Method Description

void issue_command(string command) Called to issue a normal PowerMILL command, which fails if PowerMILL is busy. The function won’t return until the command has been processed or failure occurred.

void insert_command(string command) Called to issue a command by adding it to PowerMILL's command queue. The function call returns before the command is processed if the queue isn’t empty. This function fails if PowerMILL is busy unless it's in response to a plugin command.

string get_string_par(string par_name) double get_real_par(string par_name) int get_int_par(string par_name)

Functions to obtain, parse and convert parameter values into basic types. These functions work even if commands are echoed.

string get_pmill_info(string info_name) Returns a named piece of information. Available information can be obtained using string info_list = m_services.InformationList; This will be demonstrated later.

Plugin Services IPluginCommunications contains a reference to the interface class IPluginServices

which is the only interface that can be used to interface with PowerMILL, the Framework contains a series of convenience methods that use the IPluginServices to

pass user commands and information between PowerMILL and the plugin. Those

writing Plugins in VB, or wanting to avoid using the framework can use the IPluginServices to access the functionality within PowerMILL.

The methods and parameters contained in the IPluginServices interface are

accessible to the Plugin class through the Services interface.

Property/Methods Description Project Project Returns the Project interface, allowing access to all of

PowerMILL's entities and their parameters. Bool Busy Returns true if PowerMILL is busy. int DoCommand(string Token, string Command) int DoCommandEx(string Token, string Command, out object pResponse)

Called to issue a normal PowerMILL command, which fails if PowerMILL is busy. The function doesn’t return until the command is processed or failure occurs. The Ex

version returns the output from the command window, and can be safely cast to a string. Busy means PowerMILL is processing a command.

int InsertCommand(string Token, string Command)

Called to issue a command by adding it to PowerMILL's command queue. The function call returns before the command is processed if the queue isn’t empty. This function fails if PowerMILL is busy unless it's in response to a plugin command

void AppendPluginLog(string Token, string Message)

Appends a message to the plugin log, which is available on the plugin manager dialog.



void StartProgressBreak(string Token, string Message) bool UpdateProgressBreak(string Token, int PercentComplete) void EndProgressBreak(string Token)

Allow a plugin to raise, increment and lower PowerMILL's progress bar. You can supply a message when raising the progress bar, and then you can issue % updates. If the user presses the break button at any point, the return value from UpdateProgressBreak() is true and the plugin should break from its calculation.

int SubscribeToEvent(string Token, string EventName) int SubscribeToFilteredEvent( string Token, string EventName, string FilterField, string FilterValue) void UnsubscribeFromEvent( string Token, int SubscriptionID) string EventList

Allows the plugin to subscribe to events. Note the property to obtain a full list of supported events.

string RequestInformation( string InfoName) string InformationList

Allow the plugin to request information. Note the property to obtain a full list of supported information.

int CheckPAF(string ProductName, out int pStatus, out int pNumDays)

Allows a plugin to check the status of a specific PAF code.

void CommandWindowMessage( string message)

Send a message to the command window.

void QueueCommand(string Token, string Command)

Queue a command, and don't wait for it to execute. PowerMILL can be busy because it's not being asked to process the command immediately.

string GetParameterValue( string Token, string ParameterName)

Get a parameter value without needing to issue a command. This is useful because it can be called in response to an event, where PowerMILL, is by definition, busy. Consider using GetParameterValueTerse() if you're after a simple scalar value, as it will require less parsing and is less likely to break if PowerMILL changes the formatting of the output.

void AdjustPaneHeight( string Token, int PaneIndex, int Height)

Call to adjust the height of a pane.

string GetParameterValueTerse( string Token, string ParameterName)

Similar to GetParameterValue(), but can only be used for scalar values. However, it only returns the value, unlike the nonterse function, which will contain formatting characters.

string LatestEvent( string EventName, int Position)

Call to obtain the latest event of a given type. The position index indicates how recent the event was - 0 requests the latest event, 1 the previous event, etc. Only a small number of events are cached by PowerMILL, currently 15 per type.

void AdjustTabHeight( string Token, int TabIndex, int Height)

Adjust the height of the specified tab. A height of less than or equal to 0 indicates an automatic height should be used, which is the default.

void ScaleWithDPI(string Token, bool Enable)

Specify if a plugin's pane and tab windows should scale with the operating system's current dpi setting. The default is true.



Localisation The framework provides a set of tools to allow the Plugin to be translated into the

language in the location where the plugin will be used through the use of the

localisation tools. The localisation tools use simple xml files that carry information

about the original string and the translation for a particular area, an example of the

xml code with a single translatable phrase, “Preview” is shown below.

<?xml version="1.0" encoding="utf-8"?>

<languagedocument language="en-GB">

<message>

<english>Preview</english>

<translation>Preview</translation>

</message>

</languagedocument>

PowerMILL will pass across information about the language and region that is in use

to the Plugin as a 4 letter code, “en-GB” in this instance to denote that PowerMILL is

using English language in the Great Britain region. The framework will search for a

corresponding section in the xml file.

For each phrase that needs translation a <message> element will be required with

the <English> and <translation> sub children, there can only be one of each in

each <message> element.

If no exact match is found for the language and region identifiers the translation

mechanism will search for any match supporting the same language. If there is no

match for language then English will be used.

To use the translation the namespaces using Delcam.Plugins.Localisation and using

Delcam.Plugins.Utils must be added to the class and the phrase for translation must

be passed to the TranslationUtils.Translate method.

TranslationUtils.Translate("Implementing the Base Classes")

The translation mechanism allows an xml file to be created that contains all the

phrases that it was unable to translate during operation. To access this information

the shutdown_framework method can be overwritten to add a call to the method

XMLTranslationProvider.OutputUntranslatedPhrases({PluginInstallPath}, "en-GB").

The en-GB locale generates a en-GB.xml.untranslated file. If no en-GB.xml exists you

can rename this file to form the version the plugin will use. However, if en-GB.xml

already exists and contains some, but not all, of the required translations, then the

lines within the untranslated version are manually appended to the real version.

More information about Localisation is available in the documentation installed with PowerMILL, specifically Writing_a_PowerMILL_plugin_v6.pdf.

PowerMILL Plugin Training Connecting Plugin to PowerMILL


Making the Class COM visible

Modifying the Class In order to allow communication with PowerMILL you must make the class COM

visible, this will create a COM Callable Wrapper (CCW) for the class. This wrapper is

a COM object which:

is accessed by native code, that knows how to create a .NET CLR object,

marshal calls to it from native code,

manages .NET garbage collection when the COM reference count drops to zero.

To achieve this we need to add some lines to the class we created in chapter 1.

1 Add the namespace statement

using System.Runtime.InteropServices;

to the start of the class

2 Add the following attributes within the UsingThePluginFramework namespace but

before the class definition:

[Guid("6e90c6bf-ebe9-427f-bffb-e883815ea72e")]

[ClassInterface(ClassInterfaceType.None)]

[ComVisible(true)]

Connecting Plugin to PowerMILL



3 Create a new Globally Unique Identifier (GUID) using the Create GUID dialog

found in the Tools menu. Select 4. Registry Format and use the Copy button to

copy the created GUID to the clipboard and exit the menu.

4 Paste the GUID between the quotation marks, replacing the text in the line

[Guid("6e90c6bf-ebe9-427f-bffb-e883815ea72e")]

Ensure you delete the braces {} that are pasted with the new GUID.

5 Edit the implemented class code to include the new GUID. Modify the GUID

parameter PluginGuid to return the GUID value.

public override Guid PluginGuid

{

get { return new Guid("6e90c6bf-ebe9-427f-bffb-e883815ea72e "); }

}

6 Right click on the UsingthePluginFramework namespace in the solution explorer

and open the Properties menu, open the Signing tab.



7 Check the Sign the assembly checkbox and from the dropdown menu select

<New…>. On the new dialog that appears enter Delcam as the Key file name and

uncheck the Protect my key file with a password checkbox. Click OK and close the

Properties menu.

8 Build the solution using the F5 key or clicking Start in the Standard Toolbar to

create the assembly file for your project.

Visual Studio will display a message, shown below, informing the user

that it cannot run the program as this type of program must be called by

another program.

Registering your Assembly To enable PowerMILL to locate and run the plugin we must add it to the registry to

do this we must first make the class COM visible and allow it to be found using just

the GUID.

1 Open a Command Prompt, running the Command Prompt as administrator, and

change the directory to the folder where the assembly file is located.



To identify the assembly location, right click on the project name in the

Solution Explorer and select Properties. Expand the Build tab and copy the

Output Path value. Right click on the Project name again and select Open

Folder in File Explorer, use the Output Path value to complete the directory

path to the assembly.

2 Use the Command prompt to run regasm.exe on the assembly file, for Windows

32 bit use

C:\Windows\Microsoft.NET\Framework\v4.0.30319\regasm.exe UsingthePluginFramework.dll /register /codebase

For Windows 64 bit replace Framework with Framework64.

For future plugins replace UsingthePluginFramework.dll with the name of your

assembly.

If the Command Prompt responds with any errors ensure that you have signed

your assembly (see step 6 above).

To Support PowerMILL’s plugin component category a registry key needs to be

added to the Plugins unique entry on the registry (CLSID), this will indicate to

PowerMILL that the program is a Plugin and should be run by PowerMILL.

3 To add PowerMILL’s component category to the Plugins registry entry for

windows 8 use the Command prompt to enter

REG ADD “HKCR\CLSID\{6e90c6bf-ebe9-427f-bffb-e883815ea72e}\Implemented Categories\{311b0135-1826-4a8c-98de-f313289f815e}" /f

For Windows 7 and previous versions use the command prompt to enter

REG ADD “HKCR\CLSID\{6e90c6bf-ebe9-427f-bffb-e883815ea72e}\Implemented Categories\{311b0135-1826-4a8c-98de-f313289f815e}" /reg:32 /f

For 64 bit systems use /reg:64 instead of /reg:32.

Important: Replace 6e90c6bf-ebe9-427f-bffb-e883815ea72e with the GUID

created for the new Plugin.



The process to add the component category can also be completed through the

registry editor.

4 Launch regedit.exe by searching for it from the Start menu.

5 Expand the HKEY_CLASSES_ROOT section; locate and expand the CLSID entry

to reveal registered COM objects.

6 Locate the GUID for the plugin being registered and expand it to view the

contents.

7 Right click on Implemented Categories folder, and select New Key. Name the

key {311b0135-1826-4a8c-98de-f313289f815e}.

If no Implemented Categories folder exists create it by right clicking on the

folder for the plugin’s GUID and selecting New Key. Name the key Implemented Categories.

8 You can now test your Plugin has been registered correctly. Open PowerMILL

and once it has loaded, a window will appear stating that PowerMILL has found a

new Plugin.

This window should display the name of the new Plugin, in this instance

“Implementing the Base Class”. If it does not then the Plugin may be corrupt. To resolve this you can attempt to use the Clean Solution tool from the Build menu in

Visual Studio, rebuild the solution and reopen PowerMILL.

If this does not resolve the problem open the Registry Editor by typing “regedit” into

the search bar in the start menu. Expand HKEY_CLASSES_ROOT then expand CLSID

and search for the Plugin GUID. Right click on the Plugin GUID and select Delete.

Then redo steps 1 to 4.

Be very careful you only delete the entry for the Plugin!

If no window appears when you open PowerMILL then it may not be able to find the

Plugin, to resolve this find the Plugins entry in the Registry Editor and expand the

Implemented Categories and ensure that PowerMILL’s component category appears

and is exactly as it appears here:

{311b0135-1826-4a8c-98de-f313289f815e}



If there is an error in the component category right click and Rename the

component category to give it the correct component category and reopen

PowerMILL.

If there is no Implemented Category or no entry resembling PowerMILL’s

component category redo steps 3 and 4.

9 You can check all the information has been set correctly by opening the Plugin

Manager by selecting the Plugins option from the Tools menu.

Framework Utilities The Framework provides 2 utilities that will allow improved performance of the

Plugin with PowerMILL.

1 Disable Error Messages, this allows the program to run without the risk of the

operation being interrupted by any PowerMILL error messages, warnings or

dialogs. Useful for any long computations as the operator will be able to leave

the process running without worrying about warning messages preventing the

successful completion of the process.

using (DisableDialogMessages ddm = new DisableDialogMessages(m_comms))

{ //Insert code here

}

Caution must be used when working with the error messags switched off

as ignoring these may lead to a software crash so the process must be

robust.

2 Disable Graphics, this locks the graphics window, preventing any flickering as a

result of entities being created or activated and will reduce the computational

time taken as there will be no calculation for the graphics window.

using (DisableGraphics dg = new DisableGraphics(m_comms)) { //Insert code here

}

Framework Setup and Shutdown The framework provides methods that are called to setup and shutdown the

framework and these can be overridden to add functionality to the Plugin when the

Plugin is initialised or shutdown.

1 Within the class definition, but outside of any methods or parameters that exist,

type override and the space bar.



2 From the list select setup_framework and press enter. This will create the

default call for the method and allow you to use information about Plugin to

correctly initialise your Plugin.

public override void setup_framework(string token, PluginServices services, int parent_window_hwnd)

{

base.setup_framework(token, services, parent_window_hwnd);

}

3 Add a call to the code to create a message box with a greeting when the Plugin

is initialised.

MessageBox.Show("Welcome to my Plugin!");

This will open a message box when the Plugin is initialised with the greeting

message

This is not recommended though as the initialisation of PowerMILL will be paused

until the message box is closed.

To avoid this use a background worker to run the message box on a new thread.

4 Add the namespace using System.ComponentModel;

5 Create an instance of the BackgroundWorker class directly above the

setup_framework method in the class definition.

BackgroundWorker bw = new BackgroundWorker();

6 Comment out or delete the previous messagebox command and within the

setup_framework method add an IF statement to check if the BackgroundWorker

is busy.

7 If the BackgroundWorker is not busy initialise a new DoWork event handler for

the background worker called “bw_DoWork” and use the RunWorkerAsync

method to launch the new thread.

if (!bw.IsBusy)

{

bw.RunWorkerAsync();

bw.DoWork += new DoWorkEventHandler(bw_DoWork);

}

8 Click in the name of the new EventHandler and click on the icon that appears to

the lower left corner of the text to generate the method stub.



Within the EventHandler definition add the call for the MessageBox with the

greeting. The full code is included below. And the implementation is included in the Chapter1end folder in the PowerMILL Plugin Training Resources directory.

BackgroundWorker bw = new BackgroundWorker();

public override void setup_framework(string token, PluginServices services, int parent_window_hwnd)

{

base.setup_framework(token, services, parent_window_hwnd);

//MessageBox.Show("Welcome to my Plugin!");

if (!bw.IsBusy)

{

bw.RunWorkerAsync();

bw.DoWork += new DoWorkEventHandler(bw_DoWork);

}

}

private void bw_DoWork(object sender, DoWorkEventArgs e)

{

MessageBox.Show("Welcome to my Plugin!");

}

You will be able to see this message when the Plugin is launched by PowerMILL. It is

recommended that this operation is disabled after the effect has been viewed as

otherwise the message box will appear every time PowerMILL is opened.

The shutdown_framework method can be used in the same way for when the

framework is shutdown.

This example demonstrates how PowerMILL runs plugin code in the same thread as

it’s own code and care must therefore be used to ensure that PowerMILL’s operation

is not interrupted. There may also be a noticeable reduction in performance of

PowerMILL when using Plugins as PowerMILL executes the additional code in the

Plugin.

PowerMILL Plugin Training Creating a User Interface for the Plugin


The Plugin is now connected to PowerMILL and running in the PowerMILL processing

space but at the moment that is all it is doing. There is no code and no way of

accessing the code if there was any.

PowerMILL has a few ways of issuing information to Plugins and running code within

the Plugin, commands issued in the command window can be parsed to the plugin,

a pane can be created in the main PowerMILL interface which will communicate

directly with the Plugin or you can set the Plugin to listen to events within

PowerMILL and trigger events based on the events received.

Handling commands is the first solution to look at.

Command Window Commands To issue a command from PowerMILL to a Plugin enter

PLUGIN {PLUGIN GUID} COMMAND

Into the command window. PowerMILL will parse just the Command over to the

Plugin defined by the specified GUID. PowerMILL calls the method

public virtual void ProcessPluginCommand(string Command) { }

within the Plugin to handle the command. This will be demonstrated later in this

chapter after the code has been created.

1 To your class definition, below where the properties of the Plugin have been set.

Add a new override method. Type override into the class definition and Visual

Studio will populate a list of the methods available to override.

2 Select ProcessPluginCommand(string Command) from the available options and

hit return, this will enter all the information you need to use commands supplied

by PowerMILL.

Handling Commands



The framework offers a series of useful tools to facilitate the use of commands,

primarily a method that allows the command to be broken down into individual

strings while maintaining the integrity of any double quoted statements.

3 To demonstrate how this works add a reference to System.Windows.Forms and

add the following namespaces

using Delcam.Plugins.Utils;

using System.Text.RegularExpressions;

using System.Windows.Forms;

4 Add the following lines to the ProcessPluginCommand method.

List<string> tokens = CommandUtils.GetCommandTokens(Command);

while (tokens.Count>0)

{

//Get the next token and remove it from the list

string token = CommandUtils.GetStringToken(ref tokens);

//convert token to lowercase

token=token.ToLower();

switch (token)

{

case "print":

//get next token and remove it from the list

string toprint =

CommandUtils.GetDoubleQuotedStringToken(ref tokens);

//Display what has been retrieved from the list

MessageBox.Show(toprint);

break;

default:

//if command is not recognised

MessageBox.Show("Command not recognised: " + token);

break;

}

}

5 Close PowerMILL and build the solution. Relaunch PowerMILL.

6 In the command window type

PLUGIN {PLUGIN GUID} print hello world

This should result in two windows opening as shown in the images below.



7 In the command window type

PLUGIN {PLUGIN GUID} print “Hello, World!”

This command will result in a single message box appearing.

8 To see how GetDoubleQuotedStringToken works replace this method call with

GetStringToken and retry step 7, this will also result in a single message box,

however the message will have double quotes at either end. These are removed

as part of the GetDoubleQuotedStringToken method.

Creating Buttons to Issue Commands This demonstrates how to issue commands to the Plugin through the PowerMILL

Command Window however this is prone to human error as the command has to be

entered exactly and match up with a case in the code. To mitigate against this you

can create buttons that sit in a custom PowerMILL toolbar that will run specific

commands in the Command Window.

1 In the PowerMILL window select View Toolbar Custom Customise



2 From the Customise menu select the icon to add a new user toolbar.

3 Select the newly created menu from the list available and click on the icon

to open the toolbar editing options.

4 Change the name of the toolbar to make the toolbar easier to identify for

example to “Plugin Toolbar”

5 From the Type menu select Command. This will add 2 textboxes to the form,

Command and Description.

6 Enter “Plugin {PLUGIN GUID } print hello” into the Command textbox. If a string

command is not included after the Plugin GUID the command Window will

prompt for one to be entered. Ensure the Command Window is visible before

using a button to issue commands in this way.

7 Enter “Print Hello” into the Description textbox, this will form the text on the

button.



8 Click on the icon to add the new button to the toolbar. The button’s icon

can now be changed using the icon if desired.

9 If the toolbars visibility is switched on the button that was just created will be

visible in the toolbar area in PowerMILL. Test the effect by clicking the button.

Issuing Commands from Plugins As well as handling Commands issued by PowerMILL, plugins also have the ability to

issue commands to PowerMILL, for this example the code used in the previous

example will be modified to replace the previous functionality with the new

functionality.

1 In the Visual Studio project comment out or delete all the lines of code that were

used to handle the commands in the previous example.

Selecting all the text to be commented out and pressing Ctrl + K followed

by Ctrl +C will comment out all of the selected code.

2 In the ProcessPluginCommand method add the line

insert_command("FORM BLOCK");

This method is defined in PluginFrameworkWithPanes so just the command line

is required, and the definition can be accessed by right clicking in the method name and selecting Go To Definition.

This method is used to queue commands in PowerMILL and will return to the

Plugin before the command is run, using issue_command(string Command) will

force the plugin to wait until after the command has been run.

public override void ProcessPluginCommand(string Command)

{

insert_command("FORM BLOCK");

}

3 Close PowerMILL, build the solution and reopen PowerMILL.

4 Test the Plugin’s new functionality by using the button created in the last

exercise. The Block options form will appear in PowerMILL.

Learning Commands for PowerMILL The command method of controlling PowerMILL requires knowledge of the

commands available and the process for using them.



Echo Commands can be used to find out the exact commands required to carry out

a particular operation or process in PowerMILL

1 In PowerMILL select Tools Echo Commands.

2 Ensure the Command Window is displayed and use PowerMILL in the usual way.

The commands being run by PowerMILL will be displayed in the Command

Window.

3 Try renaming entities, creating toolpaths, opening forms and changing values in

PowerMILL to become familiar with the commands in PowerMILL.

Additionally a list of available commands can be printed in the command window by

entering the word “help”.

Calling Macros from Plugins Additionally to being able to use any command on the command line in PowerMILL,

plugins can also be used to call macros that have been recorded in PowerMILL or

written separately. Allowing users to edit the functionality of the plugin without any

contact with the C# code.

To achieve this use the command:

MACRO FullFilePathofMacro\MacroName.mac

Macros can also be written to accept arguments, such as a toolpath name. To issue

arguments from the plugin to a macro simply append the arguments to the line

calling the macro.

MACRO FullFilePathofMacro\MacroName.mac ‘ToolpathName’ 1.0.



Strings must be entered between single quotes while real or bool arguments can be

issued without the need for quotes.

Challenge Modify the ProcessPluginCommand method to issue commands to PowerMILL that

will create a new Ballnosed tool, with the dimensions shown below.

All dimensions are in mm.

The code to do this is included in the solution saved in the Chapter3End folder in the

PowerMILL Plugin Training Resources director.



Commands issued between PowerMILL and the Plugin is one way of operating the

plugin, however this can be slow and complicated while using buttons to issue

commands can be limiting, for example double quoted (“”) text cannot be included

in the command for a button.

Parenting Windows The simplest form or a user interface is a window that appears when called by a

command. The Plugin interface allows this window to be parented by PowerMILL.

1 In the Visual Studio project right click on the UsingthePluginFramework and

select Add New Item…

2 From the Add New Item dialog select User Control (WPF) give it the name

“InfoDisplay” and press Add.

Creating a User Interface for the Plugin



3 Replace the word “UserControl” at the beginning and end of the xaml code with

“Window”, right click and select View Code change the base class in the C# code

from “UserControl” to “Window”.

4 From the toolbox, add a rich textbox to InfoDisplay dragging it out so that it

covers the entire form. In the properties area change the name of the text box

to “DataListBox” then right click and select View Code.

5 Modify the constructor for the form to accept a string argument and set the rich

text box text to display this string.

public InfoDisplay(string info)

{

InitializeComponent();

DataListBox.AppendText(info);

Show();

}

This form will be used to view all the information that we extract from

PowerMILL.

To parent the window within PowerMILL we need to add the following method to the

class that will be used to call the form, in this instance this will be the class for the

pane created in the next exercise.

public void ShowInformation(string info) { InfoDisplay DisplayInfo = new InfoDisplay(info); //Prevent window being visible in the taskbar DisplayInfo.ShowInTaskbar = false; //Parent window WindowInteropHelper wih = new WindowInteropHelper(DisplayInfo); //Access PowerMILL window information required to Parent Window through Framework wih.Owner = new IntPtr(m_comms.ParentWindow.Value.ToInt64());

}



Panes Plugins offer the ability to install their own User Interface into PowerMILL’s main

user interface, this allows use of a range of WPF tools and controls which will be

made readily available to the end user.

1 In the Visual Studio project right click on the UsingthePluginFramework and

select Add New Item…

2 From the Dialog that appears select User Control (WPF) give it the name

“PowerMILL_Pane” and press Add.

3 In the user control designer right click anywhere in the design window and select View Code from the context menu.

4 Add the following namespaces to the code

using Delcam.Plugins.Framework;

using System.Windows.Interop;

5 Modify the method line to make the method accept an

IPluginCommunicationInterface object as an argument.

public PowerMILL_Pane(IPluginCommunicationsInterface comms)

Supplying the main class as an argument allows access to all the methods

and properties of the parent class and allows them to be used within the

new class.

6 Above this method add a line initialising an IPluginCommunicationInterface

object.

IPluginCommunicationsInterface m_comms;

7 Inside the PowerMILL_Pane method add the following line:

m_comms = comms;

8 Add the ShowInformation method, described at the end of the last section, to

the end of the C# code for the PowerMILL_Pane class.



9 Switch back to the designer tab for PowerMILL_Pane, in the xaml code add a

background to the Grid by modifying the opening grid line.

<Grid Background="WhiteSmoke">

10 Use the Toolbox to add 2 buttons to the pane, positioning is not important for

the moment, so long as they both appear on the form, modify the Button

definition lines to change the text in the buttons to “Create Event List” and

“Create Info List”.

11 Modify the button definition to create an event when the button is clicked.

<Button Content="Create Event List" HorizontalAlignment="Left"

Margin="98,90,0,0" VerticalAlignment="Top" Width="104"

Click="EventListRequest"/>

<Button Content="Create Info List" HorizontalAlignment="Left"

Margin="98,162,0,0" VerticalAlignment="Top"

Width="104" Click="InfoListRequest"/>

12 Double Click on the Create Event List button. This will add the event handler to

the code and allow you to directly enter the code that will be run when the

button is clicked.

13 Add the following code to this event handler

string event_list = m_comms.Services.EventList;

ShowInformation(event_list);

This method will create the list of events currently available with in PowerMILL

that a Plugin can listen for. This will be used later on in this manual and is a

useful function for assisting in the development of future Plugins.

14 Return to the design tab for the PowerMILL_Pane and double click on the Create

Info List and add the following code to the new event handler

string info_list = m_comms.Services.InformationList;

ShowInformation(info_list);

This method will create the list of information currently available with in

PowerMILL that a Plugin can request. This will be used later on in this manual

and is a useful function for assisting in the development of future Plugins.

The pane has now been designed and PowerMILL just needs some information about

it to display the pane.



15 In the PowerMILL Plugin Training Resources directory locate the Images folder

and drag the png file pane_icon.png into the Images folder in the Solution

Explorer so that it is added to the solution.

Any image used as an icon for a PowerMILL Plugin pane should be 24 by 24

pixels.

16 Above the register_panes method in Class1 add the following line

PowerMILL_Pane m_pane = null;

17 In Class1 modify the register_panes method to replace the current thrown

exception with the following code:

m_pane = new PowerMILL_Pane(this);

PaneDefinition panedef = new PaneDefinition

(m_pane, 370, 250, "Useful Resources", "Images/pane_icon.png");

register_pane(panedef);

This code initialises the pane and then builds an array of the information

required to display the pane within PowerMILL, this includes the User Control

that will form the pane, the height that the plugin pane requires, the minimum

width of the pane, a string containing the title that will appear at the top of the

pane and the location of the pane icon.

The pane icon is a 24 by 24 pixel bitmap image, in this instance the png file we

copied into our images folder in step 19.

The register_pane method can be called several times to add a number of

separate panes to the Vertical Plugin Window. This can be useful to keep

separate interfaces separate while maintaining a single plugin program.

18 Close PowerMILL, build the solution and reopen PowerMILL. The pane you just

created will appear in the Vertical Plugin Window. Click on the buttons to see the

lists of information be displayed in a pop out window. This can be copied to a

document and saved for future reference.

As well as demonstrating the implementation of a user interface within PowerMILL

this example has shown how any of the standard C# utilities and tools can be used

within a PowerMILL plugin to provide a wide range and variety of functionality.

An example of this code is included in the PowerMILL Plugin Training Resources

directory in the Chapter4End folder.

Tabs Tabs are similar to panes as they are designed as a User Control, however tabs appear in the Horizontal Plugin Window and occupy the whole width of the screen.

The Robot Solution uses a tab as part of the Robot interface.

The implementation of tabs is very similar to the process used for registering panes. It does require the use of PluginFrameworkWithPanesAndTabs as a parent class.

PluginFrameworkWithPanesAndTabs has PluginFrameworkWithPanes as a parent class

so the information currently entered remains unchanged.



Typing override will reveal the new method available for override, register_tabs(), a

typical implementation may take the form:

protected override void register_tabs()

{

ExamplePluginTab tab = new ExamplePluginTab();

register_tab(

new TabDefinition(

tab,

150, // Min Height

"Example tab",

"Images/tab_icon.png"

)

);

}

Due to the similarities between panes and tabs a full example of how to implement

tabs is not included in this manual.

Options Forms PowerMILL offers Plugins the opportunity to open an options form within the Plugin

Manager window potentially reducing the number of options contained in the plugin

user interface, improving functionality and improving consistency within projects. To

use this functionality the parameter PluginHasOptions must be set to return true

when the Plugin is initialised.

public override bool PluginHasOptions

{

get { return true; }

}

This will activate the options button in the Plugin manager, although if no further

action is taken clicking this button will not open an options form.



To call an options form the base class method DisplayOptionsForm must be

overridden.

The InfoDisplay window will be called in this example to demonstrate the process

without creating a new form.

1 In the code for Class1 modify the PluginHasOptions parameter to return true.

2 Below the code generated by implementing the abstract PluginWithPanes parent

class, type override and then the space key.

3 From the list that appears select DisplayOptionsForm() and press enter.

4 In the method stub that appears add the line

m_pane.ShowInformation("This is an options form");


6 Open the Plugin Manager, select the “Implementing the Base Classes” plugin and click the Options button.

If the options and settings used by the Plugin should remain consistent between

instances of PowerMILL then it is the responsibility of the Plugin author to develop a

method of transferring the information.

Saving Information with the Project The Plugin framework also provides a method to store files that the plugin uses

alongside the other project information used by PowerMILL. To use this functionality

override the method SerializePluginProjectData, this method takes 2 inputs, the

path to a location within the Project directory dedicated to information from the

specific plugin and a bool informing the Plugin that it is being saved.

The Path takes the form:

E:/International

Support/PowerMILL/Plugins/PluginTraining/ExamplePowerMILLProject/plugin_data/{

C4227733-9F28-4193-B20E-48D8D9CA049F}

Where ExamplePowerMILLProject is the name of the PowerMILL project.

PowerMILL Plugin Training Requesting Information from PowerMILL


There are a number of ways to request information from PowerMILL, the Framework

and the PowerMILL services provide methods to request information from

PowerMILL. Alternatively you can use a Project interface to view information about

the entities contained within a PowerMILL project.

Request Information Method The PowerMILL assembly contains a method to request a named piece of

information from PowerMILL. One of the functions that was added to the plugin in

the last example was to create a list of the named pieces of information that a

plugin can request from PowerMILL. It is useful to have this feature as any future

information made available to Plugins will be added to this list and therefore this list

will remain up to date.

1 Open PowerMILL and click the Create Info List Button in the Plugin pane in the

Vertical Plugin Window. This will display the list of information available.

2 Make a note of the names of the information, alternatively the text can be

copied into a Word or Notepad document.

Requesting Information from PowerMILL



3 Open the Visual Studio project and navigate to the PowerMILL_Pane.xaml

designer tab. Add a new button to the form.

4 Modify the definition line for the new button to rename it and create a new event

handler.

<Button Content="Show PowerMILL Units" HorizontalAlignment="Left"

Margin="85,162,0,0" VerticalAlignment="Top"

Width="133" Click="UnitRequest"/>

5 Double click on the new button to add the event handler to the code.

6 Add the following lines of code to the eventhandler.

string PMunits = m_comms.Services.RequestInformation("Units");

ShowInformation(PMunits);

This issues the string “Units”, which features on the list of named information, to

PowerMILL. PowerMILL then returns the current unit system as a string. More

information about the current list of named information is shown in the table.

The strings given must exactly match an entitiy on the current list of named

information.

Named Information Return Value

"Units" "mm" or "Inches". "ErrorsDisplayed" true or false depending on whether errors are displayed. "MessagesDisplayed" true or false depending on whether messages are displayed. "EditingMode" Returns the name of any editing mode that PowerMILL is in. For

example, it could return "Curve Editor". If PowerMILL is not in a mode, it returns an empty string.

"Folders" Returns a list of all folders within the explorer. "ShadingMinToolRadius" Returns the current minimum tool radius used for shading. "ShadingUndercutDraftAngle" Returns the current undercut draft angle used for shading. "Codebase" Returns the PowerMILL codebase number. "SupportsTranslation" true or false depending on whether PowerMILL supports

translation. This is only applicable for plugins developed by Delcam, because PowerMILL's translation database won't be aware of strings from 3rd parties.

"SupportsTabs" true or false depending on whether PowerMILL supports tabs. Tabs are only available from PM2013 onwards.

"SupportsEventCaching" true or false depending on whether PowerMILL supports event caching. This is only available from PM2013 onwards.



7 Close PowerMILL, build the solution and reopen PowerMILL. Note that the pane

has updated to match the changes that were made since it was registered.

8 Click on the new button to see the effect of the new process. The form created

earlier will appear with the current PowerMILL units displayed.

Exercise Modify the code from the last exercise to create a list of the folders in the

PowerMILL explorer. The code should output the information into the form created

earlier.

The code for this project is included in the PowerMILL Plugin Training Resources

directory in the Chapter5 EX1 folder.

Using the Project Interface The RequestInformation method is useful, however the application is limited and

can be complicated to implement.

An easier to implement option is to use a Project interface. The Project interface is

connected to the PowerMILL project and can be used to access information about

entities within the project.

The project interface contains collections of all the entity types that are saved in the

project file and these are available to the Plugin to be looped over.

1 Add the following namespace to the PowerMILL pane code.

using PowerMILL;

2 Add a button to the PowerMILL_Pane, with the content “Toolpath List” and

create an event handler for a click event. Double click on the button to open the

event handler.



3 Outside of the event handler code stub, but within the class definition initialise a

new Project interface with the name “PMProject” and assign it as shown below.

Project PMProject = null;

4 In the PowerMILL_Pane constructor initialise PMProject using

PMProject = m_comms.Services.Project;

This tells the Plugin to use the instance of PowerMILL that called the plugin as

the Project interface.

5 Inside the button click event handler, initialise a new Toolpaths object called

TPs1 and set it to the Toolpaths property of the PMProject interface.

Toolpaths TPs1 = PMProject.Toolpaths;

The Toolpaths object is a collection of all the toolpaths currently in the toolpath,

regardless of whether they are calculated or not. Each individual item in the

Toolpaths collection is a Toolpath object and contains the Toolpath name, ID,

root type and name parameter.

Note: Parameters can not be set in PowerMILL using these properties. The only

way to set properties is by issuing commands to PowerMILL.

6 Initialise a List<string> to store all the toolpath names and set it to a new list.

Add a foreach loop to the event handler that will cycle through tps1 and extract

all the toolpath names and add them to the list. One solution is shown below.

string TPNames = ""; //Ensure when a toolpath is activated all entities used are activated with it.

m_comms.insert_command("DEACTIVATE TOOLPATH");

foreach (Toolpath toolp in TPs1)

{

TPNames += toolp.Name + "\n";

}

If the “DEACTIVATE TOOLPATH” command is not issued to PowerMILL

then it is possible that activating a toolpath will not activate all associated

entities.

7 Send the list to the richtext box to be displayed.

ShowInformation(TPNames);


9 Open the project “WingMirrorDie_plugintraining” from the PowerMILL Plugin

Training Resources directory.

10 Click the new button to see a list of toolpaths in the current project appear.



Care is required when using Project interfaces for a number of reasons, the first is

that the order that entities appear in the collections will differ from the order they

appear in PowerMILL, so any operation will have to identify the toolpath by name

rather than by location in the solution explorer. To demonstrate this, a program was

used to rename all the toolpaths in a project based on their position in the Toolpaths

collection, the resulting order is shown below.

Additionally, if the Project interface still exists as a reference to PowerMILL when

PowerMILL is closed it will prevent PowerMILL from closing correctly and the

PowerMILL process will remain active. It is therefore important to either only include

this interface within methods and events that uninitialise the interface when they

are completed, or have set the value of the interface to null after it has been used.

The shutdown_framework method can be used to ensure the Project interface value

is set to null before PowerMILL is closed.

11 Add a public parameter to the PowerMILL_Pane that, when set will set the value

of PMProject to null (or to the value the parameter is set to).

public Project PMILLProject

{

set { PMProject = value; }

}

12 In Class1 override the shutdown_framework method with the following

public override void shutdown_framework()

{ m_pane.PMILLProject = null;

base.shutdown_framework();

}

Get Parameter Methods The project object provides a convenient method for looping over all the entities in a

project and getting access to a limited number of parameters of the toolpath. To

access more information about entities, such as the tool used by a toolpath

parameters must be used to access the information.

The Get Parameter methods included with the framework work in a similar fashion

to the request information methods. A string containing the name of the parameter

is issued to PowerMILL and PowerMILL will return the value of the Parameter that

matches the received string.

The main difference between the requested information example and these methods

is the variety of parameters and values that can be accessed. For the list of

parameters that can be used to access information open PowerMILL, from the menus open Help Parameters Reference.



To demonstrate these abilities the last exercise will be modified to return the name

of the tool used by the toolpath and the tooltype, instead of the toolpath name.

1 Create a new method in the PowerMILL_Pane code that returns a new Dictionary

with the value pairs shown below. private Dictionary<string, string> CreateToolTypeDictionary()

{ return new Dictionary<string, string>() { {"end_mill"," which is an End Mill tool"}, {"tip_radiused"," which is a Tip Radiused tool"}, {"ball_nosed"," which is a Ball Nosed tool"}, {"taper_spherical"," which is a Tapered Spherical tool"}, {"taper_tipped"," which is a Tapered Tipped tool"}, {"off_centre_tip_rad"," which is an Off Centre Tip radiused tool"}, {"tipped_disc"," which is a Tipped Disc tool"}, {"drill"," which is a Drill tool"}, {"tap"," which is a Tap tool"}, {"form"," which is a Form tool"}, {"routing"," which is a Routing tool"}, {"thread_mill"," which is a Thread Mill tool"}, {"barrel"," which is a Barrel Cutter"},

{"dovetail"," which is a Dovetail tool"}, };

}

This could be initialised in the main body of the code, using a method allows the

code to be moved elsewhere in the code, allows it to be reusable and keeps the

solution tidier.

2 Comment out the line

TPNames += toolp.Name + "\n";

3 Above the foreach loop where this line was in the code, initialise a new

Dictionary object and set it equal to the return value of the method defined

earlier.

Dictionary<string,string> ToolTypeDictionary=CreateToolTypeDictionary();

4 Inside the foreach loop, add 2 new lines requesting the tool name and tool type

parameters. string ToolName=m_comms.Services.GetParameterValueTerse(m_comms.Token, String.Format("$entity('Toolpath','{0}').Tool.Name",toolp.Name)); string ToolTypeENUM=m_comms.Services.GetParameterValueTerse(m_comms.Token, String.Format("$entity('Toolpath','{0}').Tool.Type",toolp.Name));

The tool type parameter returns an enum value, this gives a clear indication of

the type of tool used but is not ideal for displaying the information as a form.

The value should therefore be passed through the dictionary to get the

corresponding dictionary entry. In this case this has also been used to append

additional text to the string.

5 Add a new line appending the toolpath name, tool name and the corresponding

dictionary entry for the tool type onto a new line of the TPNames string.

TPNames += toolp.Name + " uses " + ToolName + ToolTypeDictionary[ToolTypeENUM] + "\n";

6 Close PowerMILL, build the solution, reopen PowerMILL and the

WingMirrorDie_plugintraining.pmproject.

7 Click the button to run the newly created code. The following window will

appear.



Parameters can also be used to set certain values, such as the system parameters

in PowerMILL.

8 In the PowerMILL Command window enter:

$PowerMILL.Options.View.Width.Explorer=500

This will resize the Explorer window to be 500 pixels wide. And should produce a

noticeable effect. These parameters can be set from within a plugin by issuing

commands through insert_command and issue_command methods.

Parameters that can be set can be identified in the Help Parameters Reference

document as the parameters not marked as read only.

PowerMILL Plugin Training Debugging in PowerMILL


When certain processes or actions occur in PowerMILL information about them can

be passed to the Plugin and can be used as triggers to run lines of code. These are

called events and are supplied to the Plugin as xml documents carrying information

about the event. The information available depends on the event.

The event list that was created earlier lists all the different events that can be

listened for, along with the pieces of information that they supply to the Plugin.

1 In PowerMILL, click the Event List button to review the list of available events,

this method of obtaining a list will remain up to date. A pdf version of the list, with improved formatting, is supplied in the PowerMILL Plugin Training Resources

directory.

The framework is supplied with a series of utilities to facilitate the use of events

in the plugin program, one of these utilities parses the xml document as it is

received by the plugin and creates a dictionary file with the key set to the string

shown in the event list and the value set to the corresponding value from the

xml file.

2 Add a new namespace to the PowerMILL_Pane C# code.

using Delcam.Plugins.Events;

3 Within the PowerMILL_Pane class, but above the constructor for the pane

initialise the string “ToolInfo” and set it’s value to be empty.

string ToolInfo = "";

4 In the constructor for the pane add the line

m_comms.EventUtils.Subscribe(new EventSubscription("EntityCreated", NewTool));

5 Click in the word NewTool and to the lower-left of the word an icon will appear

allowing you to generate the method stub for this event, click this icon and a

method stub will appear.

6 Modify the code in the new event handler to add the following lines.

ToolInfo += event_arguments["EntityType"] + "\n" + event_arguments["Name"]

+ "\n";

This extracts the entity type created by PowerMILL and the name and adds it to

a string that can be displayed.

7 Add a new button to the form with the text “Display Entities Created”, name the

button “EntitiesCreatedRequest”.

Events

PowerMILL Plugin Debugging in PowerMILL


8 Double click on the button to create the event handler and add the following

code.

ShowInformation(ToolInfo);


10 Create a few entities using different methods to populate the string with data

then click the “Display Entities Created” button to bring up the form with a list of

the entities that have been created and their entity type.

To unsubscribe from an event the EventSubscription object must be cached and

then used as shown below

EventSubscription sub = new EventSubscription("FormRaised", FormOpened);

m_comms.EventUtils.Subscribe(sub);

...

m_comms.EventUtils.Unsubscribe(sub);

Events can be filtered so that only those events involving certain values trigger the

event. To utilise this feature one of the overrides of the EventSubscription method

will be used.

1 Replace the current event subscription line with the new event subscription line

with 2 extra arguments, the key to the value to filter results by and the return

value of the event that is of interest.

m_comms.EventUtils.Subscribe(new EventSubscription

("EntityCreated", "EntityType", "Tool", NewTool));

In this instance the Plugin will only receive information when new tools are

created instead of when any entity is created.


3 Create new entities of different types and click the button to view the effect this

has had.

PowerMILL keeps a record of the last 15 events of each type that occur and Plugins

can gain access to these events through the Plugin Services Interface method

LatestEvent. This method accepts the Event Name as a string and an integer value

as arguments, an integer value of 0 will return the latest event of that type and

increasing the integer looks further back through the history of that event type.



Plugins normally run in PowerMILL’s processing space, however there is the option

to use a surrogate to run the Plugin outside of PowerMILL’s processing space to

enable debugging to occur while still allowing communication with PowerMILL using

inter-process COM marshalling.

This will reduce the performance of the plugin it is therefore important that the

surrogate is only used when developing the Plugin and switched off during normal

use of PowerMILL.

1 Open a Windows Explorer window and navigate to Program Files Delcam

PowerMILL file plugins installers surrogate.

2 Run the Installer appropriate for your system, either 64 bit or 32 bit installer.

This will depend on how the Plugin was registered and both versions of the

installer can be installed alongside each other if desired.

3 Open PowerMILL and open the Plugin manager, at the bottom left of the form there is a new checkbox marked Use Surrogate Host. Check this box and close

PowerMILL.

PowerMILL will warn you that the changes will not take effect until PowerMILL is

restarted.

Debugging in PowerMILL



4 Restart PowerMILL and switch back to the Visual Studio window.

5 Open the Debug menu and select Attach to Process…

6 From the dialog that appears select PmillPluginSurrogate.exe and Attach.

Visual Studio then enters Debug mode. Break points can be added to the code

that will pause the process and return the values of local variables to identify the

source of bugs in the code.

7 Click in the grey margin on the left hand side of the coding window, next to the

line of code

string tpnames = "";

8 In PowerMILL click the button Toolpath List in the Plugin Pane. This time no

window will appear as the code has been paused at the breakpoint we inserted

into the code.



9 Return to Visual Studio and the line next to the breakpoint will be highlighted.

The local variables list will be populated with the current variables available to

the process. To allow the process to continue press either the continue button if

debugging is not yet complete or the stop button to end the debugging session.

PowerMILL Plugin Training Creating Installers


In order to distribute the plugin it requires an installer that will allow users to

quickly create the required files, register the assembly and add the component

category.

Software Requirements The rest of the processes covered by this manual only require the express version of

Visual Studio, however, to access the installer options plugin developers will require

access to a full version of Visual Studio professional as well as the Setup and

Distribution extension found here:

https://visualstudiogallery.msdn.microsoft.com/9abe329c-9bba-44a1-be59-

0fbf6151054d

As shown throughout this manual, it is possible to create and use Plugins without

creating an installer file, so for one off plugins for individual users of PowerMILL this

section and any version of Visual Studio above Express is unnecessary.

Adding the Installer Projects The first step to being able to distribute a plugin is to add an installer project to the

Visual Studio Solution. This will remain up to date and allow any additions or

modifications made to the Plugin to be reflected in all future installations of the

Plugin.

1 Right click the solution and select Add New Project…

Creating Installers

https://visualstudiogallery.msdn.microsoft.com/9abe329c-9bba-44a1-be59-0fbf6151054d

https://visualstudiogallery.msdn.microsoft.com/9abe329c-9bba-44a1-be59-0fbf6151054d

PowerMILL Plugin Creating Installers


2 Select Setup Project from Setup and Deployment Visual Studio Installer, name

the new project “PluginInstaller” and save it to a sensible location, the default

should be within the Plugin’s folder structure.

3 In the Installer project designer tab, right click on the application folder, select Add Project Output…



4 Ensure the UsingthePluginFramework project is selected from the Project drop

down menu. Ensure that Primary Output is selected from the list and press OK.

This will add 2 items to the Application Folder, one is the Primary output from the UsingthePluginFramework project (the assembly file) the other is the

PluginFramework assembly file as the main project references the framework.

5 If any localisation tools have been used add a folder to the Application Folder

called “Localisation” add any xml files created for translation to this location.



6 From the solution explorer select the PluginInstaller project and use the

Properties Window (if it is not displayed open it from the View menu) to set the

Manufacturer, Product Name and Version values as these will be used by the

Installer path.

The location that the file will be created can also be modified by looking at the Property Window for the Application Folder and modifying the DefaultLocation value.



Adding Prerequisites and the Launch Conditions

To ensure that the plugin will run correctly on the target machine the plugin must

check that a compatible version of the .NET framework is installed. By default a

prerequisite is added to the project for the most recent version of the .NET

framework installed on the computer used for development. However, this may not

be necessary as an older version of the .NET framework may provide all the

functionality required by the Plugin.

7 Right click on the PluginInstaller project in the Solution Explorer, select

Properties.

This offers different options to those available in the Properties Window

used in earlier in the instructions.

8 Click the Prerequisites… button and from the list select the version of the .NET

Framework required from the list and press OK.



9 From the Properties Page click Configuration Manager… and ensure that the

check box to Build the PluginInstaller is checked.

10 Build the solution to create the Launch Conditions.

11

Conditions.

12 Right click on the .NET Framework launch condition select Properties and ensure

the Version value is correct.



Registering the Assembly Once the assembly has been created on the target computer it has to be registered

with the COM category.

As the process for this is the same for each Plugin, with a different GUID for each,

an InstallerClass has been created and included in the PowerMILL Plugin Training

Resources directory. Before this is added to the solution Custom Actions will be

added to the PluginInstaller that will instruct the setup process to call the additional

code.

13 Right click the PluginInstaller project select View Custom Actions

14 Right click on the Install option and select Add Custom Action…

15 From the new dialog double click on the Assembly Files directory, select the Primary Project Output added earlier and select OK.

This ensures that any Install instructions contained in the code created are run

by the installer.



16 Repeat the same process to add The Primary Project Output as a custom action

for the Uninstall option.

In order to register the assembly a new class has to be added to the

UsingthePluginFramework project.

17 Right click on the UsingthePluginFramework project in the Solution Explorer and select Add Existing Item…

18 Navigate to the PowerMILL Plugin Training Resources directory and select the

PluginInstallerClass.cs and PluginInstallerClass.Designer.cs and press OK to add

these files to the project.

The contents of this class can be viewed by double clicking on PluginInstallerClass.cs in the Solution Explorer. This code will register the

assembly with the COM component category.

19 In the C# code change the GUID value at the start of the InstallerClass class to

the GUID for the plugin created.

20 Rebuild the solution.

21 Open RegEdit from the Start Menu and in the file tree on the left hand side

expand HKEY_CLASSES_ROOT CLSID and locate the GUID of the Plugin.

22 Ensure PowerMILL is closed. Right click on the Plugin’s GUID in the Registry

Editor and select delete. Close the registry editor.

23 Locate and run the PluginInstaller.msi file created by Visual Studio. By default

this will be created within the folder structure for the Plugin program in PluginInstaller Debug (or Release depending on build type) directory.

24 Reopen the registry editor and locate the Plugin GUID as before to ensure it has

registered correctly.

25 Open PowerMILL to ensure it has been registered with the Component category.



An alternative to the Visual Studio Professional installer solution is a Nullsoft

Scriptable Install System (NSIS) file. This is a scripting language designed to

provide an install solution for a range of applications with a variety of tools available

to users.

This chapter will describe the process and tools required to install a PowerMILL

plugin.

An example NSIS installer has been included in the PowerMILL Plugin Training

Resources directory under the Installers folder. This type of file can be viewed with

a text editor such as Notepad++.

Software Requirements Additionally to a text editor (Notepad++ will be used to demonstrate features and

functionality in this chapter), the NSIS libraries will also need to be downloaded and

installed from:

http://nsis.sourceforge.net/Download

Writing the Installer Script

The code required to complete the installation is comprised of a number of sections

and the supplied example can be used as a template to create customised installers.

1 Locate the file NSISInstallerTemplate.nsi in the Installer directory in the PowerMILL

Plugin Training Resources directory and copy it to the output directory of the

Visual studio project.

2

For a basic plugin installer there are a number of parts in the code to change:

3 In the Plugin Information Section change the:

1 Outfile to the desired name of the installer executable that will be produced.

2 Name to a descriptive name of the plugin

3 InstallDir to the location where the plugin should be installed to.

The installer will ask for administrator privelages enabling the use of user

Program Files if desired.

The NSIS Installer

http://nsis.sourceforge.net/Download



The uninstaller will delete the used directory so ensure that a new folder

is created for the plugin files.

4 GUID to the Global Unique Identifier of the created plugin.

5 DLLName to the file name, including the extension, of the class library

produced by the Visual studio project.

6 PluginRegKeyName to the descriptive text that will appear in the programs

list providing the opportunity to uninstall the plugin.

7 UninstallerName to the desired name for the program that will uninstall the

plugin.

8 DescriptiveTextForPlugin to a short description of the Plugin’s functionality.

4 In the Install section change the file names to match the names of the files

output by Visual Studio.

5 Locate the NSIS program and open it to reveal the NSIS menu.

6 Select the Compile NSI scripts option.

7 Locate the edited NSI file in the output directory of the Visual Studio project.

Open it in the MakeNSISw.exe window by dragging and dropping the file into the

window or using the open file dialog.

You can also compile the file by right clicking on it and selecting Compile

NSIS Script. Or if using Notepad++ you can compile the NSIS file into an

installer by adding a run command to the program. Full details of this

process can be found here:

http://nsis.sourceforge.net/Notepad_Plus_Plus

8 The installer can now be tested either from the MakeNSISw.exe window or by

locating the created installer file.

It is recommended that you unregister any previously registered versions of

the plugin before you install the new one to avoid any potential conflicts.

http://nsis.sourceforge.net/Notepad_Plus_Plus

authorit word publishing template · 2020. 8. 6. · powermill plugin training introduction ......

Documents