Enhance debugging support in extensions
- 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
Assessment
This issue has not been assessed yet.