Skip to content

Commit d94de39

Browse files
garrytrindergarrytrinder
committed
docs: update README for clarity and improved quick start instructions
1 parent ab68471 commit d94de39

1 file changed

Lines changed: 117 additions & 85 deletions

File tree

‎README.md‎

Lines changed: 117 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,49 @@
11
# Dev Proxy Toolkit
22

3-
[Dev Proxy](https://aka.ms/devproxy) is an API simulator that helps you effortlessly test your app beyond the happy path.
3+
<!-- Update version badges when releasing: Stable = last published release, Pre-release = current manifest version -->
4+
[![Stable Version](https://img.shields.io/badge/Stable-v1.10.0-007ACC)](https://marketplace.visualstudio.com/items?itemName=garrytrinder.dev-proxy-toolkit) [![Pre-release Version](https://img.shields.io/badge/Pre--release-v1.11.0-24bfa5)](https://marketplace.visualstudio.com/items?itemName=garrytrinder.dev-proxy-toolkit) [![Visual Studio Marketplace Installs](https://img.shields.io/visual-studio-marketplace/i/garrytrinder.dev-proxy-toolkit?label=Installs)](https://marketplace.visualstudio.com/items?itemName=garrytrinder.dev-proxy-toolkit)
45

5-
The Dev Proxy Toolkit extension for Visual Studio Code makes it easy to create and update configuration files.
6+
[![Install Stable](https://img.shields.io/badge/VS%20Code-Install_Stable-007ACC?logo=visualstudiocode)](vscode:extension/garrytrinder.dev-proxy-toolkit) [![Install Pre-release](https://img.shields.io/badge/VS%20Code%20Insiders-Install_Pre--release-24bfa5?logo=visualstudiocode)](vscode-insiders:extension/garrytrinder.dev-proxy-toolkit)
67

7-
> [!IMPORTANT]
8-
>
9-
> Dev Proxy Toolkit is designed to be used with the latest version of Dev Proxy. If you are using an earlier build some features may not work as intended. You should update to the latest version.
10-
>
8+
Supercharge your [Dev Proxy](https://aka.ms/devproxy) workflow with IntelliSense, diagnostics, and one-click commands.
119

12-
## Features
13-
14-
The following sections describe the features that the extension contributes to Visual Studio Code when installed.
15-
16-
### Code Actions
10+
<!-- TODO: Add hero GIF showing extension in action -->
1711

18-
- Update schema to match installed version of Dev Proxy
19-
- Update single or all plugin paths to DevProxy.Plugins.dll
12+
## Quick Start
2013

21-
### Code Lenses
14+
1. **Install this extension** - [Install from VS Code](vscode:extension/garrytrinder.dev-proxy-toolkit). You'll be prompted to install Dev Proxy if it's not already installed.
15+
2. **Create a config** - Run `Dev Proxy Toolkit: Create configuration file` from the Command Palette
16+
3. **Configure your proxy** - Add URLs to watch and plugins using snippets (type `devproxy-`) or let [GitHub Copilot help](#mcp-server)
17+
4. **Start Dev Proxy** - Run `Dev Proxy Toolkit: Start` from the Command Palette
2218

23-
- Plugin documentation link
19+
## Features
2420

2521
### Commands
2622

27-
- `Dev Proxy Toolkit: Start` - Only available when Dev Proxy is not running
28-
- `Dev Proxy Toolkit: Stop` - Only available when Dev Proxy is running
29-
- `Dev Proxy Toolkit: Restart` - Only available when Dev Proxy is running
30-
- `Dev Proxy Toolkit: Raise mock request` - Only available when Dev Proxy is running
31-
- `Dev Proxy Toolkit: Start recording` - Only available when Dev Proxy is running
32-
- `Dev Proxy Toolkit: Stop recording`- Only available when Dev Proxy is recording
33-
- `Dev Proxy Toolkit: Open configuration file`- Only available when Dev Proxy is installed
34-
- `Dev Proxy Toolkit: Create configuration file`- Only available when Dev Proxy is installed
35-
- `Dev Proxy Toolkit: Discover URLs to watch` - Only available when Dev Proxy is not running
36-
- `Dev Proxy Toolkit: Generate JWT` - Only available when Dev Proxy is installed
37-
38-
### Diagnostics
39-
40-
- Check for missing `configSection` property in plugin instance for plugins that require configuration
41-
- Check for missing `configSection` when defined in plugin instance
42-
- Check that schema matches installed version of Dev Proxy
43-
- Check that reporters are placed after plugins
44-
- Check that at least one plugin is enabled
45-
- Check that a plugin can be configured with a configSection
46-
- Check for configSections that are not used in plugins
47-
- Check for reporter plugin when a summary plugin is used
48-
- Check that ApiCenterOnboardingPlugin is placed after OpenApiSpecGeneratorPlugin
49-
- Check that pluginPath in plugin instance is correctly set to DevProxy.Plugins.dll when using Dev Proxy v0.29.0 or later
50-
51-
### Editor Actions
52-
53-
Shown when the active document is a Dev Proxy configuration file
54-
55-
- Start Dev Proxy
56-
- Stop Dev Proxy
57-
- Raise mock request
58-
- Start recording
59-
- Stop recording
60-
61-
### MCP Server
23+
Control Dev Proxy directly from VS Code via the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`).
24+
25+
| Command | When Available |
26+
|---------|----------------|
27+
| Start | Dev Proxy not running |
28+
| Stop | Dev Proxy running |
29+
| Restart | Dev Proxy running |
30+
| Raise mock request | Dev Proxy running |
31+
| Start recording | Dev Proxy running |
32+
| Stop recording | Dev Proxy recording |
33+
| Open configuration file | Dev Proxy installed |
34+
| Create configuration file | Dev Proxy installed |
35+
| Discover URLs to watch | Dev Proxy not running |
36+
| Generate JWT | Dev Proxy installed |
6237

63-
See [Dev Proxy MCP Server](https://github.com/dev-proxy-tools/mcp) for more information on available tools.
64-
65-
### Notifications
66-
67-
- Not installed
68-
- New version detection
69-
- Upgrade Dev Proxy
70-
71-
### Problem Watcher
72-
73-
- `$devproxy-watch` - Used for background tasks to tell VS Code when Dev Proxy has started
74-
75-
### Settings
38+
### Snippets
7639

77-
- `dev-proxy-toolkit.version` - Determines the version to use when Dev Proxy and Dev Proxy Beta are installed side by side. Can be `stable` (default) or `beta`.
78-
- `dev-proxy-toolkit.newTerminal` - Determines if Dev Proxy should be started in a new terminal. Can be `true` (default) or `false`.
79-
- `dev-proxy-toolkit.showTerminal` - Determines if the terminal should be shown when Dev Proxy is started. Can be `true` (default) or `false`.
80-
- `dev-proxy-toolkit.closeTerminal` - Determines if the terminal should be closed when Dev Proxy is stopped. Can be `true` (default) or `false`.
81-
- `dev-proxy-toolkit.apiPort` - Determines the port to use to communicate with Dev Proxy API. Default is `8897`.
40+
Type `devproxy-` to access 80+ snippets:
8241

83-
### Snippets
42+
- **JSON** - Config files, plugins, mocks, and more
43+
- **YAML** - GitHub Actions workflow steps
8444

85-
#### JSON
45+
<details>
46+
<summary><strong>JSON Snippets</strong> (click to expand)</summary>
8647

8748
| Prefix | Description |
8849
| ------ | ----------- |
@@ -136,7 +97,7 @@ See [Dev Proxy MCP Server](https://github.com/dev-proxy-tools/mcp) for more info
13697
| `devproxy-plugin-graph-random-error` | GraphRandomErrorPlugin instance |
13798
| `devproxy-plugin-graph-random-error-config` | GraphRandomErrorPlugin config section |
13899
| `devproxy-plugin-graph-sdk-guidance` | GraphSdkGuidancePlugin instance |
139-
| `devproxy-plugin-graph-select-guidance` | GraphSdkGuidancePlugin instance |
100+
| `devproxy-plugin-graph-select-guidance` | GraphSelectGuidancePlugin instance |
140101
| `devproxy-plugin-har-generator` | HarGeneratorPlugin instance |
141102
| `devproxy-plugin-har-generator-config` | HarGeneratorPlugin config section |
142103
| `devproxy-plugin-http-file-generator` | HttpFileGeneratorPlugin instance |
@@ -154,8 +115,8 @@ See [Dev Proxy MCP Server](https://github.com/dev-proxy-tools/mcp) for more info
154115
| `devproxy-plugin-minimal-permissions-guidance` | MinimalPermissionsGuidancePlugin instance |
155116
| `devproxy-plugin-minimal-permissions-guidance-config` | MinimalPermissionsGuidancePlugin config section |
156117
| `devproxy-plugin-mock-generator` | MockGeneratorPlugin instance |
157-
| `devproxy-plugin-mock-request` | MockResponsePlugin instance |
158-
| `devproxy-plugin-mock-request-config` | MockResponsePlugin config section |
118+
| `devproxy-plugin-mock-request` | MockRequestPlugin instance |
119+
| `devproxy-plugin-mock-request-config` | MockRequestPlugin config section |
159120
| `devproxy-plugin-mock-response` | MockResponsePlugin instance |
160121
| `devproxy-plugin-mock-response-config` | MockResponsePlugin config section |
161122
| `devproxy-plugin-mock-response-schema` | MockResponsePlugin schema |
@@ -171,7 +132,7 @@ See [Dev Proxy MCP Server](https://github.com/dev-proxy-tools/mcp) for more info
171132
| `devproxy-plugin-openai-usage-debugging` | OpenAIUsageDebuggingPlugin instance |
172133
| `devproxy-plugin-open-api-spec-generator` | OpenApiSpecGeneratorPlugin instance |
173134
| `devproxy-plugin-open-api-spec-generator-config` | OpenApiSpecGeneratorPlugin config section |
174-
| `devproxy-plugin-rate-limiting` | MockResponsePlugin instance |
135+
| `devproxy-plugin-rate-limiting` | RateLimitingPlugin instance |
175136
| `devproxy-plugin-rate-limiting-config` | RateLimitingPlugin config section |
176137
| `devproxy-plugin-rate-limiting-file` | Dev Proxy rate limiting file |
177138
| `devproxy-plugin-rate-limiting-file-schema` | Dev Proxy rate limiting file schema |
@@ -189,7 +150,10 @@ See [Dev Proxy MCP Server](https://github.com/dev-proxy-tools/mcp) for more info
189150
| `devproxy-task-start` | Start Dev Proxy VS Code Task |
190151
| `devproxy-task-stop` | Stop Dev Proxy VS Code Task |
191152

192-
#### YAML
153+
</details>
154+
155+
<details>
156+
<summary><strong>YAML Snippets</strong> (click to expand)</summary>
193157

194158
| Prefix | Description |
195159
| ------ | ----------- |
@@ -200,21 +164,63 @@ See [Dev Proxy MCP Server](https://github.com/dev-proxy-tools/mcp) for more info
200164
| `devproxy-action-record-stop` | GitHub Actions step: Stop Dev Proxy recording |
201165
| `devproxy-action-chromium-cert` | GitHub Actions step: Install Dev Proxy certificate for Chromium browsers |
202166

167+
</details>
168+
169+
### Diagnostics
170+
171+
Real-time validation of your configuration files. Click any diagnostic code to view [detailed documentation](https://learn.microsoft.com/microsoft-cloud/dev/dev-proxy/technical-reference/toolkit-diagnostics).
172+
173+
| Code | Description |
174+
|------|-------------|
175+
| `invalidSchema` | Schema version doesn't match installed Dev Proxy |
176+
| `invalidConfigSection` | Config section not used by any plugin |
177+
| `deprecatedPluginPath` | Using old plugin DLL path (pre-v0.29) |
178+
| `missingLanguageModel` | Plugin requires language model configuration |
179+
| `noEnabledPlugins` | No plugins are enabled |
180+
| `reporterPosition` | Reporter plugin should be last |
181+
| `summaryWithoutReporter` | Summary plugin needs a reporter |
182+
| `apiCenterPluginOrder` | OpenApiSpecGeneratorPlugin must come before ApiCenterOnboardingPlugin |
183+
| `emptyUrlsToWatch` | No URLs configured to intercept |
184+
| `pluginConfigRequired` | Plugin requires a config section |
185+
| `pluginConfigMissing` | Referenced config section doesn't exist |
186+
| `pluginConfigNotRequired` | Plugin doesn't support configuration |
187+
188+
### Quick Fixes
189+
190+
One-click fixes for common issues:
191+
192+
- **Update schema** - Match schema to installed Dev Proxy version
193+
- **Update plugin path** - Fix deprecated `dev-proxy-plugins.dll` paths (single or all at once)
194+
- **Add languageModel configuration** - Enable language model for AI plugins
195+
196+
### Code Lens
197+
198+
- **View docs** - Click plugin names to open documentation
199+
203200
### Status Bar
204201

205-
- Display installed Dev Proxy version
206-
- Display waring when Dev Proxy is not latest version
207-
- Display tick if Dev Proxy is latest version (check based on `newVersionNotification` config setting in Dev Proxy configuration file)
208-
- Display radio tower when Dev Proxy is running
209-
- Display error is Dev Proxy is not installed
210-
- Upgrade Dev Proxy progress
202+
Shows Dev Proxy status at a glance:
203+
204+
- Version number and update availability
205+
- Running state (radio tower icon when active)
206+
- Error indicator if Dev Proxy is not installed
207+
208+
## Configuration
209+
210+
| Setting | Type | Default | Description |
211+
|---------|------|---------|-------------|
212+
| `dev-proxy-toolkit.version` | `stable` \| `beta` | `stable` | Version to use when both are installed |
213+
| `dev-proxy-toolkit.newTerminal` | `boolean` | `true` | Start Dev Proxy in a new terminal |
214+
| `dev-proxy-toolkit.showTerminal` | `boolean` | `true` | Show terminal when starting |
215+
| `dev-proxy-toolkit.closeTerminal` | `boolean` | `true` | Close terminal when stopping |
216+
| `dev-proxy-toolkit.apiPort` | `number` | `8897` | Port for Dev Proxy API communication |
211217

212-
### Task Provider
218+
## Tasks
213219

214-
- Start Dev Proxy Task
215-
- Stop Dev Proxy Task
220+
Run Dev Proxy as a VS Code task for integration with build workflows.
216221

217-
Example `.vscode/tasks.json`:
222+
> [!TIP]
223+
> Use the `devproxy-task-start` and `devproxy-task-stop` snippets to quickly add tasks to your `tasks.json`.
218224
219225
```json
220226
{
@@ -235,3 +241,29 @@ Example `.vscode/tasks.json`:
235241
]
236242
}
237243
```
244+
245+
## MCP Server
246+
247+
This extension includes an MCP server for AI-assisted development. See [Dev Proxy MCP Server](https://github.com/dev-proxy-tools/mcp) for available tools.
248+
249+
## Troubleshooting
250+
251+
**Dev Proxy not detected?**
252+
- Ensure Dev Proxy is installed and available in your PATH
253+
- Check the `dev-proxy-toolkit.version` setting if you have both stable and beta installed
254+
255+
**Diagnostics not showing?**
256+
- Verify your file is recognized as a Dev Proxy config (check the status bar)
257+
- The file must be named `devproxyrc.json` or contain a valid `$schema` property
258+
259+
**Commands not available?**
260+
- Some commands are only available when Dev Proxy is running or stopped
261+
- Check the status bar to see the current state
262+
263+
## Contributing
264+
265+
Found a bug or have a feature request? [Open an issue](https://github.com/dev-proxy-tools/toolkit/issues).
266+
267+
## License
268+
269+
[MIT](LICENSE)

0 commit comments

Comments
 (0)