Debugging Client-Side Code in Flex Applications

Eric Anderson

Adobe

The Macromedia Flex RIA architecture leverages the power and ubiquity of Macromedia Flash Player to deliver rich and engaging Internet applications. While this new presentation server makes RIA development easier than ever, it also presents developers with new challenges when trying to debug ActionScript code running in the Flash player on client machines.

This article guides you through the process of installing and configuring the components required for client-side Flex application debugging. Moreover, it presents important techniques to make debugging applications running in the client simpler and more effective.

The Flex RIA development architecture offers developers a number of ways to debug applications. The Flex server includes a rich feature set for debugging remote object calls, web service calls, and HTTP requests. Moreover, Flex offers an AMF (Action Message Format) debugging gateway for debugging Flash Remoting calls using AMF. Flex also provides the SWF profiler that allows for detailed performance tuning of SWF movies. The article focuses only on techniques for debugging Flex-generated SWF movies.

Requirements

To complete this tutorial you will need to install the following software and files:

Macromedia Flex

• Try
• Buy

Macromedia Flash Player

• Download

Installing the Flash Debug Player

The Flex ActionScript debugger, or fdb, relies on the Flash Debug Player to output debugging data to the Flash player log, as well as the fdb command-line debugger. The following step-by-step instructions show how to configure the Flash Debug Player for your debugging environment.

Start by verifying the version of the Flash Debug Player installed in your default browser. The following Flash movie displays information about the Flash player version your browser is running. Click "I" in the lower right corner of the SWF and scroll the information to see the Flash Debug Player version information described below.

The SWF file will identify the Flash Debug Player as the “Content Debugger ActiveX Player” or the “Content Debugger Player” while the standard Flash player displays “Release ActiveX Player” or “Release Player.” Flex requires the version of the debug player to be equal-to or newer than Flash Debug Player version 7,0,14,112. If you already have a version of the Flash Debug Player that works with Flex, you can skip ahead to the "Configuring the Flash Debug Player" section.

If you do not have the debug player installed in your browser, you must uninstall your browser’s Flash release player. To do this, execute the Flash uninstall utility (named: uninstall_flash_player.exe) included in the {flex.rootdir}/bin directory. Note, on Windows, the typical Flex root directory is: C:\Program Files\Macromedia\Flex\bin. Next, install the Flash Debug Player included in the {flex.rootdir}/bin directory. IE requires the ActiveX installer (named: Install Flash Player 7 AX.exe) while other browsers (Opera, Mozilla, and so forth-) require the Flash plug-in installer (named: Install Flash Player 7.exe).

Note: The Flash Debug Player included with Flex is only supported on the Windows XP and Windows 2000 environments. A Linux debug player will be available later in the year.

Configuring the Flash Debug Player

The Flash Debug Player includes error reporting features that write error and trace information to a log file, flashlog.txt by default, on the local machine where the Flash player is running. The Flash Debug Player requires read and write access to the HOMEDRIVE and HOMEPATH location for error logging to work properly. On most Windows 2000 and Windows XP machines, the HOMEDRIVE value is set to the primary hard drive description, usually, C:. The HOMPATH value is set to the default home directory, typically at \Documents and Settings\{your system user name}.

Depending on your Windows domain configuration and your local profile configuration, your HOMEDRIVE and HOMEPATH values may be set differently or not at all. If this is the case, you can try to reset or create the values for the local machine. The following instructions describe how to reset the values for your Windows environment.

1. Right-click the My Computer icon on your desktop.
2. Select Properties from the pop-up list.
3. Select the Advanced tab.
4. Click the Environment Variables button.
5. Edit or create the HOMEDRIVE and HOMEPATH environment variables as necessary in the window for User Variables for {your system user name}.
6. Restart your computer.

If setting the environmental variables does not reset the location for HOMEDRIVE and HOMEPATH, you may need to contact your Windows administrator to change your user profile so that HOMEDRIVE and HOMEPTAH values are set to a location where you have read/write privileges.

To enable the Flash Debug Player’s error reporting capabilities, create the Flash debug configuration file. Create a file named mm.cfg, and put it in your HOMEDRIVE and HOMEPATH, for example, in c:\Documents and Settings\eanderson\mm.cfg. The following is a sample of settings you can put in an mm.cfg file that enables the player’s default error and trace logging.

TraceOutputFileEnable=1

ErrorReportingEnable=1

If the mm.cfg file is not located in the correct location, the player does not output error messages to the flashlog.txt file. The flashlog.txt file is stored in the same directory location as the mm.cfg file by default.

Note: The Flash Debug Player limits the number of warning and error messages written to the flashlog.txt file to 100 for each SWF invocation. To reset the default value, use the property MaxWarnings in the mm.cfg. The following example sets the maximum number of warnings to 500.

MaxWarnings=500

Note: Setting MaxWarnings=0 allows an unlimited number of error messages to be written to the flashlog.txt.

Use the TraceOutputFileName={path to location}/{customfilename} property to write the flashlog.txt to a custom location. The following example changes the location of the flashlog.txt to c:\ and changes the name of the file to flexlog.log

TraceOutputFileName=c:\flexLog.log

Flash Player Tracing()

The Flash Debug Player provides support for simple logging to the flashlog.txt using the trace() function. You can use the trace() function when debugging to write variable values or other diagnostic information to the flashlog.txt. The following example uses the trace function in a simple ActionScript function TestEffectHandler().

function TestEffectHandler(): Void {
            var counter:Number;
            var tempCounter:Number = 0;;
            for (counter=0; counter<5; counter++) {
                        tempCounter=counter+tempCounter;    
                        trace("Counter = " + counter);
                        }
            debugText.text = "Total Counted = " + tempCounter.toString();
}

When you invoke the TestEffectHandler() function, it writes the following data to flashlog.txt.

• Counter = 0
• Counter = 1
• Counter = 2
• Counter = 3
• Counter = 4

Flex’s XMLObjectOutput

While the trace() function is a great way to display simple data types and other information, it does not help when you debug more complex data structures like models and trees. For discovering information about these data structures, Flex provides an undocumented utility called XMLObjectOutput that logs simple string data to the flashlog.txt by tracing the values and attributes of XML objects, arrays and other ActionScript objects.

XMLObjectOutput is an ActionScript class that converts XML objects to simple object types. The XMLObjectOutput.as class is included in the Flex distribution in the {flex.rootdir}/extras/XMLObjectOutput directory. To use the XMLObjectOutput utility, copy the XMLObjectOutput.as file to the Flex user_classes directory. By default, the user_classes directory is located at {flex.rootdir}/jrun4/servers/default/flex/WEB-INF/flex/user_classes.

To leverage the utility in ActionScript, simply instantiate an instance of the XMLObjectOutput object as follows.

var myDebugger:XMLObjectOutput = new XMLObjectOutput() ;

Next, use the traceObject() method to output a representation of the data structure to the flashlog.txt as follows.

myDebugger.traceObject( myEmployeeModel );

Consider the following XML model view in MXML as well as the XMLObjectOutput representation of the data from the flashlog.txt.

The MXML representation of XML data:

The MXML representation of XML data:
 <mx:Model id="myEmployee">
   <employee employeeId="5">
            <firstName>John</firstName>
            <lastName>Smith</lastName>
            <phone>617-219-3345</phone>
   </employee>
 </mx:Model>
XMLObjectOutput representation of the same data
Object:  [object Object]
 |-- employee [object]
       |-- employeeId: 5
       |-- firstName: John
       |-- lastName: Smith
       |-- phone: 617-219-3345
	   

The XMLObjectOutput class provides a detailed view into even very complex XML schema.

Command-Line Debugging

Flex’s ActionScript command-line debugger (fdb) allows you to view, in real time, the properties and characteristics of all ActionScript code that comprises an MXML file executing in the Flash Debug Player. Use the fdb to set break points in AS code, step through those break points, and view application trace data as a SWF runs in the browser.

When Flex links and compiles ActionScript, SWCs, and MXML, it produces two generated files for each compiled MXML file. The first file, compiled_mxml_filename.1, contains the class definition of the class associated with the compiled MXML. This file contains the SWF init() function, event handlers, as well as any other ActionScript code required to implement the MXML. You can set breakpoints on most functions in this file except the event handlers.

Note, you can set breakpoints for the event handlers only in the original MXML file. The second file, compiled_mxml_file_name.2, contains the deferred instantiation entry for the MXML mapped class, if any.

Configuring the Flex Server for Client Debugging

When configured for debugging, Flex generates both a SWF and a SWD file (Flash debug file) for each requested MXML template. Flex stores SWD files in the same directory as SWF files. If SWD files and SWF files do not exist or do not match each other, fdb returns an error when attempting to debug an MXML template.

To enable the Flex debugger, you need to make several changes to the Flex server configuration file, flex-config.xml (typically located at c:\JRun4\servers\flex\WEB-INF\flex for JRun installations; depending on your application server, the location wills be different). First, debugging only works when you disable production mode. To ensure production mode is disabled, verify that the following setting is correct in your flex-config.xml file.

<production-mode>false</production-mode>

Next, you can force Flex to generate SWD files for each SWF by setting the generate-debug-swf in the flex- config.xml to true, as follows:

<generate-debug-swfs>true</generate-debug-swfs>

Moreover, you can also force Flex to create SWD files by appending the string to an MXML URL request, even if you disable generate-debug-swfs. To enable query string overriding, edit the flex-config.xml and verify that process-debug-query-params is enabled as in the following example.

<process-debug-query-params>true</process-debug-query-params>

With process-debug-query-params enabled, you can append ?debug=true to an MXML request to generate a SWD file for the MXML. The following is an example of this format:

http://mymachine/flex/debugging.mxml?debug=true

Configuring and Running Flex’s Client ActionScript Debugger (fdb)

To run fdb, ensure that you have the following configuration settings correct. Fdb requires a version of the Java Runtime Environment (JRE) 1.4.x installed on the machine running the debugger. If you don't already have JRE 1.4.x installed, you can get it at: http://www.java.com. Ensure that the fdb jvm.config (located at C:\JRun4\bin\ for JRun installations) file has the java.home value set to the correct location for Java. The following is an example of the java.home setting.

java.home=C:/j2sdk1.4.2_04

Verify that you have the Flash Debug Player installed and configured for your default browser. You can find more information on determining and setting your default browser version in the Flex documentation: http://livedocs.macromedia.com/flex/1/flex_docs/33_deb22.htm#wp146003.

Once you've correctly installed and configured Java environment and the Flash Debug Player, you are ready to start debugging your application with fdb.

1. Go to {flex.rootdir}/bin directory and start fdb.
2. Run the MXML file that you want to debug with the run {path to the MXML file you want to debug} command in the fdb window. The following is an example of the command and the information it returns as you debug a simple MXML file that implements a counter in ActionScript:

   (fdb) run http://e-apple:8100/flex-support/debug/debugmxml.mxml
   Attempting to launch and connect to Player using URL:
   http://e-apple:8100/flex-support/debug/sample.mxml
   Player connected; session starting.
   [SWF] /flex-support/debug/sample.mxml.swf - 487,496 bytes
   
   

3. Set breakpoints and type continue to resume the session.

   The next step in using fdb for debugging an MXML file is to determine which files Flex created for your MXML template. To view the files that Flex generated or used, you can use the info sources command in the fdb window. The following is an example of the command and the information it returns when debugging the explorer.mxml file.

   (fdb) info sources
   sample-generated.as#2
   sample.mxml#1
   
   

4. Set break points in the file and step through them in fdb. To view the source of the application, use the list {file name} command as follows:

         (fdb) list sample.mxml
    1     <?xml version="1.0" encoding="utf-8"?>
    2     <mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml" width="600" height="450">
    3
    4     <mx:Script>
    5     <![CDATA[
    6
    7     function TestEffectHandler(): Void {
    8
    9      var counter:Number;
    10     var tempCounter:Number = 0;;
   (fdb)
    11
    12     for (counter=0; counter<5; counter++) {
    13             tempCounter=counter+tempCounter;
    14             trace("Counter = " + counter);
    15             }
    16
    17     debugText.text = "Total Counted = " + tempCounter.toString();
    18
    19    }
    
   

5. Create a break point at line 13 of the sample.mxml file. Below is an example of how to create a break point on line 13.

   (fdb) break 13
   
   Breakpoint 1 at 0x76a91: file sample.mxml, line 13

6. Execute the continue command to step through the function and see the output.

   (fdb) continue
   
   Breakpoint 1, TestEffectHandler() at debugmxml.mxml:13
   
   13             tempCounter=counter+tempCounter;

   In this tutorial, you want to step through the ActionScript for the loop and print the value of the tempCounter object. To do this, use the print {object name} command. The following asks fdb to print the tempCounter object and then uses the step (or "s" as a shortcut) command to step through the loop and display the value for the object.

   (fdb) print tempCounter
   $1 = 0
   (fdb) step
    14             trace("Counter = " + counter);
   (fdb) s
   [trace] Counter = 0
    13             tempCounter=counter+tempCounter;
   (fdb) s
    14             trace("Counter = " + counter);
   (fdb) s
   [trace] Counter = 1
    13             tempCounter=counter+tempCounter;
   (fdb) s
    14             trace("Counter = " + counter);
   (fdb) s
   [trace] Counter = 2
    13             tempCounter=counter+tempCounter;
   (fdb) s
    14             trace("Counter = " + counter);
   (fdb) n
   [trace] Counter = 3
    13             tempCounter=counter+tempCounter;
   (fdb) n
    14             trace("Counter = " + counter);
   (fdb) n
   [trace] Counter = 4
    17     debugText.text = "Total Counted = " + tempCounter.toString();
   
   

The sample fdb session above is a basic example of how to start a debug session, set break points in code, and then step through them while examining the variable values. You can find more information on fdb including all of the possible features of the tool by typing help in an fdb session. You can also find information in the Flex online documentation, Flex LiveDocs, at:
http://livedocs.macromedia.com/flex/1/flex_docs/wwhelp/wwhimpl/js/html/wwhelp.htm.

Other Considerations

Be aware of a couple of gotcha’s in client-side debugging in Flex. The following is a list of issues and suggested strategies for handling problems with the debugger.

1. The biggest problem Flex developers have when trying to debug is ensuring that they have the Flash Debug Player installed. If you’re not sure if you have the debug Flash player installed, check the Installing the Flash Debug Player section of this article.
2. Like most application servers, Flex uses a number of reserved words for internal processing. Problems can occur when you use the word "debug" as the name of an MXML or ActionScript file.
3. You may encounter a situation where the SWD files do not generate correctly. If you believe that your SWF is using a cached version of either the SWF or the SWD for a given MXML page, clear the browser cache and restart your Flex server before trying to debug the MXML page again.

   The Flash Debug Player cannot communicate with the fdb debugger. This is evidenced by a pop-up window asking you to indicate where the Flash debugger host is running. If when you execute the run command in fdb or make a request to a given MXML page this pop-up window appears (Figure 1), you will need to ensure that your server configuration settings and the URL used to invoke the MXML file are correct.

   

   Figure 1. If this dialog box appears when you execute the fdb run command or request an MXML page, you'll need to ensure that your server configuration and URL are correct.

4. When you launch an fdb session and the following message appears: "WARNING: The Player that you are using does not support all fdb commands," it means that the Flash Debug Player you have installed in not the correct version.  You need to ensure that you use the Flex version of the Flash Debug Player with fdb.

In Conclusion

Flex client side debugging techniques let developers debug even the most complex applications using a variety of tools and techniques especially developed for the Flex development environment. Flex developers can leverage both the Flash player's built-in debugging capabilities using the Flash Debug Player and trace() logging. Flex also provides several new and powerful tools, such as fdb for command-line debugging and XMLObjectOutput, for displaying complex object representations. All of these options help you debug your Rich Internet Applications. Happy debugging!

About the author