Debugging an Extension

Adobe Creative Suite Extension Builder allows you to debug your extension while it is running within a Adobe Creative Suite application. You can:

Debugging an extension

There are two possible workflows for debugging an extension in a Creative Suite host application:

Debug As workflow

To debug an Adobe Creative Suite extension with Extension Builder while it is running in the host application:

  1. Make sure the host application is not running. You must allow the IDE to launch the application to ensure that the extension code is available for debugging.

  2. Open your project in Extension Builder.

  3. Set a breakpoint in your ActionScript code.

  4. Right click in the project and choose Debug As.

  5. The IDE offers a debug configuration for each of the host applications that your extension supports. Select the debug configuration to launch the desired application.

  6. Open the panel for the extension that you want to debug, and invoke the code that contains the breakpoint.

  7. Use the Flash Builder debugger to step through the code.

Attach As workflow

This feature currently supported in Illustrator, InDesign, InCopy, Flash Pro, and Dreamweaver (Windows only).

To attach an Adobe Creative Suite extension to a host application and debug it with Extension Builder:

  1. Make sure the target host application is running.

  2. Open your project in Extension Builder.

  3. Set a breakpoint in the ActionScript code.

  4. Right click in the project and choose Attach As.

  5. Select the application you want to attach; you should see some trace messages.

  6. Switch to the target host application; you should see that the extension is loaded.

  7. Execute the extension. When it reaches the break point, the Flash Builder debugger is triggered.

  8. Use the debugger to step through the code.

After you halt this first debugging session, you can attach again without having to restart the host application.

Launch Configurations

Launch configurations are the way Extension Builder stores state about your past launches to an application (e.g. what version of the application you last launched to). On the first launch of your project, a launch configuration is automatically created. If you have multiple versions of Creative Suite applications installed on your machine, Extension Builder will prompt you during the first launch to choose a version to launch to:

If you select the "Remember my decision" option, this version will automatically be used on subsequent launches. To change the version you are targeting at a later time, you have to change the launch configuration:

  1. Right click on project and choose Debug As > Debug Configurations...

  2. Select the application for which you'd like to change the launch configuration and expand the tree.

  3. Select the launch configuration associated with your project.

  4. Change version of the application using the combo box.

  5. Select the Apply button.

Troubleshooting tips

Inspecting the application scripting DOM

During a debug session, you can inspect your own code, and also the application scripting objects made available through the Creative Suite ActionScript wrapper libraries (CSAWLib). If your extension uses the CSAWLib API to interact with the host scripting object model, you can see the accessed object properties in your debug perspective.

For example, you can select  a com.adobe.illustrator.Document object and inspect its properties, in the same way you inspect the objects that you have defined. Every time you request a property, the tool makes a call to the underlying scripting engine to retrieve its value. The Variables pod here shows the values of some of the properties for the Illustrator document object, such as the default name, "Untitled-1".

Checking log files for errors

Several types of logs are available for help in debugging your Adobe Creative Suite extensions:

LogBook logs

You can use the LogBook application to track logging messages sent between the various platform components. To use this application for logging:

  1. Include this code in your application main MXML file so LogBook can listen to and display the logging information traced by your extension:

var loggingTarget:LocalConnectionTarget = new LocalConnectionTarget("_test");
loggingTarget.filters=["*"];
loggingTarget.level = LogEventLevel.ALL;
loggingTarget.includeDate = true;
loggingTarget.includeTime = true;
loggingTarget.includeCategory = true;
loggingTarget.includeLevel = true;

logger = Log.getLogger(this.className);

logger.info("my message");

  1. Go to http://code.google.com/p/cimlogbook/downloads/list and download LogBook-1.3.air

  2.  Install the AIR application and start it.

  3.  Enter the local connection name, as passed into the constructor of LocalConnectionTarget. In the example, this is '_test'.

  4. Start the host application and open your extension. You should see log messages in LogBook.

  5. To listen for internal messages, set the local connection name in logbook to '_csxs2'

Flash Player's built-in logging  

Flash Player runtime embedded in the Creative Suite application has some built-in logging functionality. It is very light-weight and easy to set up, but not as comfortable as LogBook. To use it, you must put trace() calls directly into your scripts, or create a TraceTarget instance. For example:

var traceTarget : TraceTarget = new TraceTarget();
traceTarget.filters = ["*"];
traceTarget.level = LogEventLevel.ALL;
traceTarget.includeDate = true;
traceTarget.includeTime = true;
traceTarget.includeCategory = true;
traceTarget.includeLevel = true;

To generate the flashlog.txt file:

  1. Create a new file mm.cfg in the platform-specific folder:

  2. Edit the file and add these lines:

    ErrorReportingEnable=1
    TraceOutputFileEnable=1

The flashlog.txt file is then generated in the platform-specific folder:

Application logs

The Adobe Creative Suite extensibility infrastructure creates a log file for each of the applications running extensions. These files provide useful debug information for extension developers. The log files are generated in the platform’s temp folder, and named csxs2.version#-HostID.log; for example, csxs2-ILST.log for an extension running in Illustrator CS5, or csxs2.5-ILST.log for Illustrator CS5.1.

These logs are located at these platform-specific locations:

If you need more detailed information, you can increase the logging level. The possible log level values are:

"0": Off; no logs are generated
"1": Error; preferred and default level
"2": Warn
"3": Info
"4": Debug
"5": Trace
"6": All

Update the LogLevel key at these platform-specific locations:

You must restart your application for these changes to take effect.

CS Service Manager logs

The CS Service Manager keeps log files in the logs folder under the CS5ServiceManager or CS5.5ServiceManager folder, at these platform-specific locations:

Profiling an extension

Extension Builder enables you to profile an extension while it is running within a Creative Suite application, using Flash Builder’s Profiler tools. You can use the Profiler to find memory leaks or performance bottlenecks in your extension.

The profiling feature is only available to Flash Builder Premium users.

Running the Profiler

  1. Before profiling an Adobe Creative Suite extension, ensure that the host CS application’s Welcome Screen is disabled. To do this, launch the application; if the Welcome Screen appears, check the "Don't show this again" checkbox.

    If the Welcome Screen is not disabled, the Profiler cannot connect to the host application.

  2. Close the host CS application if it is running.

  3. In Extension Builder, right click the extension project and select Profile As, then select an application.

    Extension Builder launches the selected application.  If your extension targets multiple versions of the selected application and you have more than one version installed, you are prompted to select the version to launch:

  4. In the host application, open your extension from the Windows > Extensions menu.

  5. In Extension Builder, a  Connection Established dialog opens. Click Resume to begin profiling.

    In some CS applications, the Connection Established dialog opens before you start your extension; the Profiler connects as soon as the host application has launched. In this case, click Resume to start the Profiler, then open your extension.

  6.  Use the Flash Builder Profiler tools as documented here: http://help.adobe.com/en_US/flashbuilder/using/WS6f97d7caa66ef6eb1e63e3d11b6c4d0d21-7e46.html

Configuring Profiler preferences

To access the Profiler preferences:

In Windows, choose Window > Preferences > CS Extension Builder > Profiling

In Mac OS, choose Eclipse/Flash Builder > Preferences > CS Extension Builder > Profiling

Filtering profiler data

CS extensions are loaded as sub-applications of a single Flex application called StageManager. This means that the data collected by the Profiler includes data on StageManager and all running CS extensions. In order to make your extension’s profiling data easier to find, make sure no other extensions are running while you are profiling yours.

You can also filter objects in the StageManager namespace (com.adobe.csxs.*) from the profiler perspective. Filtering is controlled by a Profiler preference; Extension Builder automatically creates a filter for these objects by default.

Setting connection timeout

You can set a preference to configure the connection timeout, a millisecond value. This controls how long the profiler waits for an extension to be launched. If no extension is launched within the specified number of milliseconds, the profiling session is cancelled, and the Extension Builder displays an "Unable to Connect" error message.

 

 

Copyright © 2011 Adobe Systems Incorporated. All rights reserved.