JonjubNet.Rules
3.0.0
dotnet add package JonjubNet.Rules --version 3.0.0
NuGet\Install-Package JonjubNet.Rules -Version 3.0.0
<PackageReference Include="JonjubNet.Rules" Version="3.0.0" />
<PackageVersion Include="JonjubNet.Rules" Version="3.0.0" />
<PackageReference Include="JonjubNet.Rules" />
paket add JonjubNet.Rules --version 3.0.0
#r "nuget: JonjubNet.Rules, 3.0.0"
#:package JonjubNet.Rules@3.0.0
#addin nuget:?package=JonjubNet.Rules&version=3.0.0
#tool nuget:?package=JonjubNet.Rules&version=3.0.0
JonjubNet.Rules
Motor de reglas para .NET 10, versión 3.0.0. Servicio singleton sin estado, sin caché, sin persistencia, sin expresiones ni aritmética.
Uso desde el Core
El Core recibe por constructor IRuleEngine y llama un único método:
RuleDocumentResult Evaluate(string rules, string data)
Recibe el documento completo de reglas y el texto de los datos. Cada llamada lee ambas entradas y evalúa todas las reglas; el componente no conserva entradas ni resultados. Leer una sola vez o persistir el resultado corresponde al Core.
RuleDocumentResult contiene Continua, RuleSetId, Version,
DefaultOutcome, Rules (árboles, operandos y salidas) y Errors.
Errors es una lista inmutable de RuleInputError(Source, Code, Path);
Source es RuleInputSource.Rules o RuleInputSource.Data.
Los códigos originales de documento, condición y datos se conservan como texto,
con la ruta original completa. Entradas inválidas, incluido texto nulo, devuelven
Continua = false, Rules vacío y los errores; no lanzan por formato inválido.
Si las reglas no se pudieron leer, el identificador del resultado es texto vacío.
Los errores de configuración son errores de arranque y se validan separadamente.
using JonjubNet.Rules.Application.Abstractions;
using JonjubNet.Rules.Application.Results;
using JonjubNet.Rules.Hosting;
// Composition root; configuration contiene la sección mostrada abajo.
services.AddJonjubRules(configuration);
// El Core recibe la misma instancia singleton mediante DI.
public sealed class CoreRules(IRuleEngine engine)
{
public RuleDocumentResult Evaluate(string reglas, string datos)
=> engine.Evaluate(reglas, datos);
}
IRuleResultWriter.Write(result) puede recibirlo el Core para serializar y
persistir por su cuenta. El JSON del resultado está en inglés, como el documento
de reglas:
{"continue":true,"ruleSetId":"ondo","rules":[
{"id":"entry","action":"enter","onUnknown":"SKIP","result":"true","matches":true,
"tree":{"path":"$.rules[0].condition","combinator":"or","result":"true","children":[
{"path":"$.rules[0].condition.rules[0]","field":"TEC0001.action","operator":"=",
"constant":{"kind":"Text","value":"VENDER"},"left":{"kind":"Text","value":"VENDER"},
"right":{"kind":"Text","value":"VENDER"},"result":"true"}]},
"outputs":{}}]}
result vale true, false o unknown. Agrega "errors" únicamente si hay
errores, con objetos {"source":"Rules","code":"InvalidText","path":"$"}.
El componente no escribe archivos ni envía el resultado.
Cambios de la 3.0.0 que rompen la 2.x: claves del JSON de salida en inglés; se
quitaron IRuleGroupReader, RuleGroupReader, RuleParseResult y
RuleDepthExceededException (ahora ArgumentOutOfRangeException);
JsonFieldSource es interno; DatePaths es una lista; los valores numéricos de
RuleParseErrorCode empiezan en 0 (los nombres no cambian).
Registro y configuración
AddJonjubRules(configuration) enlaza JonjubNet:Rules, valida con
ValidateOnStart y compone AddJonjubRulesApplication() y
AddJonjubRulesJson(). Todos los servicios se registran como singleton mediante
interfaces y tipos. Las acciones, nombres del payload y fechas proceden
de configuración; no hay nombres de negocio predeterminados en el registro.
También admite AddJonjubRules(configuration, options => ...) para ajustes
posteriores al enlace, y AddJonjubRules(section, options => ...) para enlazar
una sección con otro nombre. Las opciones se inyectan por constructor. El enlace
se genera al compilar (sin reflexión): el paquete es compatible con AOT y
trimming (IsAotCompatible).
{
"JonjubNet": {
"Rules": {
"Processing": { "EntryAction": "enter", "BlockAction": "stop" },
"Data": {
"RootPrefix": "source",
"CollectionName": "items",
"KeyProperty": "key",
"ValuesProperty": "values",
"DatePaths": []
}
}
}
}
Documento de reglas
{
"ruleSetId": "sample",
"version": "2",
"defaultOutcome": { "action": "fallback", "reason": "informational" },
"rules": [
{
"id": "r1",
"name": "Example",
"priority": 0,
"action": "enter",
"reason": "configured",
"onUnknown": "SKIP",
"condition": {
"combinator": "and",
"rules": [
{ "field": "source.enabled", "operator": "=", "value": true }
]
},
"outputs": { "selected": "item.value", "optional": "item.optional" }
}
]
}
ruleSetId y cada id deben ser textos no vacíos; los identificadores de reglas
son únicos. Se exige al menos una regla. Cada regla requiere priority entero,
action no vacía, onUnknown y condition. version, name y reason son
textos opcionales. outputs es un objeto opcional de nombre de salida a ruta
no vacía. defaultOutcome es opcional, requiere action y admite reason.
Las propiedades desconocidas se ignoran. Los errores incluyen su ruta original;
un documento inválido no entrega un RuleDocument parcial.
Los grupos admiten combinator o op con and/or sin distinguir
mayúsculas. rules y groups pueden coexistir; se recorren en ese orden.
Se exige al menos un hijo y se rechazan alias contradictorios.
Una condición binaria contiene field, operator y value.
Operadores: =, !=, >, >=, <, <=, contains.
valueSource omitido, value o constant compara una constante decimal,
booleana o de texto no vacío. valueSource: "field" compara contra otra ruta.
No se aceptan expresiones, constantes nulas, objetos ni arrays.
null y notNull son operadores unarios de react-querybuilder y no requieren
value. null es verdadero ante campo ausente o null JSON; notNull es
verdadero si el campo existe y no es nulo. Siempre devuelven True o False.
{"combinator":"and","rules":[
{"field":"REG0001.action","operator":"notNull"},
{"field":"REG0001.action","operator":"=","value":"BLOQUEAR"}
]}
Ese guardia hace falsa la regla si la acción es nula, incluso con MATCH.
Un or que solo compara la acción nula con "BLOQUEAR" resulta Unknown
y sigue bloqueando con política MATCH.
Lectura de datos y evaluación
Los datos son un array de objetos. RootPrefix prefija sus escalares;
CollectionName selecciona el array de elementos, KeyProperty los identifica
y ValuesProperty se aplana recursivamente. Por ejemplo, con la configuración
anterior [{"enabled":true,"items":[{"key":"item","values":{"value":1}}]}]
produce source.enabled, item.key, item.value y sus variantes [0]..
Las rutas distinguen mayúsculas y las duplicadas invalidan toda la entrada.
Los números son decimal, los conjuntos de textos usan comparación ordinal;
DatePaths habilita fechas ISO 8601 con offset. Nulos, números fuera de rango,
arrays mixtos y fechas inválidas quedan ausentes. Un array vacío es válido.
Se evalúan todas las reglas por prioridad ascendente y orden original en empates,
y todos sus nodos sin cortocircuitar el árbol. Ausencias o tipos incompatibles
producen Unknown en comparaciones binarias. En and domina False y en or
domina True; en otro caso se conserva Unknown. Truth es el resultado original;
Matches aplica onUnknown: MATCH acepta Unknown y SKIP lo descarta.
Las acciones de entrada siempre requieren True, incluso con MATCH.
Continua exige entrada efectiva y ausencia de bloqueo efectivo.
DefaultOutcome informa metadatos y nunca habilita la continuación.
Se resuelven Outputs solo para reglas efectivas; las salidas ausentes conservan
su ruta y IsMissing. La igualdad exige tipos iguales; el orden admite números
o fechas; contains admite texto o conjunto de textos contra texto.
Los modelos y resultados copian las colecciones públicas y son inmutables. No hay estado por evaluación compartido entre llamadas.
Sin límites
No hay límites de tamaño: ni de texto, reglas, nodos, salidas, campos, errores ni bytes del resultado. Se reportan todos los errores encontrados.
El único tope es técnico y protege la pila del proceso: RuleGroup.MaxDepth
(1.024 niveles de grupos). Un grupo más profundo devuelve TooDeep y se deja de
leer el documento. Del mismo tope sale la profundidad JSON que aceptan los dos
lectores y el escritor (2 × 1.024 + 8 niveles): todo árbol que se puede leer
también se puede escribir. Datos más profundos devuelven InvalidFormat.
Nunca se entrega un documento ni fuente parcial.
El documento se lee una sola vez por llamada: cada condición se lee del mismo JSON, sin volver a convertirla a texto.
Los errores de entrada de la evaluación permanecen en Errors. Todas las
configuraciones del registro deben ser válidas al iniciar; acciones no vacías y
distintas, nombres y rutas no vacíos.
Arquitectura
- Domain: entidades, valores y errores, sin dependencias ni JSON.
- Application: contrato
IRuleEngine, orquestación y evaluación; solo Domain y abstracciones de DI. - Infrastructure/Json: lectores y escritor; depende de Application y Domain.
- Presentation: composición DI y paquete NuGet con las cuatro DLL y sus XML.
Los demás puertos son piezas internas públicas para adaptadores de otros ensamblados; no son el contrato del Core. El escritor se mantiene disponible para persistencia a cargo del consumidor.
FieldValue ocupa 32 bytes y se compara por valor (IEquatable), sin reflexión.
Los textos de los errores de programación y de la validación de la configuración
están en recursos (.resx), no en el código. Los nombres de los códigos de error
son contrato: una prueba falla si alguien los renombra.
Verificación y benchmarks
dotnet build Tests/JonjubNet.Rules.Tests/JonjubNet.Rules.Tests.csproj --no-restore
dotnet test Tests/JonjubNet.Rules.Tests/JonjubNet.Rules.Tests.csproj --no-restore
dotnet test Tests/JonjubNet.Rules.Tests/JonjubNet.Rules.Tests.csproj --collect:"XPlat Code Coverage" --settings coverlet.runsettings
Los analizadores de .NET en modo completo (-p:AnalysisMode=All) y la
comprobación de AOT no dan avisos. CI ejecuta los benchmarks en cada cambio.
Los benchmarks existentes tienen MemoryDiagnoser y dos escenarios:
3 reglas con el payload ONDO de cuatro análisis y 500 reglas con 300 campos.
Cada medición llama únicamente a IRuleEngine.Evaluate(string, string)
resuelto por DI; preparación y validación quedan fuera de la medición.
No incluyen serialización del resultado. Se reportan tiempos en ns.
IsPackable=false; no participan en CI. La restauración y ejecución se hacen
por separado. El ejecutable mantiene los artefactos en el temporal y los elimina.
Para mantener también las salidas de compilación fuera del repositorio:
$buildRoot = Join-Path ([IO.Path]::GetTempPath()) ('JonjubRulesBuild-' + [Guid]::NewGuid().ToString('N'))
dotnet run -c Release --project Benchmarks/JonjubNet.Rules.Benchmarks --artifacts-path $buildRoot -- --filter '*'
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.Configuration.Binder (>= 10.0.5)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.5)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.