Debugging macros with VS 2017

Need help, or want to share a macro? Post here!
Posts: 1060
Joined: Thu Apr 05, 2018 1:53 am

Debugging macros with VS 2017

Postby TheMarkster » Wed May 23, 2018 10:35 pm

Is anybody else using VS 2017 for debugging FreeCAD macros? I have found it to be quite useful, so I decided to put together a post describing how to set it up and use it.

Download VS2017 here:

There are versions for Windows and macOS (but I don't think you can debug FreeCAD macros on the mac version). I'm using the free community edition for Windows.

Download and run the installer. I selected every python option I could find in the installer because I wasn't sure which, if any, would be needed. I presume at least the ability to do python projects would be required.

Once you get VS2017 installed, debugging FreeCAD macros is as simple as loading the macro in VS2017, attaching the debugger to FreeCAD.exe, setting up your breakpoints (in VS2017, not in FreeCAD), and executing the macro in FreeCAD as you would normally execute it.

You will need to add a .py extension to the macro in order for VS2017 to recognize it as a python source file. It will still work in FreeCAD with the .py extension, (e.g. MyMacro.FCMacro becomes

Create this macro and name it

Code: Select all

import FreeCAD
import Part

x,y,z = 3,5,7
box = Part.makeBox(x,y,z)
Open the file in VS2017 and add a breakpoint on the last line:
Open FreeCAD if it's not already running.
In the debug menu in VS2017, select Attach to Process...
In the Attach To: section select Python as the type of code to debug.
Find FreeCAD.exe in the list of running processes and click Attach.
Execute the macro in FreeCAD as you would normally execute it. Macro -> Macros -> -> Execute. (Don't choose debug, choose execute.)

If all goes well you should be in the VS2017 debugger with a screen similar to this one:
screenshot1.png (54.28 KiB) Viewed 991 times
If it doesn't work (or if it stops working) try restarting FreeCAD and re-attaching.

In the Debug -> Windows menu you will find options to bring up the various windows. I have found locals, autos, watch1, and the Immediate Window to be useful.

The locals window gives the most objects.
The autos window narrows down the list to focus on the ones you're most likely to be interested in.
In the watch1 window you can specify only those objects you're interested in.
The Immediate window can be used to modify values on the fly, call a function, etc.

Here is a screenshot of the autos window:
screenshot_autos.png (36.84 KiB) Viewed 991 times
In the Watch1 window you can browse FreeCAD objects. For example, here I've entered:

Code: Select all

as a watch.
screenshot-selection.png (57.44 KiB) Viewed 991 times
This is a good way to browse to see which properties and methods are available, or at least some of them.

The VS2017 editor has some nice features. It can, for example, comment out (or uncomment) an entire block of selected code. (Ctrl+k,c to comment, Ctrl+k,u to uncomment). It can indent / unindent blocks of selected code: Edit -> Advanced -> Increase Line indent. Set a bookmark in your file: Ctrl+k,k. Navigate to next bookmark: Ctrl+k,n (or Ctrl+k,p for the previous bookmark). Another nifty feature is an ability to rename an object and have all references updated to the new name. For example, highlight the word box in the 2nd line, and do Ctrl+r, Ctrl+r (do it twice). Give box a new name called newBox and hit ok. It not only renames box to newBox, but it also updates the reference to box in the next line: becomes Ctrl+f to open a find dialog. Ctrl+h for a find and replace dialog.
User avatar
Posts: 7083
Joined: Fri Aug 29, 2014 12:45 am
Location: Saint-Petersburg, Russia

Re: Debugging macros with VS 2017

Postby DeepSOIC » Fri Jul 27, 2018 11:26 pm

Thanks for sharing! To my bookmarks it goes.
Posts: 3091
Joined: Tue Nov 06, 2012 5:42 pm

Re: Debugging macros with VS 2017

Postby wandererfan » Sat Jul 28, 2018 1:24 pm

Is there an easy way to turn a forum post into wiki format? I've added this link as a temporary measure:

PythonDebuggingWiki.png (31.67 KiB) Viewed 861 times