Debugging

This page assumes you are able to fully compile the GeoDMS executables by following the steps at Compiling the GeoDMS. Debugging is an essential part of software development. There are two ways to debug the GeoDMS: debugging the command line program (GeoDMSRun.exe) and debugging the GUI (GeoDMSGui.exe).

Currently, GeoDMS development is done with Microsoft Visual Studio Community 2026 (MSVC2026).

Debugging GeoDMSRun.exe

  1. In MSVC2026, right-click on GeoDMSRun in the Solution Explorer and select Set as Startup Project.
  2. Right-click on GeoDMSRun again and select Properties.
  3. Navigate to Configuration Properties > Debugging.
  4. In the Command Arguments field, enter the full path to the .dms configuration file you want to debug, followed by the item path you want to run.

Example command arguments:

"C:\Projects\MyConfig\config.dms" /MyContainer/MyItem
  1. Press F5 or click Debug > Start Debugging to start the debugger.

Debugging GeoDMSGui.exe

Debugging the GUI is more dynamic compared to debugging GeoDMSRun.exe, as it allows you to interactively navigate the configuration.

  1. Copy GeoDmsGui.exe from the official GeoDMS installation into your output folder (e.g., bin/x64/Release or bin/x64/Debug).
  2. In MSVC2026, right-click on the project you want to debug and select Properties.
  3. Navigate to Configuration Properties > Debugging.
  4. In the Command field, enter: $(OutDir)/GeoDmsGui.exe
  5. In the Command Arguments field, enter /noconfig to start an empty GUI without loading a configuration file. Alternatively, provide a path to a .dms file to load it directly.

Example command arguments:

/noconfig

or

"C:\Projects\MyConfig\config.dms"
  1. Press F5 to start debugging. You can then open a configuration file from the GUI and navigate to the items you want to debug.

Tips

  • Use breakpoints to pause execution at specific lines of code.
  • Use the Watch and Locals windows to inspect variable values.
  • Use Debug > Windows > Call Stack to view the current execution stack.
  • For performance issues, consider using Visual Studio’s built-in profiling tools.

Crash dumps

A structured exception in a released build no longer disappears without trace. The exception filter writes a minidump to the CrashDumps folder of the LocalDataDir, and it does so in the filter, before the stack is unwound, so the dump shows the frames that faulted rather than the handler that caught it. Open the .dmp in Visual Studio (File > Open > File) or in the debugger of the Windows SDK:

cdb.exe -z C:\LocalData\CrashDumps\GeoDms_1234_20260904_111257.dmp -c ".ecxr; kn; ~*kn; q"

Point the symbol path at the build the dump came from (_NT_SYMBOL_PATH), otherwise the stack is a list of addresses. .ecxr switches to the context of the exception; without it the stack shown is the one the dump was written on.

A dedicated writer thread, created at startup and parked on an event, does the actual write, so a stack overflow is dumpable too: the faulting thread hands over the request and the writer runs on a stack of its own. A SetUnhandledExceptionFilter backstop catches a fault on a thread inside no __try, a tile worker for instance, which before produced nothing; it writes the same dump and then lets termination proceed as before. One dump is written per process, and a code that is not a crash (a C++ or Delphi throw travelling as a structured exception, a failed delay-load) does not spend it. Dumps are MiniDumpNormal plus the memory the stacks reference, never full memory, so a process holding tens of gigabytes still writes tens of megabytes; the setup lives in InitCrashDumpSupport in rtc/dll/src/xct/DmsException.cpp.