Debug applications in ColdFusion Builder

Debugging lets you examine and troubleshoot your application. When you debug, you can control when the application must stop at specific points in the code. You can also monitor important variables and test your code. Debugging uses a configuration to control how applications are launched. When you debug your application, you run the debug version of the application file.

Before you use the ColdFusion Debugger, ensure that you do the following:

Set up ColdFusion to use the Debugger

Before you use the Debugger, ensure the following:

• A server is associated with the project or the project containing the files that you want to debug.

• RDS is enabled on the ColdFusion server, and you have specified the correct RDS configuration information in ColdFusion Builder.

• Debugging is enabled in ColdFusion Administrator.

Set up debugging for J2EE configuration of ColdFusion

Specify debugger settings in ColdFusion Builder

Debugging your application

After you enabled the debugger in the ColdFusion Administrator and configured the debugger in ColdFusion Builder, you can debug projects in ColdFusion Builder.

Create or edit launch configurations

When you debug a project in your application, ColdFusion Builder creates a project-specific launch configuration for the first time that you debug. The launch configuration automatically defines a project name (based on the project that you are debugging), main application file, and the path to debug the application.

Launch configurations are managed through the Create, Manage, and Run Configurations dialog box.

Debug configuration

You can edit the default launch configuration that ColdFusion Builder creates.

Run the application

Run the application that you want to debug before setting any breakpoints. Running the application before debugging compiles the application and improves performance during debugging.

The application is run in your computer’s default browser. To specify a different external browser, do as follows:

• (Windows) Right-click the project and select Properties. Go to ColdFusion Server Settings, and select a a web browser installed on your computer.
• (Mac) In the Preferences dialog box, select General > Web Browser, and select a web browser installed on your computer.

Set and remove breakpoints

You use breakpoints to control the running of your application so you can inspect your code and debug your application. You add breakpoints in the code editor and then manage them in the Breakpoints view. You can also set breakpoints as you write code or while you debug.

For more information about managing breakpoints using the Breakpoints view, see Breakpoints view.

ColdFusion breakpoints

ColdFusion breakpoints have the following four states in the ColdFusion debugger:

• Enabled and Valid This state indicates that the breakpoint is at a valid location. The breakpoint appears as a solid blue circle in the left margin of the CFML Editor. Code execution stops when this breakpoint is encountered.
• Unresolved ColdFusion sets the breakpoint for the page that is loaded in its memory. If you modify the page and do not run it, the source is no longer in sync with the page on the server. In this situation, ColdFusion sometimes does not know whether the line where you want to set the breakpoint is valid. A question  mark   represents  this type of breakpoint.
• Invalid If ColdFusion determines that the CFML that you are editing in ColdFusion Builder is the same as the CFML in its  memory,  and that the breakpoint you have set is  at  an invalid line, the breakpoint appears as a red X.
• Disabled This state indicates that the breakpoint is disabled.

Set a breakpoint in the code editor

A blue dot appears before the line on which you set the breakpoint.

You can also view a list of breakpoints set in the current project in the Breakpoints view of the ColdFusion Builder Debugging perspective.

Skip all breakpoints in the code editor

After setting breakpoints in your code, you can ignore all breakpoints at the time of debugging.

Remove a breakpoint in the code editor

In the marker bar along the left-edge of the editor, double-click an existing breakpoint.

The breakpoint is removed from the marker bar and the Breakpoints view of the ColdFusion Builder Debugging perspective.

To remove all the breakpoints in the file, select Run > Remove all Breakpoints from the main toolbar menu.

Start a debugging session

The Debug launch configuration is automatically created and launched.

Manage the debugging session

Use the Debug view to control the debugging of the application, to suspend, resume, or terminate the application, or to step into or over code.

For information about the various views in the ColdFusion Debug perspective, see ColdFusion Debugging perspective.

Run code line by line

You can use the Step Into, Step Over, and Step Return buttons to proceed through your CFML application line by line.

For the stepping process to work properly, clear the cache of compiled classes. To do so, recompile all CFML pages compiled with an earlier version of ColdFusion.

In large files, you sometimes find that stepping and breakpoints are slow. To improve performance, do the following:

Step Into

Use Step Into for UDFs, CFCs, custom tags, and included files. Avoid using Step Into on CFML tags such as the cfset tag. Step Into is more performance intensive than Step Over. When stepping into functions, tags, and files, the file must be displayed in one of the open projects. The file that you are stepping in must be in an open project.

Step Over

Use Step Over to proceed through your CFML application, bypassing included files, such as UDFs or CFCs.

Step Return

Use Step Return to return to the original page from which you entered the included file, such as UDFs or CFCs.

Inspect variables

As you run CFML code, you can see the values and scope of variables in the Variables view. Only variables whose scopes are what you selected in the Preferences dialog box appear in the Variables view. For more information about using the Variables view, see Variables view.

Watch expressions

Watch expressions are useful to watch critical variables that sometimes go out of scope when you step into a different function. You can create your own expressions to watch and evaluate. You can modify the expressions during the debugging session.

You can do the following in the Expressions view:

• Create a watch expression by right-clicking and selecting Add Watch Expression. You can then enter the expression in the Add Watch Expression dialog box.
• Ignore a watch expression that you’ve added by right-clicking the expression and selecting Disable.
• Edit a watch expression by right-clicking the expression and selecting Edit Watch Expression. You can then modify the expression.

For more information about using the Expressions view, see Expressions view.

Debugging remote applications

If ColdFusion is running on a remote server, configure a remote server connection and specify a mapping between ColdFusion and ColdFusion Builder. Mapping ensures that ColdFusion Builder and ColdFusion are working on a copy of the same project or file.

Remote Path: Path to the project or folder on the remote ColdFusion server.

For example, if you are editing files in a ColdFusion project that points to D:\MyCoolApp and the corresponding files exist on a remote server at D:\Shared\websites\MyCoolSite. Then, create a mapping by specifying the local path as D:\MyCool App and the remote path as D:\Shared\websites\MyCoolSite.When you deploy the files to the ColdFusion server, you copy them to W:\websites\MyCoolSite\, which the ColdFusion server recognizes as D:\Shared\websites\MyCoolSite. The mapping in ColdFusion Builder specifies that the ColdFusion Builder directory is D:\MyCoolApp and the server is D:\Shared\websites\MyCoolSite. So, ColdFusion Builder translates the file path (D:\MyCoolApp\index.cfm) to a path that the ColdFusion server recognizes (D:\Shared\websites\MyCoolSite\index.cfm). To see more information about the interaction between the client and the server, add the following to the JVM arguments in the ColdFusion Administrator:

In the Navigator view, select the project or file to debug and click  in the workbench toolbar.