Azure / Azure/azure-dev

Enhance debugging support in extensions

Open
#5,852 0 comments 0 reactions 0 assignees View on GitHub
area/extensions feature
Dominant language
Go
Stars
569
Forks
364
Avg merge
2d 19h
Merged PRs (30d)
136

Description

## Problem

Extension debugging is challenging due to the gRPC-based architecture used by the azd extension framework.

### Current Architecture

- The azd core starts a gRPC server
- Extensions are dispatched as child process invocations
- gRPC server connection details (server address, authentication token) are passed to extensions via environment variables during child process invocation
- This makes isolated debugging difficult since extensions require an active gRPC server to function

### Example Scenario

When a user runs a custom command like `azd demo my-command`:
1. azd core starts the gRPC server
2. The extension subprocess is launched with environment variables containing gRPC connection info
3. The extension connects to the gRPC server to access azd services

This tight coupling makes it difficult to debug extensions in isolation.

### Current Workaround

The best available debugging approach today:
1. Add test code in the extension that pauses execution by requesting user input
2. Run the extension command (e.g., `azd demo my-command`)
3. While paused, attach a debugger to the running process
4. Continue execution and step through the extension code

This is cumbersome and doesn't provide a good developer experience.

## Proposed Solutions

We need a more advanced developer/debug story for extension developers. Potential approaches:

1. **azd Server Mode with Externalized Configuration**
- Enable azd to run in a persistent server mode
- Externalize gRPC connection details (server address, token) to a well-known location
- Allow extensions to be launched independently while connecting to the running server
- This would enable standard debugging workflows (launch extension directly from IDE)

2. **Standalone Debugging Mode**
- Provide a mock/stub gRPC server implementation for local debugging
- Extensions could run against this mock server without requiring full azd core
- Mock server would provide canned responses for testing

3. **Dedicated Debugging Tools**
- CLI command to launch extensions in debug mode (e.g., `azd x debug `)
- Built-in support for common debugger attachment patterns
- Environment variable injection helper for manual debugging

## Acceptance Criteria

- Extension developers can debug extensions using standard IDE debugging tools
- No need for manual workarounds (pausing for debugger attachment)
- Clear documentation on debugging workflows
- Support for multiple programming languages (Go, Python, Node.js, etc.)

## Benefits

- Improved developer experience for extension authors
- Faster extension development and troubleshooting
- Lower barrier to entry for new extension developers
- Better alignment with standard debugging practices

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.