SpDev.Runtime 0.2.0

SpDev — Stored Procedure Development Environment for .NET

Debug SQL Server stored procedures like regular code. Edit locally, trace variables, step through execution.

SpDev intercepts EXEC statements in your .NET application, executes local .sql files instead of database procedures, and streams variable traces to VS Code for step-through debugging.

Quick Start

# Install the NuGet package
dotnet add package SpDev.Runtime

# Configure in Program.cs
builder.Services.AddSpDev(options =>
{
    options.Enabled = builder.Environment.IsDevelopment();
    options.ProcedureDirectory = "./Procedures";
    options.ConnectionString = builder.Configuration.GetConnectionString("Default");
});

# Register the interceptor with EF Core
builder.Services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(connectionString);
    options.UseSpDev(builder.Services.BuildServiceProvider());
});

Create a local procedure file ./Procedures/GetCustomerOrders.sql:

CREATE PROCEDURE GetCustomerOrders
    @CustomerId INT
AS
BEGIN
    DECLARE @CustomerName NVARCHAR(100)
    DECLARE @OrderCount INT
    
    SELECT @CustomerName = Name FROM Customers WHERE CustomerId = @CustomerId
    SELECT @OrderCount = COUNT(*) FROM Orders WHERE CustomerId = @CustomerId
    
    SELECT * FROM Orders WHERE CustomerId = @CustomerId
END

Install the VS Code extension, open the .sql file, press F5, and debug.

Features

• Local File Execution: Edit stored procedures as .sql files in your project directory
• Variable Tracing: See variable values at each statement execution
• Step-Through Debugging: F10 to step, F5 to continue, Shift+F5 to stop
• Zero Production Impact: Enabled = false by default, no overhead when disabled
• Sync Status: See which procedures have drifted from the database version
• CodeLens: "▶ Debug" button above CREATE PROCEDURE statements

Architecture

.NET Application → SpDev.Runtime → SQL Server
                      ↓
              Trace Events (HTTP)
                      ↓
              VS Code Extension
                      ↓
              Debug UI (Variables, Line Highlight)

Documentation

• Getting Started — Step-by-step from dotnet new to first debug session
• Architecture — How the interceptor, instrumenter, and executor work
• Instrumentation Rules — Where trace SELECTs are injected
• Limitations — What SpDev does NOT support (and why)
• Security — Dev-only tool, never use in production

Requirements

• .NET 8 SDK
• SQL Server 2019+ or Azure SQL Database
• VS Code 1.90+
• Node.js 18+ (for extension development)

Sample

See samples/SqlServerApi for a complete working example.

Limitations

• SQL Server only (no PostgreSQL, MySQL, SQLite)
• No nested procedure debugging (v0.2 scope)
• No dynamic SQL tracing (EXEC(@sql))
• No cross-database procedure calls
• No encrypted procedure support

See docs/limitations.md for full details.

License

MIT — See LICENSE

Contributing

Contributions welcome. Open an issue or PR on GitHub.