Debugging an Extension

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

Debugging an extension

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

Debug As workflow

To debug an Adobe application 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 application 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 Cloud 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 Cloud 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 application 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:

import com.adobe.csxs.logging.targets.LocalConnectionTarget;
import mx.logging.*;

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

var logger::ILogger = 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' (for CS5.x targets) or _csxs3 (for CS6 targets).

Flash Player's built-in logging  

Flash Player runtime embedded in the Adobe 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:

import mx.logging.*;
import mx.logging.LogEventLevel;

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 Cloud 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 csxs[version]-HostID.log; for example, csxs2-ILST.log for an extension running in Illustrator CS5, or csxs2.5-ILST.log for Illustrator CS5.1, or csxs2.53-ILST.log for Illustrator CS6.

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.

CEP Service Manager logs

The CEP Service Manager keeps log files in the logs folder under the CC[version]ServiceManager folder, at these platform-specific locations:

Profiling an extension

Extension Builder enables you to profile an extension while it is running within an Adobe 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 application extension, ensure that the host CC 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 CC 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 CC 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 > Adobe Extension Builder > Profiling

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

Filtering profiler data

Adobe 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 Adobe 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 © 2012 Adobe Systems Incorporated. All rights reserved.