SchemaCompiler

CLI-verktyg som kompilerar JSON Schema-filer till C#-klasser vid design-tid.

Översikt

SchemaCompiler är ett kommandoradsverktyg som läser *.schema.json-filer och genererar:

C#-klasser (POCO) — typade klasser med System.Text.Json-attribut
SchemaDescriptors — lättviktsmetadata för UI-rendering
SchemaRegistryProvider — fabriksklass som skapar SchemaRegistry vid appstart

Genererade filer checkas in i källkoden. Vid runtime behövs varken JSON-parsning, NJsonSchema eller Roslyn — alla tunga beroenden stannar i kompileringssteget.

Installation

SchemaCompiler är ett separat projekt i solutionfilen. Det behövs inte som NuGet-paket utan körs direkt:

Terminal

# Körs från solution-roten
dotnet run --project src/BlazorToolkit.SchemaCompiler -- <input-dir> <output-dir> [namespace]

Användning

Terminal — kompilera scheman

# Kompilera scheman i demo-projektet
dotnet run --project src/BlazorToolkit.SchemaCompiler -- ./Schemas ./Generated MyApp.Schemas

# Output:
# Compiling schemas:
#   Input:     ./Schemas
#   Output:    ./Generated
#   Namespace: MyApp.Schemas
# ...
# Done. 6 schemas compiled to ./Generated

Argument	Krävs	Beskrivning
`input-dir`	Ja	Mapp med `*.schema.json`-filer
`output-dir`	Ja	Mapp där genererade `.g.cs`-filer skrivs
`namespace`	Nej	C#-namespace (default: `BlazorToolkit.Generated`)

Arbetsflöde

Skapa eller redigera *.schema.json-filer i din schema-mapp
Kör SchemaCompiler för att generera .g.cs-filer
Checka in de genererade filerna i källkoden
Registrera SchemaRegistry vid appstart

Program.cs — registrera scheman

using BlazorToolkit.Schema;

var builder = WebApplication.CreateBuilder(args);

// Inga tunga beroenden — Create() returnerar förbyggda scheman
builder.Services.AddSingleton(SchemaRegistryProvider.Create());

Genererade filer

För varje schema-fil genereras en C#-klass. Dessutom skapas två gemensamma filer:

POCO-klass (t.ex. Person.g.cs)

Genererad C#-klass

// Auto-generated by BlazorToolkit.SchemaCompiler
namespace BlazorToolkit.Generated;

public partial class Person
{
    [System.Text.Json.Serialization.JsonPropertyName("firstName")]
    public string FirstName { get; set; }

    [System.Text.Json.Serialization.JsonPropertyName("email")]
    public string Email { get; set; }

    [System.Text.Json.Serialization.JsonPropertyName("age")]
    public int Age { get; set; }

    [System.Text.Json.Serialization.JsonPropertyName("role")]
    public PersonRole Role { get; set; }
}

SchemaDescriptors.g.cs

Statiska metoder som bygger lättviktsmetadata för varje schema. Används av UI-komponenter för att rendera formulärkontroller.

Deskriptor-exempel

// Auto-generated — lättviktsmetadata för UI-rendering
public static JsonSchemaDescriptor Person() => new()
{
    Title = "Person",
    Type = JsonFieldType.Object,
    Required = new[] { "firstName", "email" },
    Properties = new Dictionary<string, JsonSchemaDescriptor>
    {
        ["firstName"] = new() { Title = "Förnamn", Type = JsonFieldType.String, MaxLength = 100 },
        ["email"]     = new() { Title = "E-post",  Type = JsonFieldType.String, Format = "email" },
        // ...
    }
};

SchemaRegistryProvider.g.cs

Fabriksklass med en Create()-metod som returnerar en SchemaRegistry med alla kompilerade scheman.

RegistryProvider-exempel

// Auto-generated — fabrik för SchemaRegistry
public static class SchemaRegistryProvider
{
    public static SchemaRegistry Create() => new(new SchemaRegistryEntry[]
    {
        new()
        {
            Name = "person",
            Title = "Person",
            GeneratedType = typeof(Person),
            RawSchemaJson = "...",
            Descriptor = SchemaDescriptors.Person()
        },
        // ...en post per schema
    });
}

Schemafil-format

SchemaCompiler stödjer JSON Schema Draft-07. Varje fil måste ha .schema.json-ändelse.

Exempel — person.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Person",
  "description": "En person med kontaktuppgifter",
  "type": "object",
  "required": ["firstName", "email"],
  "properties": {
    "firstName": {
      "type": "string",
      "title": "Förnamn",
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "title": "E-post",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "title": "Ålder",
      "minimum": 0
    }
  }
}

Typer som stöds

JSON Schema-typ	Genererad C#-typ
`string`	`string`
`string + enum`	`enum` (genererad)
`integer`	`int`
`number`	`double`
`boolean`	`bool`
`object`	Nästlad klass
`array`	`ICollection<T>`

Arkitektur

Tunga beroenden (NJsonSchema, Roslyn) lever enbart i SchemaCompiler-projektet. Runtime-paketet BlazorToolkit.Components har inga beroenden till dessa.

Projektstruktur

BlazorToolkit.Schema.Abstractions   (lätt, inga externa beroenden)
  └── SchemaRegistry, SchemaRegistryEntry, JsonSchemaDescriptor

BlazorToolkit.SchemaCompiler         (tungt, NJsonSchema + Roslyn)
  └── Läser *.schema.json → genererar .g.cs

BlazorToolkit.Components             (UI, beror bara på Abstractions)
  └── JsonEditor, JsonViewer, XmlViewer