Gengora - Live Code Generation for VS Code

   ____
  / ___| ___ _ __   __ _  ___  _ __ __ _
 | |  _ / _ \ '_ \ / _` |/ _ \| '__/ _` |
 | |_| |  __/ | | | (_| | (_) | | | (_| |
  \____|\___|_| |_|\__, |\___/|_|  \__,_|
                   |___/
     Live Code Generation for .NET

Gengora enables live code generation with hot-reload support for .NET projects. Write your code generators in C# and see generated code update automatically as you edit.

Features

+------------------+     +------------------+     +------------------+
|   File Watcher   | --> |    Compiler      | --> |    Generator     |
|   (Hot-Reload)   |     |    (Roslyn)      |     |    (Your Code)   |
+------------------+     +------------------+     +------------------+
         |                        |                       |
         v                        v                       v
+------------------+     +------------------+     +------------------+
|  Auto-Discovery  |     |   Diagnostics    |     |  Output Files    |
|  (*.csproj)      |     |  (Problems View) |     |  (Generated)     |
+------------------+     +------------------+     +------------------+

Core Features

Feature	Description
Hot-Reload	Generators recompile and re-run automatically when source files change
Status Bar	Real-time feedback on generator state with clickable command menu
Auto-Discovery	Automatically detects generator projects marked with `<IsGeneratorProject>`
Diagnostics	Compilation errors and warnings appear in VS Code's Problems panel
Type-Safe	Full IntelliSense and compile-time checking for generator code
Multi-Platform	Works on Windows, macOS, and Linux

Problems Panel Integration

Generator diagnostics flow directly to VS Code:

+----------------+     +----------------+     +----------------+
|   Generator    | --> |    Server      | --> |    VS Code     |
|   Errors       |     |    (LSP)       |     |   Problems     |
+----------------+     +----------------+     +----------------+

Errors appear with red markers
Warnings appear with yellow markers
Click to navigate directly to the source location

Quick Start

1. Create a Generator Project

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>

    <!-- This marker tells Gengora this is a generator -->
    <IsGeneratorProject>true</IsGeneratorProject>
  </PropertyGroup>
</Project>

2. Write Your Generator

using System.Text.Json;

// Read session ID from environment (set by Gengora)
var sessionId = Environment.GetEnvironmentVariable("GENGORA_SESSION_ID")
    ?? Guid.NewGuid().ToString("N");

// Report generator start
Console.WriteLine(JsonSerializer.Serialize(new {
    type = "generator/status",
    action = "start",
    message = "Generator starting",
    session_id = sessionId,
    timestamp = DateTimeOffset.UtcNow.ToString("O")
}));

// Generate your code
var outputPath = "Generated/MyClass.cs";
await File.WriteAllTextAsync(outputPath, @"
// <auto-generated/>
namespace Generated;

public static class MyClass
{
    public static string GetTimestamp() => ""Generated at: " + DateTime.Now + @""";
}
");

// Report file emission
Console.WriteLine(JsonSerializer.Serialize(new {
    type = "generator/file",
    action = "emit",
    path = Path.GetFullPath(outputPath),
    session_id = sessionId,
    timestamp = DateTimeOffset.UtcNow.ToString("O")
}));

// Report completion
Console.WriteLine(JsonSerializer.Serialize(new {
    type = "generator/status",
    action = "complete",
    message = "Generation complete!",
    session_id = sessionId,
    timestamp = DateTimeOffset.UtcNow.ToString("O")
}));

3. Watch the Magic

+-------------------------------------------+
|  VS Code with Gengora                     |
|-------------------------------------------|
|  [zZ Gengora: Idle]                       |  <- Status bar
|                                           |
|  1. Open workspace with generator         |
|  2. Gengora detects *.csproj              |
|  3. Compiles with Roslyn                  |
|  4. Executes your generator               |
|  5. Watches for changes                   |
|  6. Hot-reloads on save                   |
|                                           |
+-------------------------------------------+

Generator State Machine

                    +-----------------+
                    |                 |
                    v                 |
+------+     +-------------+     +---------+
| Idle | --> | Generator   | --> | Compil- |
|      |     | Found       |     | ing     |
+------+     +-------------+     +---------+
                                      |
                +---------------------+
                |
                v
          +---------+     +---------+
          |  Ready  | <-> | Running |
          +---------+     +---------+
                |              |
                v              v
          +---------+     +---------+
          |  Error  | <-- | Stopped |
          +---------+     +---------+

State Icons

State	Icon	Description
Idle	`zZ`	No generator detected
GeneratorFound	`$(search)`	Generator project discovered
Compiling	`$(sync~spin)`	Building generator
Ready	`$(check)`	Generator compiled and ready
Running	`$(play)`	Generator executing
Error	`$(error)`	Compilation or runtime error
Stopped	`$(debug-stop)`	Generator manually stopped

Commands

Access commands via:

Status Bar: Click the Gengora status item
Command Palette: Ctrl+Shift+P / Cmd+Shift+P
Context Menu: Right-click in C# files

+------------------------------------------+
|  Gengora Commands                        |
|------------------------------------------|
|  $(output) Show Output                   |
|  --------------------------------------- |
|  $(play) Start Server                    |
|  $(refresh) Recompile                    |
|  $(debug-stop) Stop                      |
|  $(debug-restart) Restart                |
|  --------------------------------------- |
|  $(settings-gear) Log Level: info        |
|  $(new-folder) Create Sample             |
|  --------------------------------------- |
|  $(info) Status: Ready                   |
+------------------------------------------+

Command	Shortcut	Description
`Gengora: Show Commands`	Click status bar	Open command menu
`Gengora: Start Server`	-	Start the language server
`Gengora: Stop Generator`	-	Stop current generator
`Gengora: Recompile Generator`	-	Force recompilation
`Gengora: Restart Server`	-	Restart language server
`Gengora: Show Output`	-	Open output channel
`Gengora: Set Log Level`	-	Change log verbosity
`Gengora: Create Sample Generator`	-	Create template project

Configuration

Settings available in VS Code preferences:

{
  "gengora.autoStart": true,
  "gengora.logLevel": "info",
  "gengora.serverPath": ""
}

Setting	Type	Default	Description
`gengora.autoStart`	`boolean`	`true`	Auto-start server when workspace opens
`gengora.logLevel`	`string`	`"info"`	Logging verbosity
`gengora.serverPath`	`string`	`""`	Custom server path (empty = bundled)

Log Levels

+----------+----------------------------------------+
| Level    | Shows                                  |
+----------+----------------------------------------+
| trace    | Everything (very verbose)              |
| debug    | Debug info + info + warnings + errors  |
| info     | Info + warnings + errors               |
| warning  | Warnings + errors only                 |
| error    | Errors only                            |
+----------+----------------------------------------+

Sample Projects

Use Gengora: Create Sample Generator to scaffold:

Simple Generator

SimpleGenerator/
├── SimpleGenerator.csproj
├── Program.cs
└── README.md

Minimal generator that creates extension methods for source files.

Advanced Generator

AdvancedGenerator/
├── AdvancedGenerator.csproj
├── Program.cs
└── README.md

Roslyn-powered generator with syntax tree analysis:

Parses C# using Microsoft.CodeAnalysis
Generates With* methods for immutable updates
Works with records and classes

Protocol

Generators communicate via JSON messages to stdout:

Status Messages

{
  "type": "generator/status",
  "action": "start|complete|error",
  "message": "Human-readable message",
  "session_id": "abc123",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

File Emission

{
  "type": "generator/file",
  "action": "emit",
  "path": "/absolute/path/to/generated.cs",
  "session_id": "abc123",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Adding Files

{
  "type": "generator/file",
  "action": "add",
  "path": "/absolute/path/to/watch.cs",
  "session_id": "abc123",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Diagnostic Messages (Problems Panel)

Report an error or warning:

{
  "type": "generator/diagnostic",
  "action": "report",
  "diagnostic_id": "GEN001",
  "message": "Missing required property 'Name'",
  "severity": "error",
  "file_path": "/absolute/path/to/file.cs",
  "line": 42,
  "column": 5,
  "session_id": "abc123",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Severity values: error, warning, info, hint

Clear all diagnostics:

{
  "type": "generator/diagnostic",
  "action": "clear-all",
  "session_id": "abc123",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Use Cases

+------------------------+     +------------------------+
|  Source Files          |     |  Generated Output      |
+------------------------+     +------------------------+
|                        |     |                        |
|  - Entity classes      | --> |  - Repository layer    |
|  - DTOs                |     |  - CRUD operations     |
|  - Interfaces          |     |  - Boilerplate code    |
|                        |     |                        |
+------------------------+     +------------------------+

+------------------------+     +------------------------+
|  Configuration         |     |  Generated Output      |
+------------------------+     +------------------------+
|                        |     |                        |
|  - appsettings.json    | --> |  - Typed settings      |
|  - config.yaml         |     |  - Validation code     |
|  - schema.json         |     |  - Environment vars    |
|                        |     |                        |
+------------------------+     +------------------------+

+------------------------+     +------------------------+
|  API Specifications    |     |  Generated Output      |
+------------------------+     +------------------------+
|                        |     |                        |
|  - OpenAPI/Swagger     | --> |  - HTTP clients        |
|  - GraphQL schemas     |     |  - Request/Response    |
|  - Protobuf            |     |  - Serialization       |
|                        |     |                        |
+------------------------+     +------------------------+

Common Scenarios

Generate repository patterns from entity classes
Create strongly-typed settings from JSON configuration
Build HTTP clients from OpenAPI specifications
Generate documentation from code comments
Create test fixtures and mock data
Build mapper extensions for DTOs

Architecture

+------------------------------------------------------------------+
|                        VS Code Extension                          |
+------------------------------------------------------------------+
|                                                                   |
|  +------------------+     +------------------+     +------------+ |
|  |  Extension.ts    | <-> |  Language Client | <-> | Status Bar | |
|  |  (Entry Point)   |     |  (LSP Client)    |     | (UI)       | |
|  +------------------+     +------------------+     +------------+ |
|           |                        |                              |
|           |              +---------+---------+                    |
|           |              |                   |                    |
|           v              v                   v                    |
|  +------------------+  +--------+  +------------------+           |
|  |  Output Channel  |  | stdio  |  | Diagnostic       |           |
|  |  (Logs)          |  |        |  | Collection       |           |
|  +------------------+  +--------+  +------------------+           |
|                              |                                    |
+------------------------------------------------------------------+
                               |
                               v
+------------------------------------------------------------------+
|                      Gengora Language Server                      |
+------------------------------------------------------------------+
|                                                                   |
|  +------------------+     +------------------+     +------------+ |
|  |  LSP Server      | <-> |  Generator       | <-> | File       | |
|  |  (JSON-RPC)      |     |  Orchestrator    |     | Watcher    | |
|  +------------------+     +------------------+     +------------+ |
|                                    |                              |
|                           +--------+--------+                     |
|                           |                 |                     |
|                           v                 v                     |
|                  +------------------+  +------------------+       |
|                  |  Roslyn Compiler |  |  Generator       |       |
|                  |  (Build)         |  |  Process         |       |
|                  +------------------+  +------------------+       |
|                                                                   |
+------------------------------------------------------------------+

Requirements

Requirement	Version
VS Code	1.85+
.NET SDK	8.0+
Platform	Windows, macOS, Linux

Extension Size

Optimized for minimal footprint:

+---------------------------+
|  Package Breakdown        |
+---------------------------+
|  Extension (JS)   ~150 KB |
|  Language Server  ~2.8 MB |
|  Samples          ~40 KB  |
|  Assets           ~1.1 MB |
+---------------------------+
|  Total            ~4.1 MB |
+---------------------------+

Troubleshooting

Server Won't Start

1. Check .NET SDK is installed: dotnet --version
2. Check output channel: Gengora: Show Output
3. Verify workspace has .csproj files
4. Try restart: Gengora: Restart Server

Generator Not Detected

1. Ensure <IsGeneratorProject>true</IsGeneratorProject> in .csproj
2. Rebuild solution: dotnet build
3. Check output for discovery logs

Diagnostics Not Showing

1. Check Problems panel (Ctrl+Shift+M)
2. Verify log level is info or lower
3. Check generator outputs valid JSON

Known Limitations

Single generator project per workspace (v1)
Single workspace root supported
Requires MSBuild SDK configuration
Generator must output to stdout

Release Notes

See CHANGELOG for full version history.

Latest: 0.9.26

Added [Server] prefix to server log messages for easier debugging
Client-side log level filtering (debug messages hidden at info level)
Reduced server-side logging verbosity

Contributing

Contributions welcome! Visit our GitHub repository.

+------------------------------------------+
|  How to Contribute                       |
+------------------------------------------+
|  1. Fork the repository                  |
|  2. Create a feature branch              |
|  3. Make your changes                    |
|  4. Write/update tests                   |
|  5. Submit a pull request                |
+------------------------------------------+

Support

License

MIT License - Blue IT Systems GmbH

Notice: This software includes automatic code generation features. Use at your own risk. The licensor assumes no liability for damages arising from use of this software.

  Made with care by Blue IT Systems GmbH

  ____  _     _   _ _____
 | __ )| |   | | | | ____|
 |  _ \| |   | | | |  _|
 | |_) | |___| |_| | |___
 |____/|_____|____/|_____| IT Systems