MintPlayer.Spark 11.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package MintPlayer.Spark --version 11.0.0
                    
NuGet\Install-Package MintPlayer.Spark -Version 11.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="MintPlayer.Spark" Version="11.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="MintPlayer.Spark" Version="11.0.0" />
                    
Directory.Packages.props
<PackageReference Include="MintPlayer.Spark" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add MintPlayer.Spark --version 11.0.0
                    
#r "nuget: MintPlayer.Spark, 11.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package MintPlayer.Spark@11.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=MintPlayer.Spark&version=11.0.0
                    
Install as a Cake Addin
#tool nuget:?package=MintPlayer.Spark&version=11.0.0
                    
Install as a Cake Tool

MintPlayer.Spark

A low-code .NET library for building data-driven web applications with minimal boilerplate. Spark uses a PersistentObject pattern to eliminate DTOs and repository layers, letting you focus on your domain logic.

Spark is built on RavenDB and ASP.NET Core. It auto-generates CRUD endpoints, model JSON files, and a data-driven Angular frontend from your C# entity classes. You define entities, register them in a SparkContext, and the framework takes care of REST API routing, persistence, and UI rendering.

Overview

A typical Spark application has three layers:

  1. Entity classes -- plain C# classes stored in RavenDB
  2. SparkContext -- exposes queryable collections of your entities
  3. Model JSON files -- auto-generated metadata that drives the Angular frontend

The Angular frontend reads the model JSON at runtime to render list views, detail pages, and create/edit forms -- without writing any page-specific code.

Installation

dotnet add package MintPlayer.Spark

A typical solution also references:

MintPlayer.Spark
MintPlayer.Spark.Abstractions
MintPlayer.Spark.SourceGenerators

It is common to keep entity classes in a separate library project (e.g. MyApp.Library) so they can be shared across modules.

Quick Start

Tip: For the fastest setup, use MintPlayer.Spark.AllFeatures which source-generates AddSparkFull / UseSparkFull / MapSparkFull — three calls instead of the granular setup below.

1. Configure Services

You can wire Spark up in two ways.

Reference MintPlayer.Spark.AllFeatures and use the source-generated convenience methods. The generator discovers your SparkContext, Actions, and Recipients at compile time:

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddSparkFull(builder.Configuration);     // Everything in one call

var app = builder.Build();

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseSparkFull();                                       // Middleware

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
    endpoints.MapSparkFull();                             // Map all Spark endpoints
});

app.Run();
Option B: Granular setup

If you only need a subset of features, reference individual packages and wire them up explicitly:

// Program.cs
using MyApp;
using MintPlayer.Spark;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSpark(builder.Configuration, spark =>
{
    spark.UseRavenDb();       // The store: MintPlayer.Spark.RavenDB. Or spark.UseInMemory() (MintPlayer.Spark.InMemory)
    spark.UseContext<MySparkContext>();
    spark.AddActions();       // Source-generated: registers all Actions classes
    spark.AddMessaging();     // Optional: durable message bus
    spark.AddRecipients();    // Source-generated: registers all IRecipient<T> classes
});

var app = builder.Build();

app.UseRouting();
app.UseSpark();

app.UseEndpoints(endpoints =>
{
    endpoints.MapSpark();
});

app.Run();

2. Configuration (appsettings.json)

{
  "Spark": {
    "RavenDb": {
      "Urls": ["http://localhost:8080"],
      "Database": "MyApp"
    }
  }
}

In development mode, Spark automatically creates the database if it does not exist.

Core has no database of its own: the store comes from a provider package. spark.UseRavenDb() (MintPlayer.Spark.RavenDB) reads the section above. spark.UseInMemory() (MintPlayer.Spark.InMemory) needs no server and no configuration; its data resets on restart, and it has no indexes, subscriptions or revisions, so features that need them (messaging, history, …) refuse to start on it and say why.

3. Define SparkContext

Create a context class that exposes your entity collections. Each public IQueryable<T> property defines a collection that Spark will manage:

using MyApp.Library.Entities;
using MintPlayer.Spark;

public class MySparkContext : SparkContext
{
    public IQueryable<Person> People => Session.Query<Person>();
    public IQueryable<Company> Companies => Session.Query<Company>();
}

Session is the store-neutral ISparkSession, so the same context runs on any provider.

The property names (People, Companies) are used to generate default query names (GetPeople, GetCompanies).

4. Define Entities

Each entity is a plain C# class with an Id property and public read/write properties. Spark inspects these properties to generate the model JSON.

public class Person
{
    public string? Id { get; set; }
    public string FirstName { get; set; } = string.Empty;
    public string LastName { get; set; } = string.Empty;

    [Reference(typeof(Company), "GetCompanies")]
    public string? Company { get; set; }

    public Address? Address { get; set; } // Nested object (AsDetail)
}

public class Address
{
    public string Street { get; set; } = string.Empty;
    public string City { get; set; } = string.Empty;
    public string ZipCode { get; set; } = string.Empty;
}

public class Company
{
    public string? Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public string? Website { get; set; }
    public int? EmployeeCount { get; set; }
}

Nullable properties (e.g. int?, string?) are treated as optional. Non-nullable value types (e.g. int, bool) are marked as required.

5. Synchronize Models

Run with the synchronization flag to generate JSON model files:

dotnet run --spark-synchronize-model

This creates entity definitions in App_Data/Model/ (and default queries in App_Data/Queries/) that the framework uses at runtime. See Model Synchronization below for details. The process exits after synchronization — run it again whenever you add or change entity properties.

Core Concepts

PersistentObject

The universal data container that replaces traditional DTOs. Contains an ID, type name, and a collection of attributes with their values and metadata.

SparkContext

A registry pattern (similar to EF Core's DbContext) that tracks available entity types through IQueryable<T> properties. The framework discovers entities by reflecting over these properties.

Natural IDs

By default Spark stores documents under {Collection}/{Guid}. An entity that has a real business key can derive its own id instead by implementing IHasNaturalId:

public class Car : IHasNaturalId
{
    public static string GetId(string licencePlate) => $"cars/{licencePlate.ToUpperInvariant()}";
    string IHasNaturalId.GetId() => GetId(LicencePlate);

    public string? Id { get; set; }
    public string LicencePlate { get; set; } = null!;
}

Declare the derivation twice — a static overload taking the key, and an explicit interface implementation delegating to it. The static is what callers use, because they need the id before they have a document:

var car = await session.LoadAsync<Car>(Car.GetId("1-ABC-234"));

That call is a point-load. The alternative — finding the car by querying an index on LicencePlate — is eventually consistent, so a car written moments earlier may not be found yet. Deriving the id removes that window, which is why it matters most for lookups that gate a decision rather than merely display a row.

The derivation's inputs must not change after the document exists. RavenDB has no rename: storing the entity again after the key changes writes a second document and leaves the original behind. Derive from a licence plate or an external system's key, not from a display name.

Entities that don't implement the interface are unaffected and keep the generated id.

Actions Classes

Customization interceptors for entity-specific business logic. Inherit from DefaultPersistentObjectActions<T>; for save and delete logic, implement the persistence interceptor interfaces on the same class (or on a separate interceptor class — see the interceptors guide):

public class PersonActions : DefaultPersistentObjectActions<Person>, IBeforeSave<Person>, IAfterSave<Person>
{
    public ValueTask OnBeforeSaveAsync(Person entity, SaveContext context)
    {
        if (string.IsNullOrEmpty(entity.FirstName))
            throw new SparkValidationException("FirstName is required");
        return ValueTask.CompletedTask;
    }

    public ValueTask OnAfterSaveAsync(Person entity, SaveContext context)
    {
        // After the commit: notifications, logging, etc.
        return ValueTask.CompletedTask;
    }
}

The framework owns every write (#482): it loads, maps, runs the interceptors, checks the row (WITH CHECK), writes with the expected change vector and commits once. Nothing on the Actions class can skip that.

Available hooks:

  • OnLoadAsync - Customize single entity loading
  • MapAsync(obj, existing) - Customize how the posted object maps onto the entity a save writes
  • IBeforeSave<T> / IAfterSave<T> - Pre-save validation/stamping/prompts, and post-commit follow-ups
  • IBeforeDelete<T> / IAfterDelete<T> - Pre-delete validation/prompts, and post-commit follow-ups (cancel with throw new SparkCancelException())
  • GetRowFilterAsync(string action) - Row-level security (preferred): the row rule as a Task<Expression<Func<T,bool>>?> the framework pushes into the RavenDB query, so a list over a row-scoped type reads only the caller's rows. Construction can await (fetch an allow-list); the returned expression stays synchronous and RavenDB-translatable. Return null for no restriction. Single-row checks and the create/edit write checks are derived from the same expression. The framework invokes it at most once per (type, action) per request and caches the result — awaiting I/O inside it is safe.
  • IsAllowedAsync(string action, T entity) - the row rule as a per-row predicate: a refinement of GetRowFilterAsync (both must allow) or a standalone for rules an expression can't capture. Overriding either filters lists, queries and live updates as well as single-entity reads, and a denied read is a 404 rather than a 403 so existence is not leaked. Not memoized — if it does I/O it is an N+1; put I/O-backed rules in GetRowFilterAsync.
  • GetProtectedAttributesAsync(string action, T entity) - per-viewer, per-row attribute redaction: names attributes of a row to hide from this caller (value nulled, invisible, and shielded from write-back). A dotted name ("Jobs.Salary") reaches into AsDetail children.
  • GetDefaultIncludes() - reference paths to always RavenDB-.Include() for this type (dotted JSON paths into the document; [Reference] properties are auto-included). Referenced docs then arrive in the same round-trip instead of a follow-up load. Nested paths are embedded-object only.

The defaults permit everything and redact nothing; overriding any of these is the signal that the class takes responsibility for row-level policy. See docs/guide-row-security.md for the full story — derivation rules, projection fallback, write-side WITH CHECK, the per-row can block, and the ⚠️ anonymous-read pattern where the row filter is the only gate.

Throw SparkValidationException for business-rule failures — it reaches the caller as a 400 with the standard errors envelope. Any other exception is a 500 and the message never leaves the server.

Entity Attributes

Attribute Purpose Example
[Reference] Foreign key to another entity [Reference(typeof(Company), "GetCompanies")]
[LookupReference] Reference to lookup values by type [LookupReference(typeof(CarStatus))]
[FromIndex] Links projection class to RavenDB index [FromIndex(typeof(People_Overview))]

API Endpoints

The MapSpark() extension creates these REST endpoints:

Endpoint Method Description
/spark/ GET Health check
/spark/types GET List all entity types
/spark/types/{id} GET Get entity type definition
/spark/queries GET List all queries
/spark/queries/get POST Get query definition — body: queryId
/spark/queries/execute POST Execute a query — body: queryId, skip, take, search, sortColumns, parentId, parentType
/spark/live GET/CONNECT Live updates: one multiplexed WebSocket for "live": true objects and queries (docs/guide-live-updates.md)
/spark/po/load POST Get entity — body: objectTypeId, id
/spark/po/create POST Create entity — body: objectTypeId, persistentObject
/spark/po/update POST Update entity — body: objectTypeId, id, persistentObject
/spark/po/delete POST Delete entity — body: objectTypeId, id
/spark/po/delete-many POST Delete a query selection, all or nothing — body: objectTypeId, ids, queryId, parentId, parentType
/spark/po/new POST Construct an unsaved object or AsDetail row
/spark/po/refresh POST Reshape an in-progress object after a trigger changed
/spark/po/delete-row POST Ask whether a stored AsDetail row may be removed
/spark/actions/list POST Custom actions for a type — body: objectTypeId
/spark/actions/execute POST Run a custom action — body: objectTypeId, actionName, …
/spark/program-units GET Get navigation structure
/spark/lookupref GET List lookup reference types
/spark/lookupref/{name} GET Get lookup reference values
/spark/lookupref/{name} POST Add lookup value
/spark/lookupref/{name}/{key} PUT Update lookup value
/spark/lookupref/{name}/{key} DELETE Delete lookup value

Every persistent-object, query and action path is literal — the type, the id and every parameter travel in a JSON body. Two consequences worth knowing:

  • A Raven id contains slashes and an alias may contain anything (nothing validates its character set), and neither needs escaping any more. There are no route variables for them to break.
  • ⚠️ A top-level objectTypeId is the request parameter the server authorizes against. It is not the same field as an objectTypeId nested inside persistentObject, which is part of the submitted document and is overwritten with the resolved type on the way in. A payload naming a different type changes nothing and buys no access.

Mutating endpoints require an X-XSRF-TOKEN header; the token is provided as a cookie by the UseSpark() middleware. The reads (load, queries/get, queries/execute, actions/list) do not require one despite being POSTs — the verb changed, what they do did not, and an antiforgery token protects against a cross-site request causing a change.

Every endpoint above answers Access-Control-Allow-Origin: *, so a page on another origin may read it. A cross-origin request carries no cookies, so it reads the anonymous view — the same thing any HTTP client could already fetch. To take that off an endpoint, or to opt one of your own endpoints in, see the CORS guide.

Extension Methods

Method Description
AddSparkFull(IConfiguration) AllFeatures: Registers all Spark services, actions, auth, messaging in one call
UseSparkFull() AllFeatures: Adds the Spark middleware pipeline
MapSparkFull() AllFeatures: Maps all Spark REST endpoints
AddSpark(IConfiguration, Action<ISparkBuilder>) Register Spark services, bound to the Spark configuration section
AddSpark(Action<ISparkBuilder>) Register Spark services without configuration binding
spark.AddActions() Register all entity-specific Actions classes (source-generated)
AddSparkActions<TActions, TEntity>() Register a specific Actions class
UseSpark() Add Spark middleware to the pipeline
UseSpark(Action<UseSparkOptions>) Add Spark middleware with per-app options
MapSpark() Map Spark REST endpoints
SynchronizeSparkModels<T>() Sync entity models from SparkContext
builder.SynchronizeSparkModelsIfRequested(args) Build step: sync or verify the model, then return from Main

RavenDB indexes are deployed by UseSpark() itself — there is nothing to call.

Model Synchronization

Model synchronization scans your SparkContext, inspects the entity classes, and generates JSON files under App_Data/Model/ and App_Data/Queries/.

Run the application with the --spark-synchronize-model flag:

dotnet run --spark-synchronize-model

This generates:

  • App_Data/Model/Person.json -- entity type definition with attributes, data types, and validation rules
  • App_Data/Model/Company.json -- same for Company
  • App_Data/Queries/GetPeople.json -- default query definition for People
  • App_Data/Queries/GetCompanies.json -- default query definition for Companies

The process exits after synchronization. Run it again whenever you add or change entity properties.

What Model Synchronization Does

For each IQueryable<T> property on your SparkContext:

  1. Reflects over the entity type's public properties
  2. Creates or updates App_Data/Model/{EntityName}.json with attribute definitions
  3. Generates a default query file App_Data/Queries/Get{PropertyName}.json (if it does not already exist)
  4. Preserves any manual edits to existing JSON files (labels, validation rules, ordering, tabs, groups)
  5. Detects and merges projection types (if an index-based query exists)

Customizing Generated Files

After synchronization, you can manually edit the JSON files to:

  • Add translated labels (label, description) in multiple languages
  • Add validation rules (rules array with minLength, maxLength, regex, email, url, range)
  • Change attribute ordering (order)
  • Change where an attribute is drawn (showedOn; see ShowedOn). Hiding a value from a group is a security.json deny, not a model flag
  • Mark attributes as read-only (isReadOnly)
  • Set the display attribute (displayAttribute)
  • Add tabs and groups for organizing attributes on detail pages

These manual edits are preserved when you re-run model synchronization. The synchronizer only adds and updates -- it never deletes. It does not overwrite labels, rules, or ordering.

showedOn is preserved on projected ([FromIndex]) entities too: membership in the projection is the capability to appear on the query grid, not a mandate. Synchronization derives a default when the attribute is first created, and afterwards only removes sides that become structurally impossible (for example, the Query flag when the property leaves the projection) -- it never widens a hand-trimmed value back.

A hand-set query on an attribute without [Reference] is preserved too -- it has no derivation source, so only you could have written it. A [Reference] attribute's query keeps re-deriving on every run, and removing [Reference] clears the now-stale derived value (with a console note).

Breadcrumbs are configured in the model JSON. The "breadcrumb" template on the persistent object is the display authority: literal text plus {AttributeName} placeholders; a placeholder naming a [Reference] renders the referenced entity's breadcrumb (recursively), and one naming an embedded complex property renders that type's own breadcrumb. Synchronization preserves an authored template, synthesizes a default when missing (preferring the type's [Breadcrumb]-marked property, below), and validates placeholders. The property-level [Breadcrumb] marker in C# declares "this type renders as this property" -- typically a null-safe computed property carrying [IgnoreProperty] (persisted by RavenDB, hidden from the model):

public class Address
{
    public string Street { get; set; } = "";
    public string City { get; set; } = "";

    [Breadcrumb, IgnoreProperty]
    public string Crumb => $"{Street}, {City}";
}

For a [GenerateIndex] entity with a complex-typed property of that type, the generator emits a {Name}Sort companion reading the persisted marked value, which makes the complex grid column sortable. A complex type without a marker stays stored-but-unsortable (FieldIndexing.No, warned as SPARK_INDEX_010 -- Corax refuses to index a complex object with default options, so mapping it verbatim would leave the index empty). Sorting or filtering a FieldIndexing.No field does not error; it silently returns unordered/empty results.

Renamed a SparkContext property? When exactly one query's Database.* source goes dead and exactly one property is unclaimed, synchronization retargets the existing query in place -- same id (program units keep working), authored settings intact, conventional Get{Name} names follow the rename. Anything ambiguous is warned about and left alone; a dead Database.* source is never deleted, only warned (it silently returns no rows). Custom.* queries and hand-authored indexName/useProjection are never touched.

Attributes without a CLR property

An attribute is kept even when no property matches it, so you can:

  • Add a virtual attribute by hand -- one whose value is supplied at runtime rather than read from a property.
  • Rename or remove a property without losing that attribute's id, translated label, renderer, group, editMode or rules. Previously a rename was a silent delete-and-recreate-with-defaults.

Each kept attribute is logged, so obsolete entries stay visible and you can remove them by hand:

Kept attribute 'Nickname' on 'Customer': no matching CLR property.
Remove it from the model JSON if it is obsolete.

There is deliberately no --prune-orphaned-attributes flag: nothing in the model distinguishes an attribute you authored on purpose from one left behind by a rename, so an automatic prune could only guess, and guessing wrong deletes hand-authored work silently.

A kept attribute that is isRequired will block saves, because validation runs against the model and nothing can populate it. Synchronization warns about this rather than editing your JSON. Set "isRequired": false, or remove the attribute.

The one exception to "never deletes" is [IgnoreProperty]: marking a property ignored is an explicit instruction to drop its attribute.

Computed (get-only) properties

A property with a getter and no setter becomes a read-only attribute:

public decimal Quantity { get; set; }
public decimal UnitPrice { get; set; }
public decimal Total => Quantity * UnitPrice;   // isReadOnly: true, isRequired: false

It is displayed like any other attribute and never written back. Use [IgnoreProperty] to leave one out of the model entirely.

[IgnoreProperty] vs [JsonIgnore]

They solve different problems and compose cleanly:

Effect
[IgnoreProperty] Keeps the property out of the model. Still stored in the RavenDB document.
[JsonIgnore] Keeps the property out of the document. Still appears in the model.
Both Neither persisted nor modelled.
public class Customer
{
    public string? Id { get; set; }
    public string Name { get; set; } = "";

    [IgnoreProperty]                        // stored, but not part of the model
    public string SyncEtag { get; set; } = "";

    [JsonIgnore]                            // modelled, but not stored
    public string ScratchNote { get; set; } = "";
}

[IgnoreProperty] is read by the model synchronizer and the entity mapper: the property gets no attribute, is never populated onto or read back from a PersistentObject, is not .Include()d, is not transmitted or declared writable by replication, and gets no AttributeNames constant.

[JsonIgnore] is a serialization attribute. Spark configures RavenDB with Newtonsoft's contract resolver, which honours it — but neither the synchronizer nor the mapper reads serialization attributes, so it has no effect on the model.

Ignoring an existing property is destructive. The next synchronize removes its attribute block, discarding its id, translated label, rules, renderer and group; re-adding the property later regenerates it with a new id. This is the one case where synchronization deletes anything — an attribute whose property was merely renamed or removed is kept.

JSON Model Structure

Entity Type Definition (App_Data/Model/*.json)

A generated model JSON file looks like this:

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "name": "Company",
  "description": {
    "en": "Company",
    "fr": "Entreprise",
    "nl": "Bedrijf"
  },
  "clrType": "DemoApp.Library.Entities.Company",
  "queryType": "DemoApp.Data.VCompany",
  "indexName": "Companies_Overview",
  "displayAttribute": "Name",
  "tabs": [],
  "groups": [],
  "attributes": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Name",
      "dataType": "string",
      "isRequired": true,
      "isReadOnly": false,
      "order": 1,
      "isArray": false,
      "showedOn": "Query, PersistentObject",
      "rules": [
        { "type": "minLength", "value": 2 },
        { "type": "maxLength", "value": 200 }
      ]
    }
  ]
}

Key fields:

  • id -- stable GUID for the entity type (auto-generated, preserved across syncs)
  • clrType -- the full CLR type name used for serialization/deserialization
  • queryType -- the projection type used for list queries (set when a [FromIndex] projection exists)
  • indexName -- the RavenDB index name for list queries
  • displayAttribute -- which attribute to show as the entity's display name
  • description -- translated strings for UI labels (editable after generation)

A reference attribute is represented like this:

{
  "name": "Company",
  "dataType": "Reference",
  "referenceType": "Company",
  "referenceQuery": "GetCompanies",
  "showedOn": "PersistentObject"
}

Spark Query (App_Data/Queries/*.json)

{
  "id": "880e8400-e29b-41d4-a716-446655440001",
  "name": "GetCompanies",
  "contextProperty": "Companies",
  "sortBy": "Name",
  "sortDirection": "asc"
}
  • contextProperty -- maps to the SparkContext property name
  • Labels are not in these files: they come from translations.json by convention (model.{Entity}.attributes.{Attribute}.label, queries.{Query}.label; see docs/guide-translated-strings.md, #467)
  • sortBy / sortDirection -- default sort order for list views

Program Units (App_Data/programUnits.json)

{
  "programUnitGroups": [
    {
      "name": "Master Data",
      "icon": "bi-database",
      "programUnits": [
        {
          "id": "990e8400-e29b-41d4-a716-446655440001",
          "name": "People",
          "type": "query",
          "queryId": "550e8400-e29b-41d4-a716-446655440001"
        }
      ]
    }
  ]
}

Data Types

Spark maps C# types to model data types automatically:

DataType CLR Types Description
string string Text input
number int, long Integer number input
decimal decimal, double, float Decimal number input
boolean bool Checkbox
datetime DateTime, DateTimeOffset Date and time picker
date DateOnly Date picker
guid Guid GUID input
color System.Drawing.Color Color picker
Reference string with [Reference] Lookup to another entity
AsDetail Nested object (complex class, e.g. Address) Inline nested form

ShowedOn: where an attribute is drawn

showedOn is layout: it decides where an attribute is drawn, never who may see or write it.

Value Description
Query Show only in list views
PersistentObject Show only in detail/edit views
Query, PersistentObject Show in both (default)
None Ship it on the persistent object, draw it nowhere (Vidyano's Never); synchronize keeps it

There is no isVisible (removed in #264; a model file still saying "isVisible": false refuses startup, true is stripped by synchronize). Instead:

  • Hide a value from a group, or from everyone: a security.json attribute deny (QueryRead/Employee/Salary), on both wellKnown groups for everyone — see Authorization.
  • Protect it from writes: isReadOnly: true or an Edit/New deny. showedOn: None alone is not protection — the value is on the wire and a client can post it.
  • Show it only in some states: model None, and set the runtime attr.ShowedOn in the actions class's OnLoadAsync / OnNewAsync / OnRefreshAsync — see triggers and refresh. The client applies it from the first render.

Model files can be validated in the editor against the published JSON schemas.

Index-Based Queries

For optimized list views with projections, use RavenDB indexes:

// Projection class
[FromIndex(typeof(People_Overview))]
public class VPerson
{
    public string? Id { get; set; }
    public string FullName { get; set; } = string.Empty;
    public string? CompanyName { get; set; }
}

// Index definition
public class People_Overview : AbstractIndexCreationTask<Person>
{
    public People_Overview()
    {
        Map = people => from p in people
                        let company = LoadDocument<Company>(p.Company)
                        select new VPerson
                        {
                            Id = p.Id,
                            FullName = p.FirstName + " " + p.LastName,
                            CompanyName = company != null ? company.Name : null
                        };
    }
}

Then reference the projection in your SparkContext:

public IQueryable<VPerson> PeopleOverview => Session.Query<VPerson, People_Overview>();

Indexes need a provider with them (spark.UseRavenDb()); on UseInMemory() a model that binds one is refused at startup.

Angular Frontend

The Angular frontend uses the @mintplayer/ng-spark library, which reads entity type definitions and query definitions from the API and renders list pages, detail pages, and create/edit forms automatically.

The SPA is configured in Program.cs with the standard ASP.NET Core SPA middleware:

app.MapWhen(
    context => !context.Request.Path.StartsWithSegments("/spark"),
    appBuilder =>
    {
        appBuilder.UseSpaImproved(spa =>
        {
            spa.Options.SourcePath = "ClientApp";

            if (app.Environment.IsDevelopment())
            {
                spa.UseAngularCliServer(npmScript: "start");
            }
        });
    });

Any request that does not start with /spark is routed to the Angular application.

Project Structure

A complete Spark application typically looks like this:

MyApp/
  MyApp.Library/
    Entities/
      Company.cs
      Person.cs
      Car.cs
    LookupReferences/
      CarStatus.cs
  MyApp/
    App_Data/
      Model/
        Company.json
        Person.json
        Car.json
      Queries/
        GetCompanies.json
        GetPeople.json
        GetCars.json
    Actions/
      PersonActions.cs
    Data/
      VPerson.cs
      VCompany.cs
    Indexes/
      People_Overview.cs
      Companies_Overview.cs
    ClientApp/
      src/app/...
    MySparkContext.cs
    Program.cs
    appsettings.json

Requirements

  • .NET 10.0+ SDK
  • RavenDB 6.2+ (default: http://localhost:8080)
  • Node.js 20+ and npm (for the Angular frontend)

Next Steps

License

MIT License

Product Compatible and additional computed target framework versions.
.NET net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (18)

Showing the top 5 NuGet packages that depend on MintPlayer.Spark:

Package Downloads
MintPlayer.Spark.AllFeatures

All-in-one package for MintPlayer.Spark. References all Spark libraries and source-generates AddSparkFull/UseSparkFull/MapSparkFull convenience methods.

MintPlayer.Spark.Testing

Test harness for writing integration tests against MintPlayer.Spark apps: an embedded RavenDB driver (SparkTestDriver), an in-memory Spark host factory (SparkEndpointFactory), an antiforgery-aware HTTP client, JSON fixture seeding, index helpers, and Verify snapshot defaults.

MintPlayer.Spark.IdentityProvider

Self-contained OIDC Identity Provider for MintPlayer.Spark. Adds Authorization Code + PKCE flow with RavenDB storage. No external OIDC framework required.

MintPlayer.Spark.Controllers

MVC controller support for MintPlayer.Spark. Mounts an application's own controllers inside Spark's pipeline so they share its authentication, authorization and antiforgery rules, and ships the SPARK010 analyzer that reports a bare MapControllers() call.

MintPlayer.Spark.Moderation

Community moderation for MintPlayer.Spark: votes and a reputation ledger on IModeratable entities, privileges earned as security.json groups (bounded to reversible rights), ten vote-fraud defences (age and activity gates, diversity, eligibility, caps, delayed crediting, a nightly detector with compensating reversals, hashed network observations), flags and a review queue, locks, suspensions and an audit log. Configured through moderation.json layered under IConfiguration.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
11.1.0 135 11/18/2026
11.0.0 168 11/16/2026
11.0.0-preview.125 114 11/12/2026
11.0.0-preview.124 110 11/11/2026
11.0.0-preview.123 115 11/7/2026
11.0.0-preview.122 116 11/7/2026
11.0.0-preview.121 114 11/6/2026
11.0.0-preview.120 120 11/5/2026
11.0.0-preview.119 119 11/5/2026
11.0.0-preview.118 117 11/5/2026
11.0.0-preview.117 123 11/4/2026
11.0.0-preview.116 129 10/30/2026
11.0.0-preview.115 121 10/24/2026
11.0.0-preview.114 112 10/24/2026
11.0.0-preview.113 79 10/23/2026
11.0.0-preview.112 80 10/17/2026
11.0.0-preview.111 80 10/16/2026
11.0.0-preview.109 73 10/15/2026
11.0.0-preview.108 69 10/15/2026
11.0.0-preview.107 79 10/15/2026
Loading failed