Full debugging of VBScripts using Visual Studio 2005

Want to do *full* debugging of a VBScripts, then use this procedure.

One of the hardest parts about scripting is getting to know the properties and methods of objects and state of a script during execution.  In this procedure, I show you how to modify Microsoft Visual Studio 2005 for full debugging of VBScripts. I have used this procedure for many years starting with Windows XP. This time, I recently did this on Windows 8.1.

Install and run Visual Studio 2005

Yes, it must be a full version of Microsoft Visual Studio 2005 (Express editions do not work) and it can’t be older or a newer version of Visual Studio, so break out that old archive of software and install it.

During installation, the only option that is needed is “Visual Basic”. In my case, I cleared all other checkboxes and only checked Visual Basic. Then finish the installation wizard.

On Windows 8.1, I had to install an older version of the Microsoft .NET Framework and run Visual Studio 2005 with Administrator rights in order for it to create some starting folders and files.

Configure Visual Studio 2005

Once Visual Studio 2005 is installed, you can immediately run your scripts through the Visual Studio 2005 debugger by using the “//X” argument in CScript.exe or WScript.exe. This prompts the scripting engine for a debugger. I will show how to do this later. In the meantime, let’s configure Visual Studio 2005 a bit more to make it better suited for VBScript execution and editing.

Visual Studio will look like this initially.

In the menu, click Tools, External Tools.

Optionally, delete the “Dot&fuscator Community Edition” entry. In my case, I removed it.

For CScript execution

Click Add and set the fields to these values:

Field	Comment
Title: CScript	This can be any title that you want.
Command: C:\Windows\System32\cscript.exe	This must be the path to the Windows installation directory and point to cscript.exe.
Arguments: //nologo $(ItemPath)	Click the right-arrow button and select “Item Path”. Optionally use the “//nologo” argument so that the CScript logo information will not be part of the output during script execution.
Initial directory: $(ItemDir)	Click the right-arrow button and click “Item Directory”.
Use Output Window: [checked]	Enable Use Output window. This will have the VBScript output go to the output window in Visual Studio

Leave all other entries at default settings and Click Apply.

Note: Optionally, use WScript in the command path if you want to have WScript.exe as the VBScript execution engine.

For CScript debugging

Click Add and set the fields to these values:

Field	Comment
Title: CScript Debug	This can be any title that you want.
Command: C:\Windows\System32\cscript.exe	This must be the path to the Windows installation directory and point to cscript.exe.
Arguments: //nologo //X $(ItemPath)	Click the right-arrow button and select “Item Path”. The “//X” argument is a CScript argument that tells the engine to prompt for a debugger. Optionally use the “//nologo” argument so that the CScript logo information will not be part of the output during script execution.
Initial directory: $(ItemDir)	Click the right-arrow button and click “Item Directory”.
Use Output Window: [checked]	Enable Use Output window. This will have the VBScript output go to the output window in Visual Studio

Leave all other entries at default settings and Click Apply.

Note: If you want to prompt for arguments to the script before execution, then check the “Prompt for arguments” check box.

Click OK on the “External Tools” dialog box when finished adding entries.

Add the scripting buttons to the toolbar

Right-click the Visual Studio 2005 toolbar (the bar with File, Edit, View, and so on) and then click Customize. Click the Commands tab and select Tools from the Categories menu. In the Commands menu, scroll down until you find “External Command 1”. Click, hold, and drag “External Command 1” to the menu bar of Visual Studio 2005. You can put it anywhere you want.

Note: The button will initially show up as “External Command 1”, but will change to the external command title we provided earlier once the toolbar Customize dialog box is closed.

Repeat this for all of the entries in the External Command window that you created earlier such as “External Command 2” and “External Command 3” and so on. Click Close on the Customize dialog box when finished.

In my case, CScript and CScript Debug show up on my toolbar.

Show line numbers

When a VBScript throws an error, it provides the line number and character number of where the error occurred. For this reason, it is convenient to have the line numbers shown when editing the scripts.

Click Tools and select Options. The Options dialog box will show. Check “Show all settings”.

In the tree view control on the left, navigate to Text Editor and select All Languages. Check “Line numbers” on the right and then click OK.

Executing VBScripts in Visual Studio 2005

To open a script within Visual Studio 2005, simply right-click on the script, and Open with Visual Studio 2005. In this case, I opened up test.vbs.

To execute the script, I just click the CScript button. In my case, my script output automatically showed the output in the Output window below.

Debugging VBScript in Visual Studio 2005

Now for the best part! Debugging the script. When a script loaded into Visual Studio 2005, click the CScript Debug button (or whatever you named it). If it throws an error of not able to find the script, then click anywhere in the script editor pane and try it again. The script has to have the focus.

When the debugger starts, it prompts if you want to debug the script from within the same instance of Visual Studio or a new instance of Visual Studio. Choose the existing instance of Visual Studio especially if you already have break points set. Then click the Yes button.

This starts off the script in the debugger and it stops at the first line of code. The yellow arrow and highlight indicate the line of execution.

At this point, you can do debugging as you normally would in Visual Studio such as setting break points, run to cursor, show locals, have a watch window and so on. Use the commands in the Debug menu and/or Debug icons to debug the script.

Showing the output when debugging

A quirk of the debugger is that you have to add the output window again by clicking on down arrow of the icon of a window with a red sphere, then selecting Output.

Change the output window to the debug output.

Now, you should see the WScript.echo output from the script when debugging.

Using Locals and/or the Watch window

I like looking at the variables of my scripts using the Locals and Watch windows. While in the script is paused in the debugger, click the “Watch 1” icon in the Visual Studio tool bar. This will replace the Output window with the Watch 1 window.

In this case, I can select variable “b” and drag it to the Watch Window.

I can do this with any variable or object within a script. This technique is especially helpful with objects and arrays because the Watch window allows you to explore the it and see the values.

Note: You cannot edit the script while it is running in the debugger and the script must be saved in order to run what you are seeing in the editor.

Intellisense and quirks

Visual Studio tries to provide “intellisense” to objects, so that you can just type an object instance name and type, “.” to have it provide you with the properties and methods of the object. Unfortunately, Visual Studio 2005 only provides intellisense for a few of the VBScript objects. Also, please understand that Visual Studio 2005 actually thinks that the VBScript is VB.NET code, so there will be a few inconsistencies.

Also, remember that the debug output has to be enabled. See “Showing the output when debugging” discussed earlier.

For a richer intellisense experience with VBScript editing, consider third party tools such as Sapien Technologies Primal Script.

Conclusion

There are certainly other editors out there for debugging VBScripts, but this one seems to be the easiest and richest experience in regards to VBScript debugging. I’ve used this technique for years for my own VBScripting needs and to teach students the basics of VBScripting. I hope you find this useful.