SDK: Building a Module (Advanced)

Overview

Custom modules are created by users to add or extend certain functionalities and to link together different types of custom functionality. While custom modules do not require .dlls, building custom code in a .dll is common. Using a custom module may involve grouping exported Decisions objects, custom Flow behaviors, and/or step implementations together in one module, integrating custom Flow or step implementations with a third-party library, etc.

If a custom module needs to be updated, refer to the Installing Modules section.

Prerequisite: MSBuild Requirement

• Build Tools for Visual Studio (MSBuild) must be installed in order to build modules.
• Download Visual Studio Tools - Install Free for Windows, Mac, Linux

Best Practices

When creating a custom module, keep the following best practices in mind:

• If issues arise, please refer to C:\Program Files\Decisions\Decisions Server\Logs.
• Contact support to remove a custom module.

Creating a Custom Module

1. Install the latest version of Decisions locally. For more information, refer to the Installation Guide.
2. From GitHub, download the Custom Module by selecting Code > Download ZIP.
3. The example module is named "CustomModule". Rename files to match the name of the module that is being created.
4. Open CustomModule.csproj, CustomModule.sln, Module.Build.json, and build.proj and rename instances of "CustomModule" to match the module name.
5. If needed, update the NuGet package reference in the CustomModule.csproj file to the correct version of the SDK.
6. Add a reference to any external or third-party DLLs.
   
   

   Module.Build.json Element	Use Relevance	Description
   CoreServicesDlls	Most commonly used	This folder contains a DLL or multiple DLLs that define a project's Flow steps, Rule parts, customizations, behaviors, initializer code for setup, and more. If these files have any Web Services registered in this folder, the user will get corresponding ServiceClient DLLs in the ServiceClientDlls folder. These are created by the CreateModule.exe tool.
   ReferenceDlls	Required if third-party dlls are used	Used to store third-party dependencies for a module.
   CliDlls	Most commonly used	See note on CoreServicesDlls. This folder does not usually contain any custom assemblies, only those generated during module build.
   WebPages	Not typically used	HTML or ASPX pages go into the web host's root directory. This folder must contain zip files that are unpacked on module installation. The unpacked files become peers to the Login.aspx page. This folder may contain folders, and those folders will be maintained.
   MvcDlls	Not typically used	Folder for compiled Dlls of MVC views and controllers
   MvcViews	Not typically used	These are additional MVC Views that are hosted in the Decisions.Web. The host is the primary user interface. MvcViews can be used to add additional view controls for pages and forms. These files go to the installation's Web Host/HUI virtual directory. HUI is the virtual directory that serves the HTML portal to users.
   AgentDLLs	Not typically used	Extra DLL files for adding the capability to the Decisions Cloud to Site Agent. If not using the agent and extensions to the product do not need to be run through the agent, this folder can be safely ignored.
   SQLScript / MySQLScript / OracleScript / AzureScript	Not typically used	These are database scripts that will run when the module is deployed. These are often used to add tables or stored procedures that this module relies on.
   ObjectsToImport	Commonly used	Flows, Pages, Reports, Rules, and Folders that have been built by the Decisions designers and exported from Decisions using the Import/Export function. These should be .decObj files.

   Note: Below is a summary of default reference DLL handling for modules:

   • CoreServicesDlls: You must add the path to your module DLL here.
   • ReferenceDlls: You must add ALL dependency assemblies required by your module, if they are not already included as part of the Decisions platform.
   • Important: You CANNOT include duplicates of library assemblies that are already part of the Decisions platform. If you are using a library included with the platform, reference the same version in your module project’s .csproj file.
7. Implement the module functionality by adding class files or custom code.
8. Run BuildModule.ps1 with PowerShell to build a .dll and create Module.zip. Running BuildModule.ps1 -deployModuleLocally builds the DLL file and creates the required module zip file to be deployed in Decisions.
9. Stop the Decisions service and place the zip file into 'C:\Program Files\Decisions\Decisions Server\CustomModules'. Start the Decisions Server service.
10. Include any custom images inside the CustomImages folder of the Module .zip file. Refer to these images in CSS within MvcStyles to utilize them in the module.
11. Once the Module is deployed, install the Module.
12. If any changes are required, make the changes to the code.
13. Run BuildModule.ps1 -deployModuleLocally to deploy changes and repeat as needed. 

Debugging Custom Decisions Modules with VSCode

Prerequisites:

1. Install VSCode + C# Extension
2. Local Decisions instance running

Steps:

1. Clone or download a copy of the code.
2. VSCode must be run as an administrator.
3. Open the folder containing the module repository.
4. Select the ‘Debug’ tab, then click “create a launch.json file”.
5. Select ‘C#’ as the debugger.
6. Select ‘Attach to a .NET process’. Use “Add Configuration” if not automatically prompted.
7. Save the launch.json. This will enable the option to start debugging with the new configuration.
8. Run .\BuildModule.ps1 successfully before attaching the debugger or setting breakpoints in the code. This command deploys a copy of the module to the local instance. Ensure the module has been initially installed.
9. Click the play button or press F5 to start debugging.
10. Select Decisions.Web.Core.exe as the application to debug.
11. Add a breakpoint to the code.
12. Configure the step and debug the Flow.
13. The breakpoint will pause the Flow of execution during the test run.