The basics of creating a new PlanetTogether customization. From setting up the development environment to loading your first add-in.
This guide will use Microsoft Visual Studio in the explanations of creating a customization project. However, any IDE capable of compiling .net framework libraries can be used.
New Customization Project
- Within Visual Studio, create a new .net Framework class library project targeting .net 4.6.2*.
- Add the PlanetTogether program assembly references. These assemblies are available as part of any PlanetTogether Installation. Default installation directory is: C:\ProgramData\PlanetTogether APS\Software\
Note: PlanetTogether assembly references will be version-specific. To make sure your customization is compatible with the specific version that will be running the add-in, make sure to reference the PlanetTogether assemblies from the correct software version.
*Note: PlanetTogether versions 11.39.9 and later now require a .NET Framework version 4.8.
Including Additional Assemblies
PlanetTogether clients automatically load several of the .net system and utility assemblies. The client application also loads many DevExpress UI Components. To include additional assemblies to use within your customization, they must be manually added to PlanetTogether application folders.
For scheduling customizations, this includes all service application folders and all client executable folders. Instance Program files are found in the Software version folder in the install directory. The default location is: c:\ProgramData\PlanetTogether APS\Software\[Version]\ProgramFiles.
For MyViews and other UI customizations, references only need to be added to the APSClient application. The client will not automatically retrieve extra assemblies from the server. This can be done manually for each user, or on the server. When users run the APS Sign-In application and log into a new version for the first time, the client will be retrieved from the server. The zip file retrieved is Client.zip found in the software version folder. This file will need to be extracted, the extra dlls added, then rezipped and placed in the same location.
Setting Up the Project
For scheduling customizations the output assembly file name must begin with "schedCust." For example schedCust.Customer.Scheduling.dll
In visual studio this is changed under the project settings -> Application -> Assembly Name section.
UI customizations do not require a prefix for the output file name.
Creating your class
There are a variety of customization points, each with its own purpose and functionality. A customization point is used by inheriting from its corresponding base class. As alluded to above, there are two types of customizations:
- Scheduling customizations: These customization points alter how jobs are scheduled. These classes inherit from classes within the PT.Scheduler.Simulation.Customizations namespace.
- UI Customizations: These customizations are used to create custom views and reports for users. These classes must be within the PTUserIntefaceCustomization namespace and must inherit from PTMyView which is located in the same namespace.
All customizations must implement the ICustomizationBase interface and will need to specify a Name and Description. Here is an example customization class code file:
public class Schedulability : SchedulabilityCustomization
public override string Name => "Demo Scheduling Constraint";
public override string Description => "This add-in prevents scheduling on Resource1";
protected override void SimulationInitialization(ScenarioDetail a_sd, SchedulabilitySimulationInitializationHelper a_schedulabilityHelper, ScenarioDetail.SimulationType a_simulationType, ScenarioBaseT a_transmission)
//This function is called automatically before any jobs are scheduled. Use this area to initialize and data objects.
protected override bool IsSchedulable(ScenarioDetail a_sd, ScenarioDetail.SimulationType a_simType, long a_clock, long a_simulationClock, BaseResource a_res, BaseActivity a_activity, SchedulableInfo a_schedulableInfo, out long o_postEventTime)
o_postEventTime = -1;
if (a_simulationClock >= a_sd.GetPlanningHorizonEnd().Ticks)
//Allow scheduling past the planning horizon
if(a_res.Name == "Resource1")
//Don't schedule on Resource1
Testing Your Customization File
First, an installed instance is required for testing. In Visual Studio, we can attach the the running processes to debug the customization code.
You can verify that the customization is loaded from within the client. Under Help -> View Current Internal Add-Ins menu option. Loaded customizations will appear in Scheduler Add-Ins tab. If there are not add-ins listed, re-check each of the steps.
After each change and compilation of the customization assembly, it should be copied to the instance customization folder. Note that this file will be read-only while the instance is running. To quickly copy a scheduling customization file after building, Add the following the project properties -> Build Events section: copy $(TargetPath) "[Instance Customization folder]". For UI Customizations add copy $(TargetPath) "[Instance folder]\ClientUpdaterService\UpdateFiles\UICustomizations"
Try starting PlanetTogether, then from Visual Studio go to Debug and select Attach to process from the drop down menu. You should see your instance system service process. For example "APS [Instance Name] [Version Number] System"
Note that visual studio may need to be run with administrator permissions to attach to the process.
When loading a UI customization, ensure that the ClientUpdater service is running before starting PlanetTogether. To confirm that customization file was successfully loaded,
Now that you have an customization file building and loading, the following guides will help you navigate the PlanetTogether data objects and get started with demo projects.