Developers
Build, extend and automate WinCleaner
WinCleaner is a .NET 8 / WPF app driven by JSON catalogs. This page covers the repo layout, catalog format, build steps and headless mode.
Repository
Solution layout
A WPF shell on top of a Core library that executes actions, with the catalogs embedded in the Data project. Tests cover catalogs, OS gating, i18n, DNS, updates and profiles.
WinCleaner.slnx
├── src/WinCleaner WPF shell, ViewModels, themes, i18n
├── src/WinCleaner.Core Actions, executor, registry / services / AppX
├── src/WinCleaner.Data Embedded JSON catalogs + profile models
├── src/WinCleaner.Bootstrap Optional launcher (prereqs → app)
├── tests/WinCleaner.Core.Tests Catalog, OS, i18n, DNS, update, profile
├── installer/ Inno Setup + build helper
├── scripts/ Portable publish + SOURCE_CODES sync
└── tools/i18n/ JSON → Strings.*.xaml pipelineData
JSON catalogs
Tweaks, services, bloatware, presets and winget apps are defined in plain JSON files you can read and review, not hard-coded in the UI.
risk: Safe, Caution, Dangerous or Blocked. Blocked entries can never be applied.reversibility: Exact, Defaulted, Scripted or None. Required on every tweak.- Optional
minBuild,win11Only,skusandarchsfields control which Windows versions, editions and architectures see an entry.
Runtime
How a change is applied
The UI never touches the system directly. Core applies each action, journals it and enforces the risk rules.
- 01
Catalog load → OS / risk filter → ViewModel binding
- 02
User intent → confirmation (Dangerous) → restore point
- 03
Executor applies action → session journal entry
- 04
Undo reads journal → reverse where reversibility allows
Setup
Build and test
Requires the .NET 8 SDK. The app requests administrator rights through UAC when it starts. win-arm64 publishing is intentionally blocked.
git clone https://github.com/emirttac/WinCleaner.git
cd WinCleaner
dotnet restore
dotnet build src\WinCleaner\WinCleaner.csproj -c Release
dotnet test
dotnet run --project src\WinCleaner\WinCleaner.csproj
# Portable single-file
powershell -ExecutionPolicy Bypass -File scripts\publish-portable.ps1
# Installer (needs Inno Setup 6)
powershell -ExecutionPolicy Bypass -File installer\build-installer.ps1CLI
Headless / --config
Apply a profile JSON without opening the UI. Useful for deployment images, lab machines and scripts.
WinCleaner.exe --config path\to\profile.json --apply --silent
WinCleaner.exe --config path\to\profile.json --whatif
WinCleaner.exe --config path\to\profile.json --apply --allow-unknown --log path\to\log.txt--config— profile JSON (schema v2 or v3)--apply/--whatif— apply or plan only--silent— no summary MessageBox--allow-unknown— skip unknown IDs instead of rejecting
Contributing
Before you open a PR
A few ground rules: keep the risk gates strict, keep catalog descriptions accurate, and keep all eight languages in sync.
-
Keep risk gates strict
Blocked entries can never be applied. Dangerous entries require a Settings opt-in and a confirmation. Changes must not loosen either rule.
-
Complete translations
Add every new string key to all eight Strings.*.xaml files. Catalog text guidelines live in tools/i18n.
-
Credit WinUtil
If an entry is adapted from WinUtil, reference the original WinUtil key in a note. Don’t reuse WinUtil’s preset names.
-
Verify before submitting
Run
dotnet testanddotnet format --verify-no-changesbefore opening a PR. Releases ship with SHA256SUMS and an SPDX 2.3 SBOM.