ExtendScript Debugger Extension for Visual Studio Code

A Visual Studio Code Extension that enables debugging ExtendScript-based extensions in Adobe’s applications that support ExtendScript.

Supported features

• Target and Engine Information Bar - Developers can launch ExtendScript-enabled Adobe applications and select ExtendScript engine
• Call Stack
• Breakpoints
  • Hit counts
  • Expressions
  • debugger statement
• Variables Inspection
  • Local Scope and Global Scope
  • Modify variables
• Debugging commands
  • Continue
  • Stepin
  • Stepover
  • Stepout
  • Stop
  • Restart
• Debug Console
  • Expression evaluation
• Expression Evaluation on Hover
• Export ExtendScript to JSXBIN
• Target started debug session

Unsupported scenarios

• Profiling Support
• OMV
• Functions/Auto-Completion
• Scripts Panel

Getting Started

Installation

1. Install the extension
2. Restart VS Code and open the folder containing the project you want to work on.
   • Note: with Visual Studio Code 1.31.1 and above, restart may not be required.

Using the debugger

When your launch config is set up, you can debug your project. Pick a launch config from the dropdown on the Debug pane in Code. Press the play button or F5 to start.

Configuration

In your project, go to the debugger and click the little gear icon and choose ExtendScript Debug. A new launch configuration will be created for you with following configuration:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "1.0.0",
    "configurations": [
        {
            "type": "extendscript-debug",
            "request": "launch",
            "name": "Ask for script name",
            "program": "${workspaceFolder}/${command:AskForScriptName}",
            "stopOnEntry": false
        }
    ]
}

Add the configuration needed from the supported launch.json settings below and save the launch.json file.

Supported launch.json settings:

Debugging

• With your .js(x) file open and the configuration done, click on "Select Target Application"
• Choose the application that your .jsx file is compatible with
  • Note: You may also edit the launch.json to launch or run your target application automatically.
• If the application is not currently running you will be prompted to open it by selecting 'yes' followed by pressing Enter. Once the application launch is complete you should be able to see the application name and the default engine in the status bar.
• Add breakpoints and click the green "Play" button in the debugger.
• A new UI bar will appear at the top of the VSCode window with arrow buttons for:
  • Continue
  • Step Over
  • Step Into
  • Step Out
  • Restart
  • Stop

Export to JSXBIN

You can export your JS(X) to JSXBIN by right-clicking in editor window of a JS(X) file and selecting Export As Binary.... A file name suggestion will be given. If you press Enter then your file will be saved in the same directory as your currently opened file. You can enter a complete path for generating the output .jsxbin if required.

Batch Export to JSXBIN

By using Export To JSXBIN above, you can export one file at a time. However you can also batch export your JS(X) to JSXBIN using a script provided with the extension. But for that please ensure Visual Studio Code is not running. Please follow:

1. Ensure that you have node 10.11.0 installed. You may use the following command from terminal to get node. npm install -g node@10.11.0
2. Locate the script at the following location: Mac: $HOME/.vscode/extensions/<adobe.extendscript-debug extension directory>/public-scripts/exportToJSX.js Windows: %USERPROFILE%\.vscode\extensions\<adobe.extendscript-debug extension directory>\public-scripts\exportToJSX.js
3. Run the following command from terminal. node <Path to exportToJSX.js> [options] [filename/directory]

Target Started Debug Session

The extension supports the debug session being started by the target, e.g. Photoshop. For this do the following:

1. Ensure that no other debug session is running in Visual Studio Code.
2. In your JS(X), just add these 2 statements before the line you want to break on:

$.level = 2;
debugger;

3. Now run your JS(X) in the Adobe's application, e.g. Photoshop.
4. Your script should break on the debugger statement in VSCode.

Notes

• The debugger works like other VSCode debugging.
• If you experience any trouble setting breakpoints in files with extensions .jsx, then try disabling any previous extensions related to ExtendScript as those extensions can conflict with breakpoints functionality.
• VSCode ExtendScript Debugger extension and ESTK application can’t run simultaneously.
• VSCode does not recognize #target and #targetengine commands.

Resources

• Official VSCode Debugging Documentation

Forums

• Extensions / Add-ons Development Forum

Troubleshooting

The following steps are good standard troubleshooting, as well as troubleshooting "Error ##15 Can't initialize target."

• Make sure the ESTK stand-alone application is closed
• Close the target application (example: Photoshop)
• Close Visual Studio Code
• Make sure there are no VS "Code Helper" processes in the Activity Monitor (Mac) or Task Manager (Windows)
• Restart Visual Studio Code
• Does it work then?
• If not, does a reboot help?

If you continue to run into problems, please report them in the forums above.

FAQ

Q. Where is the actual error displayed?

A. When you hover over the words on the line that errors, there will be a popup showing the error. The error should be there in Output Console too.

Q. I am getting Error ##15 Can't initialize target.

A. Please try following the steps in the Troubleshooting section above. If you continue to run into this error, please tell us about it in the forums above.

Q. Can I set the Target Application in launch.json?

A. You can set the target application in launch.json.

For this you will need target specifier. To get the target specifier, put "trace" = true in your launch.json. When you start a session in your desired application (by choosing from "Select the target application"), the first line in Debug Console/Output Console will be Starting <yourScript> in target: <targetSpecifier> and engine: <engineName>. You can then get these two values and put in your launch.json configuration:

"targetSpecifier": "photoshop-130.064", "engineName": "main"

Q. How can I avoid the ask for name prompt?

A. You can avoid the 'ask for name' prompt by putting the script name into the launch.json file. For example, my script is named test.jsx:

{
  "version": "1.0.0",
  "configurations": [
    {
      "type": "extendscript-debug",
      "request": "launch",
      "name": "Testing this plugin",
      "program": "${workspaceFolder}/test.jsx"
    }
  ]
}

Sample Script

You can use the following script to test the debugging features. This script is compatible with Photoshop.

//index.jsx
function addTextLayer(text) {
    var layers = app.activeDocument.artLayers;
    var layer = layers.add();
    layer.kind = LayerKind.TEXT;

    var textItem = layer.textItem;
    textItem.kind = TextType.PARAGRAPHTEXT;
    textItem.size = 24;
    textItem.position = [0, 0];
    textItem.contents = text;
    textItem.width = new UnitValue('500 pixels');
    textItem.height = new UnitValue('500 pixels');
}

Then. to test the script, you might find it useful to build a debugging driver script. For example:

//debug.jsx
$.level = 2;
//@include "index.jsx"

addTextLayer("Hello");
debugger; // comment out or remove if you want the debug session to end when the above is complete

At this point, you can set a breakpoint in index.jsx, and then run debug.jsx to trace through the function. You can also use this driver to configure various debug levels (like $.level = 2). You might also want to invoke the debugger using the debugger statement as part of your debug driver if you want to examine the final state of the environment before the script completes.

Terms & Conditions

Your use of this application is governed by the Adobe General Terms of Use.

© 2019 Adobe. All rights reserved. Adobe Privacy Policy.