Update roslyn-bridge skill documentation and settings
- Update SKILL.md with comprehensive WebAPI documentation: - New architecture diagram showing WebAPI middleware - Complete REST API endpoints documentation - WebAPI usage examples and best practices - Instance discovery and multi-client support - History tracking features - Updated troubleshooting guide - Update settings.local.json: - Add auto-approval for WebAPI startup commands - Add auto-approval for common build and test commands - Streamline development workflow 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -3,73 +3,122 @@ name: roslyn-bridge
|
||||
description: Use this for C# code analysis, querying .NET projects, finding symbols, getting diagnostics, or any Roslyn/semantic analysis tasks using the bridge server
|
||||
---
|
||||
|
||||
# Roslyn Bridge Testing Guide
|
||||
# Roslyn Bridge API Guide
|
||||
|
||||
Use this guide when testing or accessing the Claude Roslyn Bridge HTTP endpoints.
|
||||
Use this guide when accessing the Roslyn Bridge for C# code analysis.
|
||||
|
||||
## Server Info
|
||||
- **Base URL**: `http://localhost:59123`
|
||||
- **Endpoints**:
|
||||
- `/query` - Main query endpoint for all Roslyn operations
|
||||
- `/health` - Health check endpoint to verify server is running
|
||||
- **Method**: POST
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────┐ REST API ┌────────────────────┐ HTTP ┌─────────────────────┐
|
||||
│ Claude │ ◄─────────────────► │ Web API (:5000) │ ◄────────────► │ VS Plugin (:59123) │
|
||||
│ AI │ │ Middleware │ │ Roslyn Bridge │
|
||||
└─────────────┘ └────────────────────┘ └─────────────────────┘
|
||||
```
|
||||
|
||||
## Recommended: Web API (Port 5000)
|
||||
|
||||
**Base URL**: `http://localhost:5000`
|
||||
|
||||
The Web API provides a modern RESTful interface with:
|
||||
- Clean REST endpoints with query parameters
|
||||
- Full Swagger documentation at `/`
|
||||
- Request/response history tracking at `/api/history`
|
||||
- CORS support for web applications
|
||||
- Better error handling and logging
|
||||
|
||||
### Web API Endpoints
|
||||
|
||||
**Health & Info:**
|
||||
- `GET /api/health` - Check health of both Web API and VS plugin
|
||||
- `GET /api/health/ping` - Simple ping
|
||||
|
||||
**Roslyn Operations:**
|
||||
- `GET /api/roslyn/projects` - Get all projects
|
||||
- `GET /api/roslyn/solution/overview` - Solution statistics
|
||||
- `GET /api/roslyn/diagnostics?filePath={path}` - Get errors/warnings
|
||||
- `GET /api/roslyn/symbol?filePath={path}&line={line}&column={col}` - Get symbol info
|
||||
- `GET /api/roslyn/references?filePath={path}&line={line}&column={col}` - Find references
|
||||
- `GET /api/roslyn/symbol/search?symbolName={name}&kind={kind}` - Search symbols
|
||||
- `POST /api/roslyn/query` - Execute any query (fallback to raw queries)
|
||||
- `POST /api/roslyn/format` - Format document
|
||||
- `POST /api/roslyn/project/package/add` - Add NuGet package
|
||||
- `POST /api/roslyn/project/build` - Build project
|
||||
|
||||
**History:**
|
||||
- `GET /api/history` - All history entries
|
||||
- `GET /api/history/{id}` - Specific entry
|
||||
- `GET /api/history/recent?count=50` - Recent entries
|
||||
- `GET /api/history/stats` - Statistics
|
||||
- `DELETE /api/history` - Clear history
|
||||
|
||||
## Alternative: Direct VS Plugin Access (Port 59123)
|
||||
|
||||
**Base URL**: `http://localhost:59123`
|
||||
|
||||
Direct access to the Visual Studio plugin (use only if Web API is unavailable):
|
||||
- **Endpoints**: `/query`, `/health`
|
||||
- **Method**: POST only
|
||||
- **Content-Type**: application/json
|
||||
|
||||
## ⚠️ CRITICAL: Command Syntax Rules
|
||||
|
||||
**ALWAYS use curl with the Bash tool. NEVER pipe curl output to PowerShell.**
|
||||
|
||||
### ✅ CORRECT: Using curl with Bash tool
|
||||
### ✅ CORRECT: Using Web API (Recommended)
|
||||
|
||||
```bash
|
||||
# Test if server is running
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getprojects\"}"
|
||||
# Health check
|
||||
curl http://localhost:5000/api/health
|
||||
|
||||
# Get diagnostics
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getdiagnostics\"}"
|
||||
# Get all projects (returns full file paths)
|
||||
curl http://localhost:5000/api/roslyn/projects
|
||||
|
||||
# Get document info
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getdocument\",\"filePath\":\"C:\\\\path\\\\to\\\\file.cs\"}"
|
||||
# Get solution overview
|
||||
curl http://localhost:5000/api/roslyn/solution/overview
|
||||
|
||||
# Get symbol at position
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getsymbol\",\"filePath\":\"C:\\\\Users\\\\AJ\\\\Desktop\\\\PepLib\\\\PepLib\\\\Program.cs\",\"line\":10,\"column\":5}"
|
||||
# Get diagnostics for entire solution
|
||||
curl http://localhost:5000/api/roslyn/diagnostics
|
||||
|
||||
# Get diagnostics for specific file
|
||||
curl "http://localhost:5000/api/roslyn/diagnostics?filePath=C:/path/to/file.cs"
|
||||
|
||||
# Get symbol at position (use paths from /projects response)
|
||||
curl "http://localhost:5000/api/roslyn/symbol?filePath=C:/path/to/file.cs&line=10&column=5"
|
||||
|
||||
# Find all references
|
||||
curl "http://localhost:5000/api/roslyn/references?filePath=C:/path/to/file.cs&line=18&column=30"
|
||||
|
||||
# Search for symbols
|
||||
curl "http://localhost:5000/api/roslyn/symbol/search?symbolName=MyClass&kind=class"
|
||||
|
||||
# Get recent history
|
||||
curl http://localhost:5000/api/history/recent?count=10
|
||||
|
||||
# Get history statistics
|
||||
curl http://localhost:5000/api/history/stats
|
||||
```
|
||||
|
||||
**IMPORTANT curl syntax rules:**
|
||||
- Use `-X POST` (NOT `-Method POST`)
|
||||
- Use `-H` for headers (NOT `-Headers`)
|
||||
- Use `-d` for data (NOT `-Body`)
|
||||
- Escape backslashes in file paths: `\\\\` becomes `\\` in JSON
|
||||
- For GET requests, no `-X GET` needed
|
||||
- Use quotes around URLs with query parameters
|
||||
- Forward slashes `/` work in file paths (Windows accepts both `/` and `\`)
|
||||
- **DO NOT pipe to PowerShell** - the JSON output is already formatted
|
||||
|
||||
### ❌ WRONG: DO NOT DO THIS
|
||||
### Using Direct VS Plugin Access (Fallback)
|
||||
|
||||
```bash
|
||||
# NEVER pipe curl to PowerShell - this will fail on Windows
|
||||
curl ... | powershell -Command "$json = $input | ..." # ❌ WRONG
|
||||
# Health check - verify VS plugin is running
|
||||
curl -X POST http://localhost:59123/health -H "Content-Type: application/json" -d "{}"
|
||||
|
||||
# Get projects via POST
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getprojects\"}"
|
||||
|
||||
# Get symbol at position
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getsymbol\",\"filePath\":\"C:\\\\path\\\\to\\\\file.cs\",\"line\":10,\"column\":5}"
|
||||
```
|
||||
|
||||
### Using PowerShell (Alternative)
|
||||
|
||||
Run these commands **directly in PowerShell**, NOT via `powershell -Command`:
|
||||
|
||||
```powershell
|
||||
# Test server
|
||||
$body = @{queryType='getprojects'} | ConvertTo-Json
|
||||
Invoke-RestMethod -Uri 'http://localhost:59123/query' -Method Post -Body $body -ContentType 'application/json'
|
||||
|
||||
# Get document
|
||||
$body = @{
|
||||
queryType='getdocument'
|
||||
filePath='C:\path\to\file.cs'
|
||||
} | ConvertTo-Json
|
||||
Invoke-RestMethod -Uri 'http://localhost:59123/query' -Method Post -Body $body -ContentType 'application/json'
|
||||
```
|
||||
|
||||
**IMPORTANT PowerShell rules:**
|
||||
- Run directly in PowerShell console, NOT via `bash -c` or `powershell -Command`
|
||||
- Use single quotes around URI and content type
|
||||
- File paths don't need escaping in PowerShell hash tables
|
||||
**Note:** In POST requests to VS plugin, escape backslashes: `\\\\` becomes `\\` in JSON
|
||||
|
||||
## Quick Reference: All Endpoints
|
||||
|
||||
@@ -115,82 +164,104 @@ Invoke-RestMethod -Uri 'http://localhost:59123/query' -Method Post -Body $body -
|
||||
| `restorepackages` | `projectName` | - | Restore NuGet packages |
|
||||
| `createdirectory` | `directoryPath` | - | Create a new directory |
|
||||
|
||||
## Common Test Examples
|
||||
## Common Workflow Examples
|
||||
|
||||
### Typical Code Analysis Workflow
|
||||
|
||||
```bash
|
||||
# Health check - verify server is running
|
||||
curl -X POST http://localhost:59123/health -H "Content-Type: application/json" -d "{}"
|
||||
# Step 1: Check if services are healthy
|
||||
curl http://localhost:5000/api/health
|
||||
|
||||
# Get all projects in solution
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getprojects\"}"
|
||||
# Step 2: Get all projects and their files
|
||||
curl http://localhost:5000/api/roslyn/projects
|
||||
# Response includes: {"data": [{"documents": ["C:/Full/Path/To/File.cs", ...]}]}
|
||||
|
||||
# Get solution overview
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getsolutionoverview\"}"
|
||||
# Step 3: Use the full paths from Step 2 in subsequent queries
|
||||
FILE="C:/Users/AJ/Desktop/MyProject/Program.cs"
|
||||
|
||||
# Get diagnostics for entire solution
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getdiagnostics\"}"
|
||||
# Get diagnostics (errors/warnings) for a file
|
||||
curl "http://localhost:5000/api/roslyn/diagnostics?filePath=$FILE"
|
||||
|
||||
# Get semantic model for a file
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getsemanticmodel\",\"filePath\":\"C:\\\\path\\\\to\\\\file.cs\"}"
|
||||
# Get symbol information at a specific location
|
||||
curl "http://localhost:5000/api/roslyn/symbol?filePath=$FILE&line=15&column=10"
|
||||
|
||||
# Get syntax tree for a file
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getsyntaxtree\",\"filePath\":\"C:\\\\path\\\\to\\\\file.cs\"}"
|
||||
# Find all references to that symbol
|
||||
curl "http://localhost:5000/api/roslyn/references?filePath=$FILE&line=15&column=10"
|
||||
|
||||
# Find all classes containing "Helper"
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"searchcode\",\"symbolName\":\".*Helper\",\"parameters\":{\"scope\":\"classes\"}}"
|
||||
# Step 4: View your query history
|
||||
curl http://localhost:5000/api/history/recent?count=5
|
||||
|
||||
# Format a document
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"formatdocument\",\"filePath\":\"C:\\\\path\\\\to\\\\file.cs\"}"
|
||||
# Step 5: Get statistics about your queries
|
||||
curl http://localhost:5000/api/history/stats
|
||||
```
|
||||
|
||||
### Advanced Query Examples
|
||||
|
||||
```bash
|
||||
# Search for all classes with "Service" in the name
|
||||
curl "http://localhost:5000/api/roslyn/symbol/search?symbolName=Service&kind=class"
|
||||
|
||||
# Get solution-wide statistics
|
||||
curl http://localhost:5000/api/roslyn/solution/overview
|
||||
|
||||
# For complex queries not available as REST endpoints, use POST /query
|
||||
curl -X POST http://localhost:5000/api/roslyn/query \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"queryType":"searchcode","symbolName":".*Controller","parameters":{"scope":"classes"}}'
|
||||
|
||||
# Build a project
|
||||
curl -X POST "http://localhost:5000/api/roslyn/project/build?projectName=MyProject"
|
||||
|
||||
# Add NuGet package
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"addnugetpackage\",\"projectName\":\"RoslynBridge\",\"packageName\":\"Newtonsoft.Json\"}"
|
||||
|
||||
# Add NuGet package with version
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"addnugetpackage\",\"projectName\":\"RoslynBridge\",\"packageName\":\"Newtonsoft.Json\",\"version\":\"13.0.3\"}"
|
||||
|
||||
# Remove NuGet package
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"removenugetpackage\",\"projectName\":\"RoslynBridge\",\"packageName\":\"Newtonsoft.Json\"}"
|
||||
|
||||
# Build project
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"buildproject\",\"projectName\":\"RoslynBridge\"}"
|
||||
|
||||
# Build with configuration
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"buildproject\",\"projectName\":\"RoslynBridge\",\"configuration\":\"Release\"}"
|
||||
|
||||
# Clean project
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"cleanproject\",\"projectName\":\"RoslynBridge\"}"
|
||||
|
||||
# Restore packages
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"restorepackages\",\"projectName\":\"RoslynBridge\"}"
|
||||
|
||||
# Create directory
|
||||
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"createdirectory\",\"directoryPath\":\"C:\\\\path\\\\to\\\\new\\\\directory\"}"
|
||||
curl -X POST "http://localhost:5000/api/roslyn/project/package/add?projectName=MyProject&packageName=Newtonsoft.Json&version=13.0.3"
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
Success:
|
||||
All endpoints return JSON in this format:
|
||||
|
||||
**Success:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Optional message",
|
||||
"data": { /* Response data */ }
|
||||
"data": { /* Response data varies by endpoint */ },
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
Error:
|
||||
**Error:**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Error message",
|
||||
"data": null
|
||||
"message": null,
|
||||
"data": null,
|
||||
"error": "Error description"
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
## Important Notes
|
||||
|
||||
- Line numbers are **1-based**
|
||||
- Column numbers are **0-based**
|
||||
- File paths in JSON need escaped backslashes: `C:\\path\\to\\file.cs`
|
||||
- All workspace modifications use VS threading model (`JoinableTaskFactory.SwitchToMainThreadAsync()`)
|
||||
- The Visual Studio extension must be running for endpoints to work
|
||||
- Line numbers are **1-based** (first line is 1)
|
||||
- Column numbers are **0-based** (first column is 0)
|
||||
- **Use full paths from `/api/roslyn/projects` response** in other endpoints
|
||||
- Forward slashes `/` work in file paths (Windows accepts both `/` and `\`)
|
||||
- Both the Web API (port 5000) and VS Plugin (port 59123) must be running
|
||||
- All workspace modifications use VS threading model
|
||||
- Request history is automatically tracked in the Web API
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"Failed to connect" error:**
|
||||
1. Check if Web API is running: `curl http://localhost:5000/api/health/ping`
|
||||
2. Check if VS Plugin is running: `curl -X POST http://localhost:59123/health -H "Content-Type: application/json" -d "{}"`
|
||||
3. Ensure Visual Studio is open with a solution loaded
|
||||
|
||||
**"vsPluginStatus": "Disconnected":**
|
||||
- The VS Plugin (port 59123) is not running
|
||||
- Open Visual Studio and ensure the RoslynBridge extension is loaded
|
||||
|
||||
**Empty or null data:**
|
||||
- Ensure you're using the correct file paths from `/api/roslyn/projects`
|
||||
- Verify line/column numbers are within the file bounds
|
||||
- Check that the file is part of the currently open VS solution
|
||||
|
||||
Reference in New Issue
Block a user