MintPlayer.Spark
11.1.0
dotnet add package MintPlayer.Spark --version 11.1.0
NuGet\Install-Package MintPlayer.Spark -Version 11.1.0
<PackageReference Include="MintPlayer.Spark" Version="11.1.0" />
<PackageVersion Include="MintPlayer.Spark" Version="11.1.0" />
<PackageReference Include="MintPlayer.Spark" />
paket add MintPlayer.Spark --version 11.1.0
#r "nuget: MintPlayer.Spark, 11.1.0"
#:package MintPlayer.Spark@11.1.0
#addin nuget:?package=MintPlayer.Spark&version=11.1.0
#tool nuget:?package=MintPlayer.Spark&version=11.1.0
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:
- Entity classes -- plain C# classes stored in RavenDB
- SparkContext -- exposes queryable collections of your entities
- 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.AllFeatureswhich source-generatesAddSparkFull/UseSparkFull/MapSparkFull— three calls instead of the granular setup below.
1. Configure Services
You can wire Spark up in two ways.
Option A: AllFeatures (recommended)
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 loadingMapAsync(obj, existing)- Customize how the posted object maps onto the entity a save writesIBeforeSave<T>/IAfterSave<T>- Pre-save validation/stamping/prompts, and post-commit follow-upsIBeforeDelete<T>/IAfterDelete<T>- Pre-delete validation/prompts, and post-commit follow-ups (cancel withthrow new SparkCancelException())GetRowFilterAsync(string action)- Row-level security (preferred): the row rule as aTask<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 canawait(fetch an allow-list); the returned expression stays synchronous and RavenDB-translatable. Returnnullfor 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 ofGetRowFilterAsync(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 inGetRowFilterAsync.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
objectTypeIdis the request parameter the server authorizes against. It is not the same field as anobjectTypeIdnested insidepersistentObject, 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 rulesApp_Data/Model/Company.json-- same for CompanyApp_Data/Queries/GetPeople.json-- default query definition for PeopleApp_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:
- Reflects over the entity type's public properties
- Creates or updates
App_Data/Model/{EntityName}.jsonwith attribute definitions - Generates a default query file
App_Data/Queries/Get{PropertyName}.json(if it does not already exist) - Preserves any manual edits to existing JSON files (labels, validation rules, ordering, tabs, groups)
- 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 (
rulesarray withminLength,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 asecurity.jsondeny, 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,
editModeor 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
isRequiredwill 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/deserializationqueryType-- the projection type used for list queries (set when a[FromIndex]projection exists)indexName-- the RavenDB index name for list queriesdisplayAttribute-- which attribute to show as the entity's display namedescription-- 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.jsonby convention (model.{Entity}.attributes.{Attribute}.label,queries.{Query}.label; seedocs/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.jsonattribute deny (QueryRead/Employee/Salary), on bothwellKnowngroups for everyone — see Authorization. - Protect it from writes:
isReadOnly: trueor anEdit/Newdeny.showedOn: Nonealone 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 runtimeattr.ShowedOnin the actions class'sOnLoadAsync/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
- Reference Attributes -- link entities together with navigation properties
- Queries and Sorting -- define RavenDB indexes and sortable list views
- Authorization -- add permission-based access control
- Custom Attribute Renderers -- replace default UI rendering with custom Angular components
License
MIT License
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net11.0 is compatible. |
-
net11.0
- MintPlayer.AspNetCore.Endpoints (>= 11.4.1)
- MintPlayer.AspNetCore.SpaServices.Prerendering (>= 11.0.0)
- MintPlayer.AspNetCore.SpaServices.Xsrf (>= 11.0.0)
- MintPlayer.SourceGenerators.Attributes (>= 13.1.2)
- MintPlayer.Spark.Abstractions (>= 11.0.0)
- MintPlayer.Spark.SafeHttp (>= 11.0.0)
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 |