WaterGems Toolbox V1.1

Revision History

  • May 2009 - Version 1.1 uploaded.  Main change to the application was to alter the app.config file to by default "point" to WaterGems V8i DLL files.   However, V1.1 SHOULD still work with V8 XM, and could in theory be done by putting the V1.0 app.config file in place of the V1.1 app.config file.  The WaterGems Toolbox can be downloaded from here.
  • July 2008 - Version 1.0 uploaded.  The app.config file points to WaterGems V8 XM DLL files in the standard installation directory, but the user can use a text editor to point to equivalent WaterCAD files, or files in a non-standard installation directory.  The WaterGems Toolbox can be downloaded from here.


The WaterGems Toolbox provides a set of miscellaneous tools to conduct operations on a WaterGems/CAD model dataset file(WTG.MDB files).  It makes extensive use of the WaterObjects.NET API provided by Bentley for its Municipal Product Group.

It provides some functions that either:

  • Are not available in WaterGems/CAD application; or
  • Have known performance/bug issues when run from the WaterGems/CAD application

This is an intial working release, and is being slowly expanded.  Requests or suggestions are welcome as often these are relatively easy to develop within the WaterObjects environment.


Note that the Toolbox is preconfigured to work with an existing WaterGems installation.  WaterCAD users, or those with non-standard WaterGems installation directories are required to edit the *.config file.




The WaterGems Toolbox application is not a Bentley product, and is not supported by Bentley. It is a non-commercial product to be used at the user's risk.

No Data Safeguards

The WaterGems Toolbox provides none of the data safeguards that the Bentley WaterCAD/WaterGems environment does.

The Bentley WaterCAD/WaterGems environment provides numerous data safeguards, including:

  • Only performing edits in a temporary (ie. "working") copy of the model. The project directory files remain untouched during model edits, and are only replaced with Save operations. Even if a model crashes in mid-operation, the project directory files remain unaffected;
  • Recording of Undo actions so that changes to the working copy of the model can be reversed by the user;
  • Having to press a Save Button to commit the changed model back to the project directory. Changes to the model can simply be discarded by not saving the model;
  • Certain actions in the WaterCAD/WaterGems environment triggering updates to other related model data to ensure that all model data remain synchronised.

In comparison, the WaterGems Toolbox does not create, nor edit, a temporary copy of the model data source file. It makes edits directly in the model data source file.  Crashes mid-operation can potentially corrupt the model. Once the edits are applied, they cannot be undone. However, in many cases the sacrificing of these protections makes the processing of the data file MUCH faster than in WaterCAD/WaterGems.

It is strongly advised that the Toolbox be applied to a copy of your project model, and the model be Validated and Run after Toolbox operations, in case unexpected model behaviour/corruption has resulted.

Requires WaterCAD/WaterGems to be installed

This application reuses Bentley WaterCAD/WaterGems DLL files, which contain the core functionality that WaterGems Toolbox uses for its Tools.  Currently, this release of the Toolbox only works with WaterGems/WaterCAD Build 08.09.400.34.


The application is written in VB.NET 2008. It also extensively uses .NET components from Bentley's WaterCAD and WaterGems products to work with the WaterCAD/WaterGems model data files. As for any .NET based application, the PC must have the appropriate .NET framework components installed to run .NET applications.

The provided setup.exe does not check for the presence of the .NET Framework and the user has to verify this manually. A user will need at least all .NET frameworks up to 2.0 installed. These are usually provided as optional components on the Windows Update website, but can also be downloaded from the www.microsoft.com website.


The WaterGems Toolbox was primarily created to:

  • Automate some tasks that are otherwise manually laborious;
  • Provide some work-arounds for some buggy, or poor-performing actions inside the WaterCAD/WaterGems environment. Some of Bentley's data safeguards directly or indirectly cause some of this behaviour.

At its core, the WaterGems Toolbox makes use of the .NET components that Bentley exposes in the WaterCAD /WaterGems application files. These accessible components are generically called "WaterObjects .NET" by Bentley, and are deliberately exposed so that 3rd party developers can take advantage of them, and are what makes it possible to create an application like the WaterGems Toolbox.



The ToolBox aims for simplicity. The user selects and opens a model file, and then performs whatever operations he/she wants to do on it.

The model file can be opened using File->Open, or using the optional command-line methods described in a later section. The model file remains open until either the ToolBox is closed, or the user selects File->Close.

Note that, as the WaterCAD/WaterGems model files are Microsoft Access databases, changes to the data are automatically committed to the database file. That is why the Toolbox has no "Save" button, as any operations performed automatically commit the changes back to the model file. These changes, once made, cannot be undone, so care is advised.

Delete Selection Set

Allows the user to delete any model elements referenced by a Selection Set. Whilst this can also be done in the WaterCAD/WaterGems environment, deletion performance inside WaterCAD/WaterGems is slow for large Selection Sets, and runtime errors can also result for particularly large models. In comparison, this tool deletes elements very fast, and so far testing has not shown any adverse effects on model files.

At this stage, the tool also automatically deletes any pipes that are linked to any deleted nodes (junctions, tanks etc.). Whilst in theory WaterCAD/WaterGems should still function with Pipes Missing End Nodes, testing in with the current version of the product has shown that runtime errors in WaterCAD/WaterGems will appear if this is not done. To safeguard the user from this behaviour, the Toolbox has this Option set to "On" by default and cannot be changed by the user. It may become available as an option when the WaterCAD/WaterGems product is able to support it.

Inheritance Repair

This Tool compares each Child Alternative record with its corresponding Parent record. If the Child Alternative record contains the exact same data as its Parent Alternative record, then it re-establishes Parent->Child inheritance by resetting the "IsLocal" value to FALSE for that record.

Data inheritance in Alternatives with WaterCAD/WaterGEMs Parent->Child is a great thing, but it does have some common traps:

  • The WaterCAD environment discourages modellors from "quick and dirty" trialing of different options in the currently active Alternatives. Experienced modellors know that, once something is changed, inheritance is lost, and it is very painful to re-establish it. Currently, users either setup new Scenarios/Alternatives for trialling model changes, or just avoid doing trials altogether. This limits the flexibility of the software;
  • All modellors, at some time or other, accidentally enter data into the wrong Child Alternative.  As soon as data is entered into that Alternative, the IsLocal flag is set to TRUE and Parent->Child Inheritance is lost.

To re-establish inheritance is very time-consuming. Even if the data is reset to the original values, the Parent->Child Inheritance can only be fixed by manually finding the affected record(s) in the WaterCAD/WaterGems Alternative Manager and unticking the "IsLocal" checkboxes one by one for the affected elements.  This can be hard to do when the user is trying to distinguish between "real" child records, and the ones that were set to IsLocal accidentally.

This Tool automates that process somewhat. So long as the data is chnaged back to what it was, the Tool will re-establish inheritance. It aims to give modellors some freedom for doing quick trials inside their scenario (like Opening/Closing Pipes or Valves), and give them confidence in being able to re-establish inheritance once they finish trialling their changes and decide they wish to reset the data back to its original state.

Delete Orphan Isolation Valves

This Tool uses the same methodology of selecting Orphan Isolation Valves in WaterCAD/WaterGems Network Navigator Tool. Ie. The referenced pipe has not been set or is non-existent. It then deletes the Orphan Isolation Valves

This tool uses some of the programming elements required to make some of the other, more sophisticated Tools work (eg. Routines for Selecting Orphan Isolation Valves, Deleting Model Elements etc.), and was put into the Toolbox because it was easy to do so, but is not expected to have heavy use due to it being simple to do in WaterCAD/WaterGems. The user may wish to combine this action with other Toolbox actions, however.

Delete Orphan Controls

Finds any Conditions, Actions and Controls that refer to deleted or non-existent elements, and deletes them.

This tool is mainly for those who extract and use SubModels. The current version of WaterCAD/WaterGems puts all control elements into the SubModel, despite the high probability that many of the referenced elements don't exist in the SubModel. In WaterCAD/WaterGems, the only way to delete them is one-by-one in the Controls Component Dialog, which is time-consuming, especially if you have large library of SubModel exports that need to be maintained. This tool seeks to automate this.

A special note for Composite Actions and Conditions. In this version of the Toolbox, if a Composite Action/ Condition refers to ANY orphaned Simple Action/ Condition, then the Composite Action/ Condition is also considered to be "orphaned" and similarly deleted, even if all the other Actions/Conditions are valid.

Reset Inheritance for Common Elements

{Note at this time this component is incomplete, but will appear in V1.1}

This tool analyses an external WaterGems model database, and compares it to the WaterGems model currently open in the Toolbox.  Where there are common Junctions, Pipes etc. (based on Label), it will re-establish Inheritance for all Child Alternative records.

This is mainly a workaround for a problem that occurs when users like to export a "working" Submodel from a large base model, make changes, and wish to import those changes back to the base model.   Unfortunately, during this process, WaterGems will not reset onheritance in the base model where the Submodel has the alternative record as being reset back to being inherited from its Parent Alternative.

This can have adverse effects if a user say, exported out to a Submodel, and re-established inheritance in some records in the Alternatives, and then imported the altered Submodel back to the base model.  These changes won't be picked up in the Submodel import process and will not be applied back to the base model.

This tool provides a work-around by resetting the Inheritance of all common model elements, and the subsequent Submodel import process then simply puts back in all the appropraite Child Alternative records.  The end result will be Alternatives that have identical structures, values and Inheritance for the common model elements.

Clean Working Folders

Although the latest versions of WaterCAD/WaterGems are much improved in the frequency of bugs and runtime, crashing and lockups can and do occur, especially in large models.

Over time, abnormal program terminations lead to a build-up of temporary model files in C:. Eventually, you will run out of disk space and attempts to open models will give some error message along the lines of "Not enough memory to open model" or something like that!  This itself is confusing, because most people associate the term  "memory" with RAM. However, in this case the error message is talking about physical disk space. 

This Tool cleans the working directories for WaterCAD/WaterGems of any left-over temporary files. Usually these directories are, for Windows 2000/XP:

  • C:\Documents and Settings\%(UserName)\Local Settings\Temp\Bentley\WaterCAD\; and
  • C:\Documents and Settings\%(UserName)\Local Settings\Temp\Bentley\WaterGems\.


Since it was easy to do so, this Tool also checks the HAMMER temporary folder.

However, in some circumstances system settings can mean that alternate folder locations are used. Like most other applications, the Bentley temporary folder locations are determined by the Operating System settings.   The Toolbox will automatically refer to any alternate locations.


The application can also be run from the command-line with the project data source file name as an argument.   This was primarily done so that the user has an option of running the WaterGems Toolbox from within WaterCAD/WaterGems as an External Tool.

When the WaterGems Toolbox runs with this argument set, it will then automatically open that model when the Toolbox opens.

The arguments are:

  • /dbname=ModelDataSourcePath. Where ModelDataSourcePath is the path to the location of the *.wtg.mdb file (including the file extension).

To set up the WaterGems Toolbox as an External Tool:

  1. In WaterCAD/WaterGems, go to "Tools->External Tools->Customize"
  2. Add a New Tool, using the "New" Button
  3. For the "Command" setting, Browse to the installed location of the WaterGems Toolbox.exe file (usually in the C:\Program Files\WaterGems Toolbox\ directory)
  4. For the "Arguments" settings, enter the following exactly "/dbname= %(ProjDir)%(ProjStoreFileName)".
  5. The user can Rename the Tool to be whatever you like, or just use the imaginative name of "WaterGems Toolbox"


The user should understand that a model open inside a WaterCAD/WaterGems session is not the actual project file, but a temporary copy stored on your C:\. That is why WaterCAD/WaterGems has a Save button, as this posts the temporary copy back to project folder location.

Because of this, changes that the WaterGems Toolbox makes to a project directory file will not be visible in the currently open model, until the current model is closed, and then reopened. The reopened model will be a new temporary copy of the project directory file and contain any ToolBox changes.

If the user tries to save any changes to the currently open model, then the user will either have to discard the changes made by the Toolbox, or discard the changes made inside WaterCAD/WaterGems. For this reason, it is best to save any outstanding edits in WaterCAD/WaterGems, before opening the same model in the WaterGems Toolbox.

  • Ben,

    This is excellent. I'd like to see more of these sorts of applications available for download from this site. Excellent work and I'm glad that Brisbane Water is getting value out of WaterObjects.NET. I can tell you also that the Bentley Developers in Watertown are thoroughly psyched.

    On deployment of the Toolbox...we may need to calibrate on that. The redistribution of runtime dlls will give our licensing stewards a little heart-burn.

    I'll review that with you off-line.

    But this is fantastic and a perfect use of the BE Community.

    Keep blogging.


    VP Water & Wastewater Solutions