<menu path> <link to F1 content>
System Setup / Plugin Customization / Plugin Configuration [SET062]
This is a technical user guide for developers and DSPs to get an overview of how custom plugins can be utilized within the DATASCOPE WMS software. The purpose of this document is to give you a complete overview of how to build a simple plugin.
First, we would like you to review the Custom Plugins Interfaces and Types user guide.
| Info |
|---|
Strong development skills are required in order to develop your own plugins. For more information, refer to What is needed to work with Plugins? |
| Info |
|---|
If you don’t like reading, you can watch the video. |
| Panel | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
premium_3_CUSTOM_PLUGINS_BUILDING_A_PLUGIN_product_technicalguide TG - v0.1.pdf |
Try it!
<content>Practical Problem
Within most of our Checkout Modules, we have a Fetch Mass button that can integrate with an external weight scale. It might be in different places for each module, but most of them use this button. All this button does is import the actual weight, received from an external weight scale, of a product into the system to compare with the weight and mass the software thinks it must be and then do a variance calculation. Different weight scales use various formats and communication options, so a plugin must be configured to link the Fetch Mass button with the external weight scale.
In our example, we will not integrate with an external weight scale but with a normal .txt file. In the real world, you should be able to get some form of file from an external weight scale.
Project Structure
Visual Studio IDE - You will need Microsoft Visual Studio 2022.
.Net Framework - You will be using the standard .Net Framework 4.7 (not Core)
Class Library Project - You will create a Class Library Project type within Visual Studio. This will generate the .dll files required.
Reference Requirements - We will review the References requirements within the Class Library Project.
Implementing the Interface - As well as how to implement the required Interface for this plugin type.
Inputs/Outputs - Lastly, we will look at the Inputs and Outputs generated for this practical problem.
Start Coding
Open Visual Studio
Select Create a new project.
Search for a Class Library and select the Class Library (.NET Framework) specifically for C#. This can also be done in VB (Visual Basics), using the WPF Class Library.
Select Next
Enter a name for your project in the Project name field. Example: DemoMass
| Info |
|---|
Note: The Project name shouldn’t have any spaces. |
Select Create
| Info |
|---|
Note: We’re using the Framework .NET Framework 4.7.2 |
The project screen will open with the Class Library visible.
The first step would be to rename your Class1. Example: MassPlugin
Select Solution Explorer on the right-hand side of the screen.
Right-click on Class1 and select rename.
Next, there are a couple of things you must do prior to coding the plugin.
Include the DATASCOPE WMS SDK as a Reference under the References.
§ To do that, you will need the .dll file from the DATASCOPE WMS server.
§ On the DATASCOPE WMS server, browse to C:/ Program Files (x86) / DATASCOPE / DATASCOPE WMS SDK / DATASCOPE.SDK.dll
§ Right-click on the .dll file and select Copy.
§ Paste it on your local machine (C:/SDK should be fine) where you are busy developing the new plugin.
Right-click on References within your project
Select Add Reference
o Browse to the C: / SDK folder on your local machine and insert the DATASCOPE.SDK.dll file in the Reference list for the project.
o This will provide you access to all the available Interface.
o Next, you must indicate which Interface you will need for this specific plugin.
§ Add a using line underneath the default using method.
§ After adding the DATASCOPE.SDK. you can Intellisense or ( )PluginInterfaces
o Next, we must add classes from which we will inherit default data.
§ The first one is the class MarshalByRefObject.
| Info |
|---|
Note: This class is a prerequisite for using our Interfaces. |
§ Next, you will search for the applicable Interface associated with this Plugin.
§ As our Practical Problem is to add a plugin to the Fetch Mass buttons on the Checkout modules screens, we will be adding the IFetchMass Interface.
| Info |
|---|
Note: A detailed list of all our current Plugins and their Interfaces are available in the Types and Interfaces user guide, or you can browse to the Plugin Configuration screen under the Main Menu / System Setup / Plugin Customization / Plugin Configuration and view the Interfaces per Plugin |
§ The Interface name, IFetchMass, will be underlined in red. This is because this is an Interface and the method within the Interface must still be implemented.
§ To implement the method, right-click on the Interface and select Quick Actions and Refactorings.
§ Visual Studio will then allow you to implement the Interface.
§ It will then immediately display the method that is required in your code.
§ Therefore, when the user selects the Fetch Mass button (which is the Linked Action) on one of the Checkout module screens, this method will be called.
§ Notice that the method has a return type of string, therefore it expects a return value, which can either be the mass from the external weight scale or an error message. (we will be using an .txt file)
§ Let’s go over both scenarios:
Return an error message when the user selects the Fetch Mass button.
Return the mass from the external weight scale. (In our video example, we’re not connecting to a physical scale, but are using a text file to illustrate the process. Ensure a text file with one line of data, i.e., 23, is stored under C:/Temp/Mass.txt to follow this process)
Inserting the Input method - Insert the following to read from the .txt file.
Reading it - Insert a StreamReader to read the text from the first line of the .txt file.
| Info |
|---|
Note: This is just a simple example, but this piece of code can become complicated, especially if you are reading directly from the external weight scale data. |
The Output - Insert a return – this is what must be returned, sMass, from the .txt file.
o Next, you can build the solution.
§ Right-click on the solution and select Build.
§ Once done, browse to the Directory. Right-click on the solution and select Open Folder in File Explorer or browse from your File Explorer to C:/ Projects / Custom / DemoMass / bin / Debug / DemoMass.dll
§ Locate the DemoMass.dll file.
§ Copy this .dll file and paste it in the C:/ Program Files / DATASCOPE / DATASCOPE WMS WebAPI / Plugins folder on the server.
§ Next, we must configure the plugin within the software.
Configuring the plugin in the software
Open DATASCOPE WMS
From the Main Menu, browse to System Setup / Plugin Customization / Plugin Configuration
The Plugin Configuration screen will open.
All configurations for plugins happen on this screen. This is where a specific plugin (example, the DemoMass.dll) will be linked to a specific process in the system.
Select the Plugin Name drop-down to select one of the Checkout processes. For more information on the available Plugin Types, refer to Custom Plugins Interfaces and Types.
The next step is to enter the file name within the Dll FileName field, which is the compiled DLL under C:/ Program Files / DATASCOPE / DATASCOPE WMS WebAPI / Plugins
Select Save
The newly added plugin will display at the bottom in the Configured Plugin data grid.
Testing
You should now be ready to go and test the new plugin in the system.
Browse to the Application that uses this plugin. In our example it should be the Fetch Mass button within the MSN Grocery Pack module, located under Order Packing & Check Out / Check Out Options.
Complete the MSN Grocery Pack / Complete Carton process up to where the Weigh Complete Box pop-up appear.
Notice the Fetch Mass button. This is the button (or Linked Action) on which we configured the new plugin.
If you select the button, the weight entered in the text file, should display in the Scale Mass field.
If the data in the text file is not numeric, as the string requires it to be numeric, then you will get an error message or if nothing is in the file you can add text to display an error message.
Summary
To summarize what was done:
We opened a Class Library Project within Visual Studio
We inserted the DATASCOPE SDK
We inserted the inheritance from the DATASCOPE SDK
We selected the required Interface.
We wrote the code.
We build it into a single .dll file.
Then, we configured and saved the plugin in the system Plugin Configuration screen.
Lastly, we tested it in the module.