From 1.3.0 Hash Tool is in maintenance mode. What it accepts is written down once, in CONTRIBUTING.md ("Project
status"): security fixes (high/critical vulnerabilities in .NET or a dependency get a prompt release), dependency and
.NET updates, bug and UI/UX fixes, accessibility, translation fixes, and hash algorithms on real demand; no new
features unless truly necessary.
- README: maintenance, Qodana and .NET 10 LTS badges and a "Project status" section.
- CONTRIBUTING: the policy, the issue forms, and the hash algorithm candidates (BLAKE2b-512, SHA3-256/512, CRC-32C)
with what each would take; ARCHITECTURE: a checklist for adding an algorithm.
- Issue forms: the feature request form is replaced by "Hash algorithm request" and "Translation problem"; feature
ideas go to Discussions (Ideas). The accessibility form gives the email address for people who cannot use GitHub.
- Pull request template: the kinds of change that are accepted.
- SECURITY: 1.3.x supported, the security commitment during maintenance, Qodana among the checks.
- CLAUDE.md: the project status for agents.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
99 lines
7.8 KiB
Markdown
99 lines
7.8 KiB
Markdown
# Architecture
|
||
|
||
HashTool is a .NET 10 solution with three shipped programs sharing one core library.
|
||
|
||
```
|
||
src/HashTool.Core hashing, checksum files, folder walking, settings (no UI; trim/AOT compatible)
|
||
src/HashTool.App Avalonia 12 desktop app (CheckHash.exe) — views, view models, services
|
||
src/HashTool.Cli `hashtool` command-line tool (System.CommandLine, NativeAOT)
|
||
tests/ Core.Tests, Cli.Tests, App.Tests (Avalonia headless); Compat/LegacyClient (release gate)
|
||
bench/ BenchmarkDotNet benchmarks (run by hand)
|
||
eng/ scripts used by CI and releases (translations, coverage, release notes, package checks)
|
||
build/ packaging inputs (macOS Info.plist, Linux icon)
|
||
```
|
||
|
||
Shared build settings: `Directory.Build.props` (version, nullable, analyzers, NuGet audit), `Directory.Packages.props`
|
||
(central package versions with transitive pinning), `global.json` (SDK and the Microsoft.Testing.Platform runner),
|
||
`.config/dotnet-tools.json` (vpk, nuget-license, CycloneDX, SonarScanner for .NET, dotnet-coverage; Dependabot keeps
|
||
them up to date).
|
||
|
||
## HashTool.Core
|
||
|
||
| Area | Types | Notes |
|
||
|---|---|---|
|
||
| Hashing | `HashEngine`, `HashType`, `HashAlgorithms`, `HashResult`, `HashMatcher`, `TextHashing` | One read per file for any number of algorithms: double-buffered reads (1 MiB, 4 MiB above 1 GiB), each block fed to every algorithm in parallel; BLAKE3 uses its multi-threaded update for large blocks. CRC32 is big-endian (as 7-Zip/SFV); `HashMatcher` still accepts the reversed order Hash Tool 1.1 wrote. `TextHashing` turns text into the bytes the Hash Text page and `hashtool hash -` hash: UTF-8/UTF-16 without a byte order mark, LF or CRLF line breaks, nothing appended. |
|
||
| Checksum files | `ChecksumParser`, `ChecksumWriter`, `ChecksumDocument`, `ChecksumFileNames` | Reads GNU (`hash name`, `*name`, escaped names), BSD tagged, SFV, xxhsum `XXH3_` and bare sidecar hashes; writes GNU/BSD/SFV/JSON/CSV. The algorithm comes from the line, then the file name, then the user's choice, then the hash length. Paths may not point to UNC or device locations; CSV output neutralises formulas. |
|
||
| Files | `FileEnumerator`, `FileErrors` | Walks folders without following symbolic links or junctions, skips unreadable folders, optionally hidden files. |
|
||
| Processing | `BatchProcessor`, `HashJob`, `IHashJobObserver<T>` | Small files in parallel (default `min(cores, 4)`), files ≥ 1 GiB in a separate lane, one at a time in HDD mode; per-file time-out; every item is reported exactly once. |
|
||
| Configuration | `AppSettings`, `SettingsStore` | `config.json` with a schema version; atomic writes (temp file + move), values clamped on load, a corrupt file is backed up as `config.json.bak-<time>`, 1.x font settings are migrated. |
|
||
|
||
## HashTool.App
|
||
|
||
- **Composition** — `AppHost` builds a `Microsoft.Extensions.DependencyInjection` container (services and view models are
|
||
singletons). `Program.Main` runs Velopack hooks first, then `--smoke-test`, single-instance forwarding and Avalonia.
|
||
- **Views and view models** — compiled bindings everywhere; `App.axaml` maps each view model to its view.
|
||
`FileListViewModelBase` holds what Generate and Verify share: importing (background enumeration, batches of 1000),
|
||
filtering, running a `BatchProcessor` with UI updates pumped every 100 ms, and the summary dialog.
|
||
`TextHashViewModel` (Hash Text) hashes text in memory with every algorithm, shortly after each change.
|
||
- **Localization** — `LocalizationService` reads the satellite resources, detects the system language, sets the culture
|
||
(including `DefaultThreadCurrentCulture`, so async work keeps it) and right-to-left flow. Views bind
|
||
`Localization[Key]`; view models swap their `LocalizationProxy` when the language changes, which refreshes every
|
||
binding. Status texts are stored as enums and translated by converters, so they follow language changes.
|
||
- **Services** — dialogs, file pickers, clipboard and launcher behind interfaces (`UiServices.cs`); `SettingsService`
|
||
debounces saves; `ThemeService`/`ThemePalettes` swap brush resources; `FontService` picks per-script fonts;
|
||
`UpdateService` wraps Velopack (GitHub source, stable channel).
|
||
- **Infrastructure** — logging to daily files and an in-memory sink for the Developer console (`Logging/`), crash
|
||
reports, `AppPaths` (`HASHTOOL_DATA_DIR` override), command-line parsing, single instance (named mutex/lock file plus
|
||
a per-user named pipe), Windows shell integration under `HKCU\Software\Classes`, on-demand elevation, and the
|
||
headless smoke test.
|
||
|
||
## HashTool.Cli
|
||
|
||
`hashtool hash | verify | check | algorithms`, built on Core; `hash -` reads standard input. Exit codes follow `sha256sum`: 0 success, 1 failed or
|
||
mismatched file, 2 usage error or unreadable checksum file. Published per platform as a single NativeAOT executable.
|
||
|
||
## Tests
|
||
|
||
- `HashTool.Core.Tests` — known-answer vectors for every algorithm, engine, parser/writer, enumerator, batch processor,
|
||
settings store. CI requires at least 80% line coverage of Core.
|
||
- `HashTool.Cli.Tests` — commands, output formats and exit codes.
|
||
- `HashTool.App.Tests` — Avalonia headless: every page in several languages, a create-and-verify flow, translation
|
||
integrity (keys, placeholders, Languages.json ↔ resx ↔ project, satellite assemblies, unused keys), language detection,
|
||
and accessibility (`AccessibilityTests`: a real, translated automation name for every control, headings, Tab inside
|
||
file rows, focus when buttons swap, WCAG contrast of every theme palette; see [ACCESSIBILITY.md](../ACCESSIBILITY.md)).
|
||
- `tests/Compat/LegacyClient` — not in the solution: the release workflow uses it to update a real 1.1.3 install with
|
||
its own Velopack 0.0.1298 library and updater (see [RELEASING.md](RELEASING.md)).
|
||
|
||
[SonarCloud](https://sonarcloud.io/project/overview?id=poli0981_HashTool) analyses every pull request and `main` from
|
||
the SonarCloud workflow: the C# during a real build, with coverage from the tests above and from the smoke test
|
||
(`dotnet-coverage`), plus the scripts and workflows. Its quality gate ("Sonar way") applies to new code; `bench/` is
|
||
analysed as test code and `eng/` is left out of coverage.
|
||
|
||
## Adding a hash algorithm
|
||
|
||
In maintenance mode an algorithm is added only on real demand (CONTRIBUTING.md, "Hash algorithms"). What it touches:
|
||
|
||
- `HashType`: append only, never rename. Settings store the name (`"SHA256"`), an unknown name resets `config.json`
|
||
(so would a downgrade after a new algorithm was chosen), and the name is what the UI, the CLI and `-a` show.
|
||
- `HashAlgorithms`: `GuessPriority` (every algorithm must be listed), `Aliases`, `SizeInBytes`, `FileExtension`,
|
||
`BsdTag`, `IsInsecure`.
|
||
- `HashFunction.Create`: the implementation. `HashEngine` creates every requested function before reading, so one that
|
||
can fail on some platforms (the SHA-3 of .NET on macOS and Windows 10) breaks unrelated rows: use a managed
|
||
implementation.
|
||
- `ChecksumFileNames`: extensions and well-known file names (`B2SUMS`…). The Windows context menu uses the same list,
|
||
and `build/macos/Info.plist` must match it (`PackagingTests`).
|
||
- Digests of the same length become guesses (64 hex digits: SHA-256, BLAKE3…): Verify hashes every candidate in one
|
||
read, except when the Default algorithm of the page has that length.
|
||
- Tests: `KnownAnswerTests` (published vectors), `EdgeCaseTests` and `CliTests` (both assert that `sha3` is unknown
|
||
today), `HashMatcherTests`; docs: README, USAGE, `hashtool hash --help`.
|
||
|
||
## Benchmarks
|
||
|
||
```text
|
||
dotnet run -c Release --project bench/HashTool.Benchmarks -- --filter '*'
|
||
```
|
||
|
||
`LargeFileBenchmarks` compares the engine with `SHA256.HashData(FileStream)`; `SmallFilesBenchmarks` compares sequential
|
||
hashing with `BatchProcessor`. On an i7-14700KF with a warm cache: SHA-256 of 256 MiB 129 ms vs 221 ms, BLAKE3 57 ms,
|
||
XXH3 36 ms, CRC32 34 ms; 2,000 × 16 KiB files 26 ms in parallel vs 89 ms sequentially.
|