RoslynBridge/RoslynBridge.WebApi/README.md

Roslyn Bridge Web API

A modern ASP.NET Core web API that acts as middleware between Claude AI and the Roslyn Bridge Visual Studio plugin, providing RESTful access to C# code analysis capabilities.

Overview

This web API serves as a bridge between external clients (like Claude AI) and the Visual Studio Roslyn Bridge plugin. It provides:

• Modern RESTful API with comprehensive Swagger/OpenAPI documentation
• CORS-enabled for web application access
• Health monitoring for both the web API and Visual Studio plugin connection
• Simplified endpoints for common Roslyn operations
• Type-safe models with validation

Architecture

┌─────────────┐      HTTP/REST      ┌──────────────────┐      HTTP      ┌─────────────────────┐
│   Claude    │ ◄─────────────────► │  Web API (5000)  │ ◄────────────► │  VS Plugin (59123)  │
│     AI      │                     │   Middleware     │                │   Roslyn Bridge     │
└─────────────┘                     └──────────────────┘                └─────────────────────┘

Getting Started

Prerequisites

• .NET 8.0 SDK or later
• Visual Studio with Roslyn Bridge plugin running (default port: 59123)

Quick Installation

Option 1: Automated Installation

Open PowerShell as Administrator:

cd RoslynBridge.WebApi
.\install.ps1 -InstallService -StartService

This will build, publish, install as a Windows Service, and start the API automatically.

For more detailed service setup options, see SERVICE_SETUP.md.

Option 2: Development Mode

1. Start the Visual Studio plugin (it should be running on port 59123)

2. Run the Web API:

   cd RoslynBridge.WebApi
   dotnet run
   

3. Access Swagger UI:

   • Navigate to: http://localhost:5000
   • Or: https://localhost:7001 (with HTTPS)

Configuration

Edit appsettings.json to configure the connection:

{
  "RoslynBridge": {
    "BaseUrl": "http://localhost:59123",
    "TimeoutSeconds": 30
  }
}

API Endpoints

Health Endpoints

• GET /api/health - Check health status of Web API and VS plugin
• GET /api/health/ping - Simple ping endpoint

Roslyn Query Endpoints

• POST /api/roslyn/query - Execute any Roslyn query
• GET /api/roslyn/projects - Get all projects in solution
• GET /api/roslyn/solution/overview - Get solution statistics
• GET /api/roslyn/diagnostics - Get errors and warnings
• GET /api/roslyn/symbol - Get symbol information at position
• GET /api/roslyn/references - Find all references to symbol
• GET /api/roslyn/symbol/search - Search for symbols by name

Refactoring Endpoints

• POST /api/roslyn/format - Format a document
• POST /api/roslyn/project/package/add - Add NuGet package
• POST /api/roslyn/project/build - Build a project

Example Usage

Using curl

# Health check
curl http://localhost:5000/api/health

# Get all projects
curl http://localhost:5000/api/roslyn/projects

# Get solution overview
curl http://localhost:5000/api/roslyn/solution/overview

# Execute custom query
curl -X POST http://localhost:5000/api/roslyn/query \
  -H "Content-Type: application/json" \
  -d '{
    "queryType": "getsymbol",
    "filePath": "C:\\path\\to\\file.cs",
    "line": 10,
    "column": 5
  }'

# Search for symbols
curl "http://localhost:5000/api/roslyn/symbol/search?symbolName=MyClass"

# Get diagnostics
curl "http://localhost:5000/api/roslyn/diagnostics"

Using JavaScript/TypeScript

const response = await fetch('http://localhost:5000/api/roslyn/query', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    queryType: 'getprojects'
  })
});

const result = await response.json();
console.log(result.data);

Using C#

using var client = new HttpClient();
client.BaseAddress = new Uri("http://localhost:5000");

var request = new RoslynQueryRequest
{
    QueryType = "getsolutionoverview"
};

var response = await client.PostAsJsonAsync("/api/roslyn/query", request);
var result = await response.Content.ReadFromJsonAsync<RoslynQueryResponse>();

Query Types

The following query types are supported:

Code Analysis

• getprojects - Get all projects
• getdocument - Get document information
• getsymbol - Get symbol at position
• getsemanticmodel - Get semantic model
• getsyntaxtree - Get syntax tree
• getdiagnostics - Get compilation errors/warnings
• findreferences - Find all references
• findsymbol - Find symbols by name
• gettypemembers - Get type members
• gettypehierarchy - Get type hierarchy
• findimplementations - Find implementations
• getnamespacetypes - Get namespace types
• getcallhierarchy - Get call hierarchy
• getsolutionoverview - Get solution overview
• getsymbolcontext - Get symbol context
• searchcode - Search code patterns

Refactoring

• formatdocument - Format document
• organizeusings - Organize using statements
• renamesymbol - Rename symbol
• addmissingusing - Add missing using
• applycodefix - Apply code fix

Project Operations

• addnugetpackage - Add NuGet package
• removenugetpackage - Remove NuGet package
• buildproject - Build project
• cleanproject - Clean project
• restorepackages - Restore packages
• createdirectory - Create directory

Response Format

All responses follow this structure:

{
  "success": true,
  "message": "Optional message",
  "data": { ... },
  "error": null
}

Error responses:

{
  "success": false,
  "message": null,
  "data": null,
  "error": "Error description"
}

Features

CORS Support

The API is configured with CORS enabled for all origins, making it accessible from web applications.

Swagger/OpenAPI

Comprehensive API documentation is available at the root URL (/) with:

• Detailed endpoint descriptions
• Request/response models
• Try-it-out functionality
• XML documentation comments

Health Checks

Built-in health checks monitor:

• Web API service status
• Visual Studio plugin connectivity
• Request/response timing

Logging

Structured logging with different levels:

• Information: General operations
• Warning: Non-critical issues
• Error: Failed operations
• Debug: Detailed tracing (Development only)

Development

Project Structure

RoslynBridge.WebApi/
├── Controllers/
│   ├── HealthController.cs      # Health check endpoints
│   └── RoslynController.cs      # Roslyn operation endpoints
├── Models/
│   ├── RoslynQueryRequest.cs    # Request DTOs
│   ├── RoslynQueryResponse.cs   # Response DTOs
│   └── HealthCheckResponse.cs   # Health check models
├── Services/
│   ├── IRoslynBridgeClient.cs   # Client interface
│   └── RoslynBridgeClient.cs    # HTTP client implementation
├── Program.cs                    # Application configuration
├── appsettings.json             # Configuration
└── README.md                    # This file

Building

dotnet build

Running Tests

dotnet test

Publishing

dotnet publish -c Release -o ./publish

Deployment

Docker (Optional)

Create a Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 5000

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["RoslynBridge.WebApi.csproj", "./"]
RUN dotnet restore
COPY . .
RUN dotnet build -c Release -o /app/build

FROM build AS publish
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "RoslynBridge.WebApi.dll"]

Build and run:

docker build -t roslyn-bridge-api .
docker run -p 5000:5000 roslyn-bridge-api

Integration with Claude

This API is designed to work seamlessly with Claude AI for code analysis tasks:

1. Claude can query project structure
2. Analyze code for errors and warnings
3. Search for symbols and references
4. Suggest refactorings
5. Navigate code hierarchies

Example Claude prompt:

"Using the Roslyn Bridge API at http://localhost:5000,
analyze the current solution and identify any code quality issues."

Troubleshooting

Visual Studio Plugin Not Connected

Error: {"vsPluginStatus": "Disconnected"}

Solution:

1. Ensure Visual Studio is running
2. Verify Roslyn Bridge plugin is installed and active
3. Check plugin is listening on port 59123
4. Update appsettings.json if using a different port

CORS Errors

If accessing from a web app:

• Verify CORS is enabled in Program.cs
• Check browser console for specific CORS errors
• Ensure the origin is allowed

Timeout Errors

Increase timeout in appsettings.json:

{
  "RoslynBridge": {
    "TimeoutSeconds": 60
  }
}

License

This project is part of the Roslyn Bridge suite.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Support

For issues and questions:

• Check the Swagger documentation at /
• Review the logs in the console output
• Verify the Visual Studio plugin is running