SpToolkit.Generator.Cli 0.1.1

SpToolKit

SpToolKit generates strongly-typed C# wrappers around SQL Server stored procedures. You point the CLI tool at your database, it reads the procedure metadata, and emits .g.cs files with request, response, and row classes ready to use. At runtime, inject IStoredProcedureExecutor and call the generated methods — no raw ADO.NET in your application code.

How it works

SQL Server stored procedures
        │
        ▼
  sp-generate (CLI)          ← reads metadata from your database
        │
        ▼
  Generated .g.cs files      ← request/response/row classes + wrapper
        │
        ▼
  Your application code      ← call wrapper methods via IStoredProcedureExecutor

Requirements

• .NET 10 (all packages target net10.0)
• SQL Server (metadata and execution are T-SQL specific)

Installation

Install the runtime packages into your application project:

dotnet add package SpToolkit.Abstractions --version 0.1.0
dotnet add package SpToolkit.Runtime      --version 0.1.0

Install the CLI tool globally to generate code from your database:

dotnet tool install --global SpToolkit.Generator.Cli --version 0.1.0

For prerelease versions add --prerelease or pass the explicit --version string.

Getting Started

1. Create the configuration file

Copy the example config to sptoolkit.json in your project root and fill in the three required fields:

{
  "ConnectionString": "Server=localhost;Database=MyDb;User Id=...;Password=...;TrustServerCertificate=True",
  "Namespace":        "MyProject.Data.StoredProcedures",
  "OutputDirectory":  "Generated/StoredProcedures"
}

See Configuration options for the full list of settings.

2. Run the generator

sp-generate --config sptoolkit.json

The tool connects to your database, reads stored procedure signatures, and writes .g.cs files to OutputDirectory. Use --dry-run to preview the resolved configuration without touching your database or disk.

What gets generated — for a procedure dbo.SP_GET_USERS you get:

Generated/StoredProcedures/
  GetUsersRequest.g.cs      ← input parameters
  UserRow.g.cs              ← result set columns
  AppStoredProcedures.g.cs  ← wrapper class with GetUsersAsync method

3. Register in DI

In your application startup:

// Option A: own connection string
services.AddSpToolkit(opts =>
{
    opts.ConnectionString = configuration.GetConnectionString("Default");
});

// Option B: reuse an existing EF Core DbContext connection
services.AddDbContext<AppDbContext>(...);
services.AddSpToolkit<AppDbContext>();

4. Call generated methods

Inject the generated wrapper (or IStoredProcedureExecutor directly) and call the methods:

public class UserService
{
    private readonly IStoredProcedureExecutor _sp;

    public UserService(IStoredProcedureExecutor sp) => _sp = sp;

    // Query a result set
    public async Task<IReadOnlyList<UserRow>> GetUsersAsync(int maxRows)
        => await _sp.QueryAsync<GetUsersRequest, UserRow>(
               "dbo.SP_GET_USERS",
               new GetUsersRequest { MaxRows = maxRows });

    // Execute with output parameters
    public async Task<CreateUserResponse> CreateUserAsync(string name, string email)
        => await _sp.ExecuteAsync<CreateUserRequest, CreateUserResponse>(
               "dbo.SP_CREATE_USER",
               new CreateUserRequest { Name = name, Email = email });
}

Execution patterns

The generator picks the right method based on what the stored procedure returns. You can also force a pattern per-procedure in Overrides.

QuerySingle variants return TRow? (null when the SP returns no rows).
WithOutputs variants return SpResult<TData, TOutput> with .Data and .Output properties.

Configuration options

All options for sptoolkit.json with inline documentation are in the example template:

sptoolkit.example.jsonc

Quick reference:

*Required unless the equivalent CLI flag is passed (--connection, --namespace, --output).

CLI flags take precedence over the config file:

sp-generate --config sptoolkit.json --connection "Server=...;" --output ./Generated

Handling dynamic SQL

When sp_describe_first_result_set cannot infer columns (e.g. dynamic SQL), declare them manually in Overrides:

"Overrides": [
  {
    "Procedure": "dbo.SP_DynamicReport",
    "ResultColumns": ["UserId:int", "DisplayName:string", "Amount:decimal?"]
  }
]

License

See LICENSE.