Anarchy.Toolkit.Automation.Build
2.0.0
dotnet add package Anarchy.Toolkit.Automation.Build --version 2.0.0
NuGet\Install-Package Anarchy.Toolkit.Automation.Build -Version 2.0.0
<PackageReference Include="Anarchy.Toolkit.Automation.Build" Version="2.0.0" />
<PackageVersion Include="Anarchy.Toolkit.Automation.Build" Version="2.0.0" />
<PackageReference Include="Anarchy.Toolkit.Automation.Build" />
paket add Anarchy.Toolkit.Automation.Build --version 2.0.0
#r "nuget: Anarchy.Toolkit.Automation.Build, 2.0.0"
#:package Anarchy.Toolkit.Automation.Build@2.0.0
#addin nuget:?package=Anarchy.Toolkit.Automation.Build&version=2.0.0
#tool nuget:?package=Anarchy.Toolkit.Automation.Build&version=2.0.0
Anarchy.Toolkit.Automation.Build
Part of Anarchy I/O Toolkit, a .NET developer platform · Pillar: Build Ecosystem · Layer: Automation · Package catalog
Reusable Anarchy build components for .NET repositories, powered by Fallout Build.
dotnet add build/_build.csproj package Anarchy.Toolkit.Automation.Build
Implement the components appropriate to your repository on an AnarchyBuild class. For example, a package-only build can implement INuGetBuild, ILayeringBuild, IDependencyMapBuild, IDependencyUpgradeBuild and IGitHooksBuild, with an empty Artifacts collection. Use IBoilerplateBuild for scaffolding, add IApiReferenceBuild for a DocFX API reference site, or add the container (IContainerBuild, IDockerBuild) components as needed. External deployment and publication targets require their respective tools and credentials.
Fallout types in the public API
The build components intentionally expose a small set of Fallout Build types because consumers compose Fallout targets
and operate on Fallout's loaded solution model: Target, AbsolutePath, Solution, Project, GitRepository, and
DotNetVerbosity, together with Fallout's [Parameter] and [Solution] attributes. These types are part of the
Automation.Build contract, not accidental implementation details. Toolkit-owned concepts such as SolutionLayout,
Artifact, and preference values use toolkit types; adapters or wrappers would obscure the Fallout operations the
consumer needs to customize.
using Anarchy.Toolkit.Automation.Build.Component;
using Anarchy.Toolkit.Automation.Build.Core.Entity.Build;
using Anarchy.Toolkit.Automation.Build.Infrastructure.Extension;
class Build : AnarchyBuild, INuGetBuild, ILayeringBuild, IDependencyMapBuild,
IDependencyUpgradeBuild, IGitHooksBuild
{
public IReadOnlyCollection<Artifact> Artifacts => [];
public static int Main() => Execute<Build>(x => x.As<IDefaultBuild>().Clean);
}
Create Fallout's .fallout/parameters.json with the solution path, then run dotnet run --project build/_build.csproj -- --help to see targets and parameters. Layering and other toolkit preferences are optional in the solution-root .anarchy-toolkit.json (schema: anarchy-toolkit.schema.json); without overrides, the effective layering baseline is folder mode under src/Library with standard application folders and layers. Existing Fallout parameter resolution takes precedence over saved preferences, then in-code defaults. A missing file or layout mode is valid and no mode is inferred. The included scaffolding target writes its engine-owned solution setting to .fallout/parameters.json; it will not overwrite existing files.
See the Anarchy automation builds guide for component details and package publishing.
Local containers
IDockerBuild manages a local environment on a Docker Compose file (default: docker/docker-compose.yml, project named after the repository directory). It uses docker compose when available, otherwise the legacy docker-compose, and passes the compose file's directory as DOCKER_ROOT. The boilerplate's docker.mk exposes each target to Make:
| Target | Make | What it does |
|---|---|---|
DockerInfo |
docker_info |
Docker engine and Compose versions, the Compose command, and the running containers |
DockerStopAll |
docker_stopall |
Stops every container running on the host |
DockerLogs |
container_logs |
Prints the environment's logs, of DockerContainer if given |
DockerStart |
start |
up --detach --quiet-pull --remove-orphans, then waits for each DockerWaitFor container (healthy, with DockerWaitForHealthy) |
DockerStop, DockerRestart, DockerDestroy |
stop, restart, destroy |
Stop, restart (DockerContainer only, if given) or remove the environment, including its volumes |
DockerWaitRunning |
wait_running_container |
Waits up to DockerTimeout seconds (default 60) for DockerContainer to be running, then, if DockerReadinessCheck is overridden, up to DockerTimeout more for it to pass |
DockerWaitHealthy |
wait_healthy_container |
Waits up to DockerStartTimeout seconds (default 180) for it to be running, then up to DockerTimeout for its health check to pass; fails at once if it turns unhealthy or has no health check |
The waits show a progress bar on interactive terminals and plain lines otherwise (CI, redirected output).
Container images
IContainerBuild publishes a runnable app, builds its image from docker/Dockerfile by default, then pushes it to the
configured ContainerRegistry. The artifact directory defaults to artifacts/Container/<app>; use any registry the
Docker client supports. Authenticate before pushing: for ECR, run aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com; for GHCR, use
echo "$GHCR_TOKEN" | docker login ghcr.io -u <user> --password-stdin; ACR uses az acr login --name <registry>;
Docker Hub uses docker login. The toolkit does not log in or manage registry credentials.
The build targets are ContainerPublishAppArtifact, ContainerImageBuild and ContainerImagePush. Their Make wrappers
are container_publish_app_artifact, container_image_build and container_image_push (each takes APP_NAME).
For containers without a health check, override DockerReadinessCheck in the build to add your own; it is called once a second with the container's name until it returns true:
Func<string, bool>? IDockerBuild.DockerReadinessCheck => container =>
{
try { using var client = new TcpClient("localhost", 5432); return true; }
catch (SocketException) { return false; }
};
Starting from an empty folder
For a guided setup, including APIs, jobs and UIs, install the Anarchy.Toolkit.Automation.Build.Cli global tool and run anarchy-toolkit bootstrap. See the tool README. To set up the build host manually instead:
With the .NET 10 SDK, Bash and Make installed, create a build host first:
mkdir -p build .fallout
dotnet new console --framework net10.0 --name _build --output build
dotnet add build/_build.csproj package Anarchy.Toolkit.Automation.Build
printf '{}\n' > .fallout/parameters.json
Use the example above in build/Program.cs, adding IBoilerplateBuild to the class. Then generate a starter solution and try the build:
dotnet run --project build/_build.csproj -- SetupBoilerplate --boilerplate-solution-name MyApp
make compile
make check_layering
By default, scaffolding creates a solution containing the build and a starter src/Core project, along with tests/, samples/, docs/, Makefile, scripts and configuration files. It does not create an automation preferences file unless explicitly asked to save preferences. Review the supplied .NET SDK and test-runner settings and enable or adapt the optional Make targets for your build components and tools.
Choosing what to install
Use --boilerplate-items for a comma-separated allowlist and --boilerplate-exclude to remove items. Names are case-insensitive; omit the allowlist to select everything.
| Item | Effect |
|---|---|
solution |
Create the named .sln, add the existing build and selected Core project, and set Solution in .fallout/parameters.json. Requires --boilerplate-solution-name. |
core |
Create src/Core/Core.csproj. Add it to a solution yourself if solution is excluded. |
tests, samples, docs |
Create the directory and its .gitkeep. |
Makefile, .gitignore, .editorconfig, global.json, nuget.config |
Install the corresponding packaged file. |
Directory.Build.props |
Create the SQL resource embedding rule if the file is absent. |
scripts |
Install all scripts; individual paths such as scripts/build.anarchy.sh or scripts/bootstrap can also be selected or excluded. |
skills |
Install the toolkit's agent skills into .agents/skills (see Agent skills). Opt-in: all leaves them out. |
all selects every item except skills, and none selects nothing. Unknown names fail before any files are written. When selecting individual scripts, include their helpers: the launcher needs scripts/shared/colors.env, scripts/console/subtitle.sh and, unless environment reloading is disabled, scripts/bootstrap/shell-profile-path.sh.
Existing .gitignore and .editorconfig files are untouched unless --append-existing (or --apend-existing) is supplied. The packaged content then goes into a managed block between # >>> anarchy-toolkit and # <<< anarchy-toolkit lines: a later run replaces that block with the current packaged settings, and never touches the lines outside it, where the repository keeps its own entries. In .gitignore, the block leaves out the entries the file already has. Whenever it writes a .gitignore, the target warns about files Git tracks that the new rules ignore, so you can untrack them or add a ! exception below the block. In .editorconfig, override a setting by repeating its section below the block (for example [*.cs] then dotnet_diagnostic.S8970.severity = none): later entries win, so the toolkit owns the block and the repository owns its exceptions. Review the result because later rules can change earlier ones. The same option adds the packaged test section ("runner": "Microsoft.Testing.Platform", which dotnet test needs to run xUnit.net v3 projects) to an existing global.json that does not have one; the rest of the file is kept, and a file with comments is left alone. Existing nuget.config and Directory.Build.props are always preserved, as is global.json otherwise. The target refuses to overwrite a solution, selected script, Makefile, starter project, .gitkeep or existing Solution parameter. If an operation fails partway through, inspect the output before retrying.
To look before writing, --boilerplate-dry-run (make boilerplate DRY_RUN=true) only logs what the target would create, keep or update (with the managed block's diff) and which files conflict. DiffBoilerplate (make boilerplate_diff ITEMS=Makefile,scripts) logs a unified diff from each of the solution's copies to the packaged file, for all items but the skills when --boilerplate-items is not set.
Agent skills
The toolkit ships eight Agent Skills so coding agents run the solution's operations the way the toolkit intends: anarchy (the entry point: CLI, rules and which skill to load), anarchy-adopt (first-time adoption and initial repository setup), anarchy-compose (modules, settings, health reports, workers), anarchy-conventions (the recommended coding conventions and the decisions behind them), anarchy-develop, anarchy-environment, anarchy-release and anarchy-maintenance. They are opt-in: make install_skills (or make boilerplate ITEMS=skills, or anarchy-toolkit skills install) copies them to .agents/skills, never overwriting existing files.
A skill is free text (when to use the commands, how to combine them, what to avoid) plus a commands table generated between and from the Makefiles' #?, #+ and #! comments. Make targets declare their skill with a #@ comment, which make help COMMAND=<target> also shows:
#@ shop-billing # before the first target: every documented target of the file
invoice: #? Issues the pending invoices
#@ shop-admin # right after a target: that target only; '#@ -' exempts it
A bare #@ names the skill <prefix>-<file>. IAgentSkillsBuild keeps the skills in step:
To add a skill for this solution's own targets, document them with #? (and parameters with #+ NAME|type|description),
mark a .mk file with #@ <skill-name> or mark an individual target just below it, then run make skills_sync.
Replace the generated TODO description with when and how to use the commands, and run make skills_validate to check
the skill. #@ - exempts a target.
| Target | Make | What it does |
|---|---|---|
SyncAgentSkills |
skills_sync [PREFIX=…] |
Creates each missing skill from a template and rewrites the commands block of every skill, keeping the rest of the file |
ValidateAgentSkills |
skills_validate [PREFIX=…] |
Fails when a required skill is missing or invalid, still has the template's TODO description, lost its ## When to use or ## Commands section, or lists outdated commands |
--agent-skills-prefix defaults to the solution's name, and --agent-skills-directories to .agents/skills (new skills are created in the first). These can also be saved under agentSkills in .anarchy-toolkit.json. ValidateAgentSkills is not part of PullRequest; run it as its own CI step.
Automation preferences
Fallout resolves command-line, environment and parameters.json values using its existing precedence before consulting
the optional root .anarchy-toolkit.json, then the in-code default. To inspect or deliberately edit saved overrides,
use ShowAnarchyPreferences, SetAnarchyPreference --PreferenceKey section.property --PreferenceValue '<JSON>',
UnsetAnarchyPreference --PreferenceKey section.property or ConfigureAnarchyPreferences; Make wrappers are
config_show, config_set KEY=section.property VALUE='<JSON>', config_unset KEY=section.property and
config_configure. Edits merge only requested keys, validate the resulting preferences and write atomically. Normal
build execution never writes preferences. See the complete inventory and defaults.
Mock server
IMockServerBuild runs an Anarchy.Toolkit.Web.MockServer host, a runnable project in the solution whose name ends in MockServer (or MockServerProject) and whose Program calls MockServerEntryPoint.RunAsync(args). It is launched by path with dotnet run, so the build does not reference it. Parameters: MockServerPort (default 6001, or the next free one), MockServerExpectations, MockServerRecord (default artifacts/mock-server/requests.jsonl), MockServerVerbosity (quiet to diagnostic), MockServerArgs and MockServerTimeout. The boilerplate's mock-server.mk exposes each target to Make:
| Target | Make | What it does |
|---|---|---|
MockServerRun |
mock_server |
Runs it in the foreground until Ctrl+C |
MockServerStart, MockServerStop |
mock_server_start, mock_server_stop |
Starts it in the background (output in artifacts/mock-server/mock-server.log), waiting until it is ready, and stops it |
TestIntegrationWithMockServer, TestEndToEndWithMockServer |
test_integration_mocked, test_end_to_end_mocked |
Runs the tests with MOCKSERVER_URL set, starting the server for them (and stopping it after) unless one is already running |
MockServerSyncOpenApi |
mock_server_sync_openapi SPEC=… [OUT=…] [DRY_RUN=true] |
Adds an expectation for each endpoint of an OpenAPI or Swagger specification (file or URL) that has none, into <tag>.json files for you to review and commit. It never changes existing expectations: endpoints that changed, disappeared or answer an undocumented status code are only reported |
Build logs and telemetry
Fallout owns the build's logging: right after creating the build it replaces Serilog's Log.Logger with its own
console (themed, honouring --verbosity), CI annotation, warnings-summary and .fallout/temp/build.log sinks, so a
logger configured in Main is discarded. To also send the build logs to your own sinks, add [BuildTelemetry] to the
build class, implement IBuildTelemetry and return your configuration from ConfigureBuildLogs. The attribute wraps
Fallout's logger once it is configured: everything logged through Log (targets, toolkit components, tool output)
reaches both, Fallout's sinks are untouched, and your logger is flushed when the build finishes. IBuildTelemetry
also exposes Telemetry, the toolkit's AppTelemetry over the same pipeline (metrics are discarded).
What Fallout keeps to itself:
- events logged while the build is being constructed, before Fallout configures logging;
- the end-of-build "Errors & Warnings" replay and outcome tables, written to a console-only logger;
- the console theme, the
--verbositylevel switch (your sinks choose their own minimum level), the CI annotation sink and the log files; - output written straight to the console rather than logged, such as the toolkit's tables and sections.
Releases
See the release notes for the complete release history.
| 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
- Anarchy.Toolkit.Automation (>= 2.0.0)
- Anarchy.Toolkit.Infrastructure.Telemetry.Serilog (>= 1.0.1)
- Docfx.App (>= 2.81.0)
- Fallout.Common (>= 11.0.18)
- Humanizer (>= 3.0.10)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.15)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Diagnostics (>= 10.0.15)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Logging (>= 10.0.15)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.15)
- Microsoft.Identity.Client (>= 4.92.0)
- Microsoft.OpenApi (>= 3.11.1)
- Microsoft.OpenApi.YamlReader (>= 3.11.1)
- Newtonsoft.Json (>= 13.0.4)
- NuGet.Packaging (>= 8.0.0)
- Serilog (>= 4.4.0)
- Serilog.Extensions.Logging (>= 10.0.0)
- Serilog.Sinks.Console (>= 6.1.1)
- Spectre.Console (>= 0.57.2)
- System.Security.Cryptography.Pkcs (>= 10.0.15)
- System.Security.Cryptography.Xml (>= 10.0.15)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
## Releases
### 2.0.0
- Breaking: Generate release entries in each package's `RELEASE-NOTES.md` instead of its README.
- fix(Automation.Build): Handle Windows directory containment
- chore(build): Format package release notes property
### 1.0.0
- Breaking: use descriptive `ConfigurationValueSet`, `EnvironmentValueSet`, and `RuntimeValueSet` types without namespace-clash aliases; public automation default changes are classified as breaking. This newly named package remains at its initial 1.0.0.
- Add `AnarchyBuild` as the standard build host, with Fallout as the underlying engine.
- New package identity, renamed from `Anarchy.Toolkit.Build.Fallout`; versions below are historical releases under that package ID.
- Breaking: replace the ECR-named container targets with registry-neutral `Container*` targets, move the Dockerfile default to `docker/Dockerfile` and the publish output to `artifacts/Container/<app>`. The package remains at its initial 1.0.0 on this branch.
- Add optional unified automation preferences and build preference show/set/unset/configure targets, preserving existing Fallout parameter precedence.
- Added `IBuildTelemetry` and `[BuildTelemetry]`, which add consumer sinks alongside Fallout's logging and expose the
toolkit telemetry to build code.
- Establish adopter organization conventions and apply application-folder mappings only when folder-based layering is selected.
- `CheckLayering` and `GenerateDependencyMap` resolve optional `layering` overrides from `.anarchy-toolkit.json` against the folder-mode baseline; a missing file or mode is valid.
### Historical releases under `Anarchy.Toolkit.Build.Fallout`
### 3.10.0
- feat(Build.Cli): ship the conventions and onboarding guides in the agent skills
### 3.9.0
- fix(Build.Cli): pack the boilerplate at its source paths
- feat(Build.Cli): ship a generic .gitignore synced through a managed block
- feat(Build.Cli): show, diff and dry-run the boilerplate before installing it
- feat(Build.Cli): keep the packaged .editorconfig in a managed block
- feat(Build.Fallout): make the source and test roots configurable
- feat(Build.Fallout): accept test kind aliases and run unit tests before delivery
- docs(mock-server): add a guide covering recording and migrating from MockServer
- feat(Build.Cli): ship adoption and runtime composition skills
### 3.8.0
- feat(Build.Cli): add opt-in agent skills to the boilerplate
- feat(Build.Fallout): validate and sync agent skills
- fix(Build.Cli): print a plain title on narrow terminals
- fix(Build.Cli): keep shell completion working for including Makefiles
### 3.7.0
- feat(Build.Fallout): run the mock server with or without its UI
### 3.6.1
- docs(packages): identify each package's pillar and layer
- build(packages): attribute the copyright to Leandro Melão Medeiros
- build: relicense under Apache-2.0 and update the package metadata
- fix(mock-server): default to port 6001, which browsers allow
### 3.6.0
- build(deps): upgrade Swashbuckle.AspNetCore to 11.0.1 and Microsoft.OpenApi to 3.11.1
- feat(Build.Cli): scaffold APIs without the Swagger theme and UIs with the logo and theme toggle
### 3.5.0
- feat: `MockServerSyncOpenApi` target (`MockServerOpenApi`, `MockServerOpenApiOutput`, `MockServerOpenApiDryRun`) adding expectations for new OpenAPI endpoints
### 3.4.0
- feat: `IMockServerBuild`, running a mock server host in the foreground, in the background or around integration and end-to-end tests
### 3.3.1
- docs: expand XML docblocks across all projects for the DocFX API reference
### 3.3.0
- feat(Build.Fallout): add IApiReferenceBuild generating a DocFX API reference from the compiled assemblies
### 3.2.0
- Target output is formatted with Spectre.Console: `ListProjects`, `ListPackages` and the `RunApp`/`RunApps` app hints print tables, `GenerateAppSettings` prompts per file with masked input for secrets, the release targets end with a summary of version changes (changed or dependent), and `Publish` numbers each push and prints a summary.
- The dependency upgrade lists outdated packages within its version lock (`--highest-minor` for `Major`, `--highest-patch` for `Minor`), and prints each step under its own heading.
- `System.Security.Cryptography.Xml` aligned with the .NET 10 LTS (10.0.15, down from 11.0.0).
### 3.1.0
- `IDockerBuild` gains the overridable `DockerReadinessCheck`, a custom check `DockerWaitRunning` polls once the container is running, for containers without a health check.
### 3.0.0
- feat(Build.Fallout): replace AWS release flows with Docker and container builds
### 2.0.0
- **Breaking:** layering, dependency map, release version and notes, Git hook, lint staging and local process tasks, their entities and the connection-string helpers moved to `Anarchy.Toolkit.Build.Cli` (namespaces `Anarchy.Toolkit.Build.Cli.Core.*` and `.Infrastructure.Helper`). Targets are unchanged; update `using` directives that referenced them directly.
- `ILayeringBuild` gains the `LayeringLayers` and `LayeringApplicationFolders` parameters, so layers and application folders (e.g. `src/Api=Web`) can be configured in `.fallout/parameters.json`.
- The packaged Makefile and scripts now come from `Anarchy.Toolkit.Build.Cli`.
### 1.0.2
- chore(deps): update AWS SDK packages