Debugging macros

The macro debug allows you to analyze how the system resolves macros. If you encounter problems with macros not working correctly, the debug can help you:

  • Confirm when and where your macros are being processed
  • Identify the exact source of problems
  • Detect syntax errors

Enabling the macro debug

To use the macro debug, you need to adjust the settings in Settings -> System -> Debug:

Setting

Description

Enable macro debug

Enables macro debugging and the Macros (K#) tab in the Debug application.

Enable detailed macro debug

If enabled, the macro debug displays the results of all sub‑elements used within macro expressions. This allows you to check the exact data content of a macro’s components during each step of the resolving process.

Detailed macro debugging is highly recommended. If disabled, the debug only shows the final result of each macro.

You can enable the detailed debug only for specific expressions by adding the |(debug) parameter to the given macro.

Display macro debug on live site

If enabled, macro debug information is also displayed at the bottom of each live site page. Macro debugging must also be enabled.

Only works for Portal Engine sites. The debug cannot be displayed on the pages of MVC sites.

Debug macros resolved on UI pages

If enabled, macros resolved on the pages of the administration interface are also included in the macro debug. Macro debugging must also be enabled.

Log macros to file

If enabled, the system saves the macro debug log into the logmacros.log file in the ~\App_Data folder. Macro debugging must also be enabled.

Macro debug log length

Sets the maximum length of the macro debug log, i.e. the number of requests for which the macro debug stores information. If empty, the value of the Default log length setting is used.

Display stack information

If enabled, the system tracks the code stack when debugging macros and displays the information in the Context column.

This information is only available in the debugging UI and on the live site, not in the debug log written into the logmacros.log file.

Tip: You can also enable macro debugging through the “debug everything” settings in the All section of the Debug settings category.

Debugging macros

Limitation for MVC sites

If you have a site built using the MVC development model, the debug only includes macros resolved by the Kentico administration application. The debug cannot display macros resolved by the MVC application (for example macros in email templates that the application sends as a response to live site actions).

To access the macro debug, open the Debug application and select the Macros (K#) tab.

The log displays a list of recent page requests, along with the macros that the system resolved while processing the requests. For each macro, you can see:

  • The exact Expression

  • The Result (the value into which the system resolved the macro)

    • If detailed macro debugging is enabled, you can see the results of all sub-expressions that make up the macro.
  • An identifier of the macro’s author (the user name or identity in the macro signature)

  • The Context in which the macro was resolved

    • Click on the method to see the full stack trace.
    • If you enable the Show complete context option at the top of the interface, the stack trace is displayed for all macros.
  • The Duration of the resolving process

Viewing the macro debug log

When debugging macros, we recommend using two separate tabs or browsers to:

  • Adjust the code of your macro
  • Execute the macro by loading/refreshing the page that contains the expression or triggers the related functionality

To remove all previously logged macro debug data, click Clear debug log.