Siemens.AspNet.CodeRules.Cli
7.7.0
Prefix Reserved
See the version list below for details.
dotnet tool install --global Siemens.AspNet.CodeRules.Cli --version 7.7.0
dotnet new tool-manifest
dotnet tool install --local Siemens.AspNet.CodeRules.Cli --version 7.7.0
#tool dotnet:?package=Siemens.AspNet.CodeRules.Cli&version=7.7.0
nuke :add-package Siemens.AspNet.CodeRules.Cli --version 7.7.0
Siemens.AspNet.CodeRules.Cli
coderules run: the code rules of your solution from the console. Human output with clickable locations, or one JSON document for AI agents.
When: you want to run the rules without a test framework: locally before a push, in a git hook, in CI, or from an AI agent that needs machine-readable findings.
The CLI is a .NET tool (coderules). It runs the same ICodeRuleSetup as your test project, with the same engine,
but natively: no MSTest, xUnit or NUnit, no test host, its own output. You write no code.
dotnet tool install -g Siemens.AspNet.CodeRules.Cli # once
dotnet build # the code rule projects must be built
coderules run # every code rule project of the solution here (like dotnet test)
How the CLI finds the rules
┌─ source generator → one test per rule → dotnet test / Test Explorer
CodeRuleSetup ────────────┤
(your code rule project) └─ coderules run → load the built assembly → ConfigureServices() → engine → console / JSON
- Find the solution: like the dotnet CLI, a
.sln/.slnxfile, a folder with one, or the current directory. - Find the code rule projects: every project of the solution is evaluated with MSBuild
(
dotnet msbuild -getProperty, in parallel). A project with<IsCodeRuleProject>true</IsCodeRuleProject>is a code rule project. Because MSBuild evaluates it, the property counts wherever it is set: in the csproj, aDirectory.Build.props, or a package. - Load the setup: the project's built assembly (
TargetPath) is loaded in its ownAssemblyLoadContext, and its oneICodeRuleSetupis found withCodeRuleSetupLocator, the same class the test adapters use. - Run natively:
ConfigureServicesregisters the engine exactly as in the tests. Only the solution is replaced by the one the CLI was pointed at. The solution is parsed once, even with several projects.
Code rule project = the IsTestProject of code rules
| Project | IsCodeRuleProject |
IsTestProject |
Set by |
|---|---|---|---|
| Rule library: defines rules and offers them (a "rule pack") | no | no | nobody, it references only the engine contracts |
| Test project that registers rules from libraries | yes | yes | the adapter package / the test SDK |
| Test project with its own local rules (both) | yes | yes | the adapter package / the test SDK |
IsTestProject answers "does dotnet test run it?", IsCodeRuleProject answers "does coderules run it?". A runner is
both, which is intended. IsTestProject alone would not do: every unit test project of the solution would be loaded.
A rule library is never run by itself: its rules run because a code rule project registers them. So external rules run
too (AddRulePack<T>(), AddRulesFrom(...)), the library is simply in the project's output folder, and nothing runs twice.
You set nothing
The adapter packages (Siemens.AspNet.CodeRules.{MSTest,XUnit,NUnit}) contain build/<PackageId>.props, which NuGet
imports into every project with a PackageReference to the adapter:
<IsCodeRuleProject Condition="'$(IsCodeRuleProject)' == ''">true</IsCodeRuleProject>
- No analyzer or source generator needed: this is plain NuGet, the same mechanism that sets
IsTestProjectforMicrosoft.NET.Test.Sdk. .props, not.targets: it is imported before your csproj, so<IsCodeRuleProject>false</IsCodeRuleProject>in your project wins.- It is in the adapter, not in the engine package:
build/only applies to direct references, andbuildTransitive/in the engine would also mark rule libraries. - A ProjectReference does not import package files. Inside this repository the code rule projects therefore set the
property themselves (
Siemens.AspNet.Sdk.CodeRules,Siemens.AspNet.CodeRules.Samples.{MsTest,XUnit,NUnit}). It cannot be done inDirectory.Build.targets, because MSBuild evaluates properties before items, so a property cannot depend on aProjectReference. - A project without a test framework (only the engine and an
ICodeRuleSetup) sets the property itself and runs only in the CLI.
Commands
coderules run # every code rule project of the solution in the current directory
coderules run src/My.slnx # a solution file, or a folder with one solution
coderules run --project *.MsTest # only some code rule projects; '*' matches anything, repeatable
coderules run --rule RECORD_* # rules by ID pattern; repeatable
coderules run --group Controllers --tag security # by group and tag; every option is repeatable
coderules run --format ai # JSON for agents and scripts
coderules list # all rules with group, pack and tags (the code is never parsed)
coderules packs # code rule project → rule packs (with version) → rules per group
coderules run --pack <dll> # ad hoc: a rule pack without a code rule project
coderules --help # 'coderules' alone only shows the help, like 'dotnet'
Filters: values of one option are OR, different options are AND. A filter that matches nothing is an error (exit code 2),
never a green run with zero rules. list and packs take the same source options as run.
--pack: ad hoc, without a code rule project
--pack <dll> replaces the discovery: the rules of the given assembly run against the solution. Use it to try a rule
pack on any repository ("how many findings would we have?") before adding a code rule project. A pack with an
ICodeRulePack decides its rules, otherwise all public rules are taken. --pack and --project cannot be combined.
Long argument lists go into a response file: coderules run @coderules.rsp, one argument per line.
Output
Every command has --format human|ai:
- human (default): made to be read.
runprints one line per rule as soon as it has run, under a failing rule why, fix and every finding aspath:line:column(clickable in terminals and IDEs) with-current and+suggested code, and a summary.listis an aligned table,packsa tree that also warns when two projects use different versions of a pack. Colors are off when the output is redirected, withNO_COLORor with--no-color, and forced on withFORCE_COLOR. - ai: JSON, and nothing else on stdout.
runuses the schema shared with the test adapters;rerunof each result is the exact command to check a fix, e.g.coderules run --project Shop.CodeRules --rule SAMPLE_PACK_001 --format ai.
Exit codes
| Code | Meaning |
|---|---|
| 0 | every rule passed or was skipped |
| 1 | at least one rule has findings (also invalid arguments) |
| 2 | a rule could not run, or the setup is invalid: no code rule project, project not built, pack or solution not found, a filter matches nothing |
Why native and not dotnet test?
Running the code rule projects with dotnet test --filter ... would also work, and it stays the main way (Test Explorer,
CI test results). The CLI exists for what a test run cannot do:
dotnet test |
coderules |
|
|---|---|---|
| Test framework | required | none: rules are plain function calls on the engine |
| Several code rule projects | solution parsed once per project | parsed once |
| Output | per test, findings inside assert messages, TRX per project | one report: live console, or one JSON document |
| Selection | test filter, syntax differs per framework | --rule, --group, --tag, --project (tags are only known to the catalog) |
| Overview | – | list, packs |
| Rules without a test project | – | --pack |
Both run the same ICodeRuleSetup, so they cannot drift apart. On this repository both report the same result.
Rules must not depend on the test host
A rule runs in the test host and in the CLI. In the CLI, AppContext.BaseDirectory is the tool's folder, not your
repository. Find paths from the solution or the files (RepositoryPath.Relative(path)), never from the base directory or
the current directory.
The load context handles the rest of the difference: shared frameworks named in the project's .runtimeconfig.json
(e.g. Microsoft.AspNetCore.App) are loaded from the dotnet installation, and a dependency the tool also ships is taken
from the tool only when the tool's version is at least the requested one (otherwise from the project). The engine
contracts are checked separately: a project built against newer contracts than the tool fails with a clear message.
Install
dotnet tool install -g Siemens.AspNet.CodeRules.Cli # global
dotnet tool install Siemens.AspNet.CodeRules.Cli # or as local tool (dotnet-tools.json), run with 'dotnet coderules'
dotnet tool update -g Siemens.AspNet.CodeRules.Cli # newer version
The tool runs on the newest installed .NET runtime (RollForward=Major), so a rule pack built against a newer runtime
still runs.
A local build of the tool
dotnet pack src/CodeRuleEngine/Siemens.AspNet.CodeRules.Cli -c Release -o ./output -p:Version=1.1.0-local.1
dotnet tool install -g Siemens.AspNet.CodeRules.Cli --add-source ./output --version 1.1.0-local.1
With package source mapping in your nuget.config, --add-source is refused: run the install outside the repository with
a nuget.config that only has the ./output folder, and pass it with --configfile.
Related packages
| Package | Purpose |
|---|---|
Siemens.AspNet.CodeRules.MSTest / .XUnit / .NUnit |
the same rules as generated tests; referencing one makes a project a code rule project |
Siemens.AspNet.CodeRules.Contracts |
write rules and rule packs |
Siemens.AspNet.CodeRules.Engine |
ICodeRuleSetup, registration options, RuleTester<TRule> |
License
Copyright (c) Siemens AG. See LICENSE.md in the package.
| 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. |
This package has no dependencies.
## Next
First release of the `coderules` .NET tool.
- `coderules run` finds every code rule project of a solution (`IsCodeRuleProject`) and runs its `ICodeRuleSetup` natively, without a test framework; the solution is parsed once, even for several projects.
- Filters `--project`, `--rule`, `--group` and `--tag` (repeatable, `*` patterns); a filter that matches nothing is an error, never a green run.
- `coderules list` (rules with group, pack and tags) and `coderules packs` (projects, rule packs with version, rules per group).
- `--pack <dll>` runs a rule pack ad hoc against any solution, without a code rule project.
- `--format human|ai`: live console output with clickable `path:line:column` locations, or one JSON document with a `rerun` command per result.
- Exit codes 0 (passed), 1 (findings) and 2 (a rule could not run or the setup is invalid) for git hooks, CI and AI agents.