Edit

Share via

Debug Azure API Management policies in Visual Studio Code

  • Article

APPLIES TO: Developer

Policies in Azure API Management provide powerful capabilities that help API publishers address cross-cutting concerns such as authentication, authorization, throttling, caching, and transformation. Policies are a collection of statements that are executed sequentially on the request or response of an API.

This article describes how to debug API Management policies using the Azure API Management Extension for Visual Studio Code.

Prerequisites

Restrictions and limitations

  • This feature uses the built-in (service-level) all-access subscription (display name "Built-in all-access subscription") for debugging.

Important

  • API Management no longer supports subscriptions for tracing or the Ocp-Apim-Trace header.
  • To improve API security, tracing can now be enabled at the level of an individual API by obtaining a time-limited token using the API Management REST API, and passing the token in a request to the gateway. For details, see Enable tracing of an API.
  • Take care when enabling tracing, as it can expose sensitive information in the trace data. Ensure that you have appropriate security measures in place to protect the trace data.

Initiate a debugging session

  1. Launch Visual Studio Code
  2. Navigate to the API Management extension under Azure extensions
  3. Find the API Management instance to debug
  4. Find the API and operation to debug
  5. Right click on the operation and select Start policy debugging

At this point, the extension will try to initiate and establish a debugging session with the API Management gateway.

initiate debugging

Send a test request

When the debugging session is established, the extension will open a new editor that allows us to create and send a test HTTP request to this operation leveraging the REST Client extension.

You will notice the Ocp-Apim-Debug header has already been added to the request. This header is required and the value must be set to the service-level, all-access subscription key to trigger the debugging functionality in the API Management gateway.

Modify the HTTP request in the editor according to your test scenario. Then click send request to send the test request to the API Management gateway.

send a test request

Debug policies

After the test HTTP request is sent, the extension will open the debugging window showing the effective policies of this operation and stop at the first effective policy.

debug policies

To follow the policy pipeline, you can single-step through individual policies or set a breakpoint at a policy and step directly to that policy.

In the Variables panel, you can inspect values of system-created and user-created variables. In the Breakpoints panel, you can see the list of all breakpoints that have been set. In the Call Stack panel, you can see the current effective policy scope.

If there is an error during policy execution, you will see the details of the error at the policy where it happened.

exceptions

Tip

Remember to exit the debug session by clicking the Stop button when you are finished.

Next steps