Last updated on May 16th, 2013
We have all heard that phrase. We have all faced that scenario. A script runs perfectly fine on your machine or any VM you have, but just refuses to do anything useful on that one server where it really matters. Error messages can be notoriously unhelpful. “Access denied”, yes, but to WHAT and WHY? And everyone’s favorite “Unknown error” makes for a very frustrating day at the office.
If you have physical or remote desktop access to that server it’s pretty easy, just use whatever debugger you have, install it on that machine and see what happens. Or, in case of PowerShell, use the ISE. But what if you can’t use remote desktop and the machine is halfway around the globe?
Enter the world of remote debugging. PrimalScript 2012 and PowerShell Studio 2012 enable you to debug on a remote machine just as you do on your local computer. You can use the same 32/64 bit capability and the same switching between PowerShell V2 and V3 as you do locally. All you need is a little thing called the RSEE service. RSEE stands for Remote Script Execution Engine and has been part of PrimalScript for a few versions now.
You can find the RSEE installer in the PrimalScript installation folder (e.g. C:\Program Files\SAPIEN Technologies, Inc\PrimalScript 2012\Redistributables\RSEE) in 32 and 64 bit versions. This will install the service and the debugger components needed on your remote machine. At this point you may have a few questions.
1. Why do I need to install a remote agent?
PrimalScript needs some counterpart to initiate the debug session on the remote machine. The RSEE Service will initiate the communication between the debugger on the server and your local IDE. Neither VBScript/JScript nor PowerShell have any support for remote debugging. Windows Remoting also has no debugging support. So you basically need to run a local debugger on your server and have your IDE on your computer display the results.
2. Why does it need to be a service?
We chose a service over some system tray app for the very simple reason that a service is easy to start and stop remotely, provided you have sufficient permissions. Even if it’s running in the background, as long as it’s not doing anything, the overhead is pretty much zero. On top of that, if the problem you are facing is isolated to a specific user, it is extremely simple to configure a service to run under a specific user id. Otherwise, the system account guarantees that your script can do anything you need it to do.
Configure the service to use a specific user id if necessary
If you are within the same network as your target machine it is extremely simple to use the remote debugger after you have installed the service there. Simply load up the script you wish to debug in PrimalScript or PowerShell Studio and place a breakpoint as you normally would.
Then select Go –> Debug Remotely in the Debug group in the Home tab.
This displays the “Remote Debugging” dialog shown below. Simply enter the machine name of the target machine here or its IP address.
Press Ok and you should see the debugger hit the breakpoint.
We generally recommend indicating with some type of output what the current user or machine name is, so that when you are debugging you are sure you are on the correct target computer.
So that’s all there is to it. After you installed and started that RSEE service its all the same process as debugging locally. You just start it differently.
In closing a few words on firewalls. If you are using the Windows firewall, PrimalScript’s and RSEE’s installers should have added the required exceptions already. If you use a third party firewall or if your exceptions were removed by group policy, here is a list of executables and ports you need to configure your firewalls for:
PrimalScript.exe and Powershellstudio.exe on your local machine and ScriptDriver32.exe, ScriptDriver32Elevated.exe, ScriptDriver64.exe, ScriptDriver64Elevated.exe and rexecservice.exe on the remote machine. The ports depend on your settings, which can be found here in PrimalScript:
You should not have to change these port settings unless something else you have uses these ports. Please note that if you change the ports locally you must change them on the remote machine accordingly.
Oh and one final thing: No, you do not need to copy your script to the remote machine. PrimalScript or PowerShell Studio will send it to the remote machine for you.