JonjubNet.Rules 3.0.0

dotnet add package JonjubNet.Rules --version 3.0.0
                    
NuGet\Install-Package JonjubNet.Rules -Version 3.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="JonjubNet.Rules" Version="3.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="JonjubNet.Rules" Version="3.0.0" />
                    
Directory.Packages.props
<PackageReference Include="JonjubNet.Rules" />
                    
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 JonjubNet.Rules --version 3.0.0
                    
#r "nuget: JonjubNet.Rules, 3.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 JonjubNet.Rules@3.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=JonjubNet.Rules&version=3.0.0
                    
Install as a Cake Addin
#tool nuget:?package=JonjubNet.Rules&version=3.0.0
                    
Install as a Cake Tool

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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.0 50 11/18/2026
1.0.2 97 11/5/2026