Skip to content

Commit ed9ca73

Browse files
KeelMatrixKeelMatrix
committed
Refactor: move WithQueryWatch to QueryWatchExtensions; drop Dapper/Ado extension types; switch samples to �uild/* setup and pack Redaction; fix samples (async tx, invariant parse); update README/DEV/PublicAPI; add build README; remove legacy init scripts.
1 parent 5ab36c7 commit ed9ca73

File tree

18 files changed

+358
-109
lines changed

18 files changed

+358
-109
lines changed

‎README.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,11 @@ This repo ships three tiny sample apps (EF Core, ADO.NET, Dapper) that **consume
3737
```bash
3838
dotnet pack ./src/KeelMatrix.QueryWatch/KeelMatrix.QueryWatch.csproj -c Release --include-symbols --p:SymbolPackageFormat=snupkg --output ./artifacts/packages
3939
dotnet pack ./src/KeelMatrix.QueryWatch.EfCore/KeelMatrix.QueryWatch.EfCore.csproj -c Release --include-symbols --p:SymbolPackageFormat=snupkg --output ./artifacts/packages
40+
dotnet pack ./src/KeelMatrix.QueryWatch.Redaction/KeelMatrix.QueryWatch.Redaction.csproj -c Release --include-symbols --p:SymbolPackageFormat=snupkg --output ./artifacts/packages
4041
```
41-
2. **Install local packages to samples** (pins to `./artifacts/packages` via `samples/NuGet.config`):
42-
- Windows (PowerShell): `./samples/init.ps1`
43-
- Linux/macOS (bash): `./samples/init.sh`
42+
2. **Install local packages to samples** (pins to `../artifacts/packages` via `samples/NuGet.config`):
43+
- Windows (PowerShell): `pwsh -NoProfile -File build/Dev-PackInstallSamples.ps1`
44+
- Linux/macOS (bash): `bash build/Dev-PackInstallSamples.sh`
4445
3. **Run a sample** (EF example shown):
4546
```bash
4647
dotnet run --project ./samples/EFCore.Sqlite/EFCore.Sqlite.csproj -c Release
@@ -77,7 +78,7 @@ var options = new DbContextOptionsBuilder<MyDbContext>()
7778
```csharp
7879
using Dapper;
7980
using Microsoft.Data.Sqlite;
80-
using KeelMatrix.QueryWatch.Dapper;
81+
using KeelMatrix.QueryWatch;
8182
using KeelMatrix.QueryWatch.Testing;
8283

8384
using var q = QueryWatchScope.Start(exportJsonPath: "artifacts/dapper.json", sampleTop: 200);
@@ -99,7 +100,7 @@ var rows = await conn.QueryAsync("SELECT 1");
99100

100101
```csharp
101102
using Microsoft.Data.Sqlite;
102-
using KeelMatrix.QueryWatch.Ado;
103+
using KeelMatrix.QueryWatch;
103104
using KeelMatrix.QueryWatch.Testing;
104105

105106
using var q = QueryWatchScope.Start(exportJsonPath: "artifacts/ado.json", sampleTop: 200);

‎build/Dev-CleanPackInstallSamples.ps1‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
Param()
2+
$ErrorActionPreference = 'Stop'
3+
4+
function Step($msg) { Write-Host "==> $msg" -ForegroundColor Cyan }
5+
function Run {
6+
param([Parameter(Mandatory=$true)][string]$exe, [Parameter(ValueFromRemainingArguments=$true)][string[]]$args)
7+
Write-Host (" " + $exe + " " + ($args -join " ")) -ForegroundColor DarkGray
8+
& $exe @args
9+
if ($LASTEXITCODE -ne 0) { throw "Command failed: $exe $($args -join ' ')" }
10+
}
11+
12+
$repoRoot = Split-Path -Parent $PSScriptRoot
13+
Set-Location $repoRoot
14+
15+
try {
16+
Step ".NET SDK info"
17+
Run dotnet --info | Out-Null
18+
19+
$artifacts = Join-Path $repoRoot "artifacts"
20+
$pkgDir = Join-Path $artifacts "packages"
21+
if (-not (Test-Path $pkgDir)) { New-Item -ItemType Directory -Path $pkgDir | Out-Null }
22+
23+
# 0) Clean local KeelMatrix.* packages only (leave other artifacts intact)
24+
Step "Clean ./artifacts/packages (KeelMatrix.QueryWatch*)"
25+
Get-ChildItem -Path $pkgDir -Filter "KeelMatrix.QueryWatch*.nupkg" -ErrorAction SilentlyContinue | Remove-Item -Force -ErrorAction SilentlyContinue
26+
Get-ChildItem -Path $pkgDir -Filter "KeelMatrix.QueryWatch*.snupkg" -ErrorAction SilentlyContinue | Remove-Item -Force -ErrorAction SilentlyContinue
27+
28+
# 1) Restore solution
29+
Step "Restore solution"
30+
Run dotnet restore "KeelMatrix.QueryWatch.sln"
31+
32+
# 2) Build in dependency-friendly order
33+
Step "Build libraries (Release)"
34+
Run dotnet build "src/KeelMatrix.QueryWatch.Redaction/KeelMatrix.QueryWatch.Redaction.csproj" -c Release --no-restore
35+
Run dotnet build "src/KeelMatrix.QueryWatch/KeelMatrix.QueryWatch.csproj" -c Release --no-restore
36+
Run dotnet build "src/KeelMatrix.QueryWatch.EfCore/KeelMatrix.QueryWatch.EfCore.csproj" -c Release --no-restore
37+
38+
# 3) Pack all
39+
Step "Pack libraries -> ./artifacts/packages"
40+
$packArgs = @('--configuration','Release','--no-build','--include-symbols','--p:SymbolPackageFormat=snupkg','--output',$pkgDir)
41+
Run dotnet pack "src/KeelMatrix.QueryWatch.Redaction/KeelMatrix.QueryWatch.Redaction.csproj" @packArgs
42+
Run dotnet pack "src/KeelMatrix.QueryWatch/KeelMatrix.QueryWatch.csproj" @packArgs
43+
Run dotnet pack "src/KeelMatrix.QueryWatch.EfCore/KeelMatrix.QueryWatch.EfCore.csproj" @packArgs
44+
45+
# 4) Restore samples against local feed
46+
Step "Restore samples with samples/NuGet.config"
47+
Run dotnet restore "samples/QueryWatch.Samples.sln" --configfile "samples/NuGet.config"
48+
49+
Step "Done"
50+
Write-Host "Cleaned, packed, and restored samples successfully." -ForegroundColor Green
51+
}
52+
catch {
53+
Write-Error $_
54+
exit 1
55+
}

‎build/Dev-CleanPackInstallSamples.sh‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
step() { printf "\n==> %s\n" "$1"; }
5+
run() { printf " %s\n" "$*" >&2; "$@"; }
6+
7+
SCRIPT_DIR="$( cd -- "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
8+
REPO_ROOT="$(dirname "$SCRIPT_DIR")"
9+
cd "$REPO_ROOT"
10+
11+
step ".NET SDK info"
12+
run dotnet --info >/dev/null
13+
14+
ARTIFACTS="$REPO_ROOT/artifacts"
15+
PKG_DIR="$ARTIFACTS/packages"
16+
mkdir -p "$PKG_DIR"
17+
18+
step "Clean ./artifacts/packages (KeelMatrix.QueryWatch*)"
19+
find "$PKG_DIR" -maxdepth 1 -type f \( -name 'KeelMatrix.QueryWatch*.nupkg' -o -name 'KeelMatrix.QueryWatch*.snupkg' \) -print -delete || true
20+
21+
step "Restore solution"
22+
run dotnet restore "KeelMatrix.QueryWatch.sln"
23+
24+
step "Build libraries (Release)"
25+
run dotnet build "src/KeelMatrix.QueryWatch.Redaction/KeelMatrix.QueryWatch.Redaction.csproj" -c Release --no-restore
26+
run dotnet build "src/KeelMatrix.QueryWatch/KeelMatrix.QueryWatch.csproj" -c Release --no-restore
27+
run dotnet build "src/KeelMatrix.QueryWatch.EfCore/KeelMatrix.QueryWatch.EfCore.csproj" -c Release --no-restore
28+
29+
step "Pack libraries -> ./artifacts/packages"
30+
COMMON_PACK_ARGS=('--configuration' 'Release' '--no-build' '--include-symbols' '--p:SymbolPackageFormat=snupkg' '--output' "$PKG_DIR")
31+
run dotnet pack "src/KeelMatrix.QueryWatch.Redaction/KeelMatrix.QueryWatch.Redaction.csproj" "${COMMON_PACK_ARGS[@]}"
32+
run dotnet pack "src/KeelMatrix.QueryWatch/KeelMatrix.QueryWatch.csproj" "${COMMON_PACK_ARGS[@]}"
33+
run dotnet pack "src/KeelMatrix.QueryWatch.EfCore/KeelMatrix.QueryWatch.EfCore.csproj" "${COMMON_PACK_ARGS[@]}"
34+
35+
step "Restore samples with samples/NuGet.config"
36+
run dotnet restore "samples/QueryWatch.Samples.sln" --configfile "samples/NuGet.config"
37+
38+
step "Done"
39+
echo "Cleaned, packed, and restored samples successfully."

‎build/Dev-PackInstallSamples.ps1‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
Param()
2+
$ErrorActionPreference = 'Stop'
3+
4+
function Step($msg) { Write-Host "==> $msg" -ForegroundColor Cyan }
5+
function Run {
6+
param([Parameter(Mandatory=$true)][string]$exe, [Parameter(ValueFromRemainingArguments=$true)][string[]]$args)
7+
Write-Host (" " + $exe + " " + ($args -join " ")) -ForegroundColor DarkGray
8+
& $exe @args
9+
if ($LASTEXITCODE -ne 0) { throw "Command failed: $exe $($args -join ' ')" }
10+
}
11+
12+
$repoRoot = Split-Path -Parent $PSScriptRoot
13+
Set-Location $repoRoot
14+
15+
try {
16+
Step ".NET SDK info"
17+
Run dotnet --info | Out-Null
18+
19+
$artifacts = Join-Path $repoRoot "artifacts"
20+
$pkgDir = Join-Path $artifacts "packages"
21+
if (-not (Test-Path $pkgDir)) { New-Item -ItemType Directory -Path $pkgDir | Out-Null }
22+
23+
# 1) Restore solution (ensures props/targets are resolved)
24+
Step "Restore solution"
25+
Run dotnet restore "KeelMatrix.QueryWatch.sln"
26+
27+
# 2) Build packable libraries (Release)
28+
Step "Build libraries (Release)"
29+
Run dotnet build "src/KeelMatrix.QueryWatch.Redaction/KeelMatrix.QueryWatch.Redaction.csproj" -c Release --no-restore
30+
Run dotnet build "src/KeelMatrix.QueryWatch/KeelMatrix.QueryWatch.csproj" -c Release --no-restore
31+
Run dotnet build "src/KeelMatrix.QueryWatch.EfCore/KeelMatrix.QueryWatch.EfCore.csproj" -c Release --no-restore
32+
33+
# 3) Pack to ./artifacts/packages (symbols included)
34+
Step "Pack libraries -> ./artifacts/packages"
35+
$packArgs = @('--configuration','Release','--no-build','--include-symbols','--p:SymbolPackageFormat=snupkg','--output',$pkgDir)
36+
Run dotnet pack "src/KeelMatrix.QueryWatch.Redaction/KeelMatrix.QueryWatch.Redaction.csproj" @packArgs
37+
Run dotnet pack "src/KeelMatrix.QueryWatch/KeelMatrix.QueryWatch.csproj" @packArgs
38+
Run dotnet pack "src/KeelMatrix.QueryWatch.EfCore/KeelMatrix.QueryWatch.EfCore.csproj" @packArgs
39+
40+
# 4) Restore samples using their NuGet.config (pins KeelMatrix.QueryWatch* to ../artifacts/packages)
41+
Step "Restore samples with samples/NuGet.config"
42+
Run dotnet restore "samples/QueryWatch.Samples.sln" --configfile "samples/NuGet.config"
43+
44+
Step "Done"
45+
Write-Host "Packages are in: $pkgDir" -ForegroundColor Green
46+
Write-Host "Samples restored against local packages." -ForegroundColor Green
47+
}
48+
catch {
49+
Write-Error $_
50+
exit 1
51+
}

‎build/Dev-PackInstallSamples.sh‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
step() { printf "\n==> %s\n" "$1"; }
5+
run() { printf " %s\n" "$*" >&2; "$@"; }
6+
7+
SCRIPT_DIR="$( cd -- "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
8+
REPO_ROOT="$(dirname "$SCRIPT_DIR")"
9+
cd "$REPO_ROOT"
10+
11+
step ".NET SDK info"
12+
run dotnet --info >/dev/null
13+
14+
ARTIFACTS="$REPO_ROOT/artifacts"
15+
PKG_DIR="$ARTIFACTS/packages"
16+
mkdir -p "$PKG_DIR"
17+
18+
step "Restore solution"
19+
run dotnet restore "KeelMatrix.QueryWatch.sln"
20+
21+
step "Build libraries (Release)"
22+
run dotnet build "src/KeelMatrix.QueryWatch.Redaction/KeelMatrix.QueryWatch.Redaction.csproj" -c Release --no-restore
23+
run dotnet build "src/KeelMatrix.QueryWatch/KeelMatrix.QueryWatch.csproj" -c Release --no-restore
24+
run dotnet build "src/KeelMatrix.QueryWatch.EfCore/KeelMatrix.QueryWatch.EfCore.csproj" -c Release --no-restore
25+
26+
step "Pack libraries -> ./artifacts/packages"
27+
COMMON_PACK_ARGS=('--configuration' 'Release' '--no-build' '--include-symbols' '--p:SymbolPackageFormat=snupkg' '--output' "$PKG_DIR")
28+
run dotnet pack "src/KeelMatrix.QueryWatch.Redaction/KeelMatrix.QueryWatch.Redaction.csproj" "${COMMON_PACK_ARGS[@]}"
29+
run dotnet pack "src/KeelMatrix.QueryWatch/KeelMatrix.QueryWatch.csproj" "${COMMON_PACK_ARGS[@]}"
30+
run dotnet pack "src/KeelMatrix.QueryWatch.EfCore/KeelMatrix.QueryWatch.EfCore.csproj" "${COMMON_PACK_ARGS[@]}"
31+
32+
step "Restore samples with samples/NuGet.config"
33+
run dotnet restore "samples/QueryWatch.Samples.sln" --configfile "samples/NuGet.config"
34+
35+
step "Done"
36+
echo "Packages are in: $PKG_DIR"
37+
echo "Samples restored against local packages."

‎build/README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# 🧰 Build Scripts
2+
3+
Helper scripts for local development and CI.
4+
Run from the **repo root** unless otherwise noted.
5+
6+
---
7+
8+
## 📦 What’s Here
9+
10+
- **`Dev-PackInstallSamples.ps1` / `.sh`** — Restore, build, and **pack** `KeelMatrix.QueryWatch*` libraries, then restore **samples** against the locally packed feed (`./artifacts/packages`).
11+
→ `build/Dev-PackInstallSamples.ps1` • `build/Dev-PackInstallSamples.sh`
12+
13+
- **`Dev-CleanPackInstallSamples.ps1` / `.sh`** — Same as above, but first **cleans** local `KeelMatrix.QueryWatch*.nupkg` / `.snupkg` before rebuilding & packing. Ideal when iterating locally.
14+
→ `build/Dev-CleanPackInstallSamples.ps1` • `build/Dev-CleanPackInstallSamples.sh`
15+
16+
- **`Update-ReadmeFlags.ps1`** — Builds the CLI and updates the README block between
17+
`<!-- BEGIN:CLI_FLAGS -->` and `<!-- END:CLI_FLAGS -->` using `--print-flags-md`.
18+
Writes fallback output to `docs/CLI_FLAGS.generated.md` if markers are missing.
19+
→ `build/Update-ReadmeFlags.ps1`
20+
21+
- **`Pack-Sign-Push.ps1`** — End-to-end **pack → (optional) sign → push** workflow.
22+
Stubs for signing/publishing (customize for your environment).
23+
→ `build/Pack-Sign-Push.ps1`
24+
25+
- **`New-DevSecrets.ps1`** — Stub that documents how to configure your **NuGet API key** and import a **code-signing certificate** locally. Safe to customize for your organization.
26+
→ `build/New-DevSecrets.ps1`
27+
28+
> PowerShell (`.ps1`) and Bash (`.sh`) variants are provided to support cross-platform workflows.
29+
30+
---
31+
32+
## ⚡ Quick Tasks
33+
34+
### Pack libs and restore samples (fast path)
35+
36+
#### Windows / PowerShell
37+
```powershell
38+
pwsh -NoProfile -File build/Dev-PackInstallSamples.ps1
39+
```
40+
41+
#### Linux / macOS
42+
```bash
43+
bash build/Dev-PackInstallSamples.sh
44+
```
45+
46+
---
47+
48+
### Clean old local packages, repack, restore samples
49+
50+
```powershell
51+
pwsh -NoProfile -File build/Dev-CleanPackInstallSamples.ps1
52+
```
53+
54+
```bash
55+
bash build/Dev-CleanPackInstallSamples.sh
56+
```
57+
58+
---
59+
60+
### Refresh CLI flags in README
61+
62+
```powershell
63+
./build/Update-ReadmeFlags.ps1
64+
```
65+
66+
---
67+
68+
### End-to-end pack → (optional) sign → push
69+
70+
Customize first, then run:
71+
```powershell
72+
./build/Pack-Sign-Push.ps1
73+
```
74+
75+
---
76+
77+
## 🧩 Prerequisites
78+
79+
- **.NET SDK 8.x+** → check via:
80+
```bash
81+
dotnet --info
82+
```
83+
See: `docs/DEV.md`
84+
- For signing/publish flows: configure your **NuGet API key** and (optional) **code-signing certificate** locally.
85+
See: `build/New-DevSecrets.ps1`
86+
87+
---
88+
89+
## 📁 Conventions
90+
91+
- Artifacts are written to `./artifacts` (subfolders: `packages/`, `benchmarks/`, etc).
92+
See: `build/Dev-PackInstallSamples.ps1` or `bench/README.md`.
93+
94+
---

‎docs/DEV.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -195,8 +195,8 @@ Read more in `bench/BENCHMARKS.md`.
195195
dotnet pack ./src/KeelMatrix.QueryWatch/KeelMatrix.QueryWatch.csproj -c Release --no-build --include-symbols --p:SymbolPackageFormat=snupkg -o ./artifacts/packages
196196
dotnet pack ./src/KeelMatrix.QueryWatch.EfCore/KeelMatrix.QueryWatch.EfCore.csproj -c Release --no-build --include-symbols --p:SymbolPackageFormat=snupkg -o ./artifacts/packages
197197

198-
# Then run the sample helper
199-
pwsh -NoProfile -File samples/init.ps1
198+
# Then run the sample setup
199+
pwsh -NoProfile -File build/Dev-PackInstallSamples.ps1
200200
dotnet run --project samples/EFCore.Sqlite/EFCore.Sqlite.csproj -c Release
201201
```
202202

‎samples/Ado.Sqlite/Program.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@
4444
// Query back
4545
using (var select = conn.CreateCommand()) {
4646
select.CommandText = Redaction.Apply("SELECT COUNT(*) FROM Users WHERE Name LIKE 'User_%';");
47-
var count = Convert.ToInt32(await select.ExecuteScalarAsync());
47+
var count = Convert.ToInt32(await select.ExecuteScalarAsync(), System.Globalization.CultureInfo.InvariantCulture);
4848
Console.WriteLine($"Users in DB: {count}");
4949
}
5050

‎samples/Dapper.Sqlite/Program.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
using Dapper;
22
using DapperSample;
3-
using KeelMatrix.QueryWatch.Dapper;
3+
using KeelMatrix.QueryWatch;
44
using KeelMatrix.QueryWatch.Testing;
55
using Microsoft.Data.Sqlite;
66

@@ -26,15 +26,15 @@
2626
await conn.ExecuteAsync(Redaction.Apply("/* contact: [email protected] */ CREATE TABLE Users(Id INTEGER PRIMARY KEY, Name TEXT NOT NULL);"));
2727

2828
// Insert in a transaction (exercise Transaction wrapper + async APIs)
29-
using (var tx = conn.BeginTransaction()) {
29+
using (var tx = await conn.BeginTransactionAsync()) {
3030
for (int i = 0; i < 3; i++) {
3131
var email = $"user{i}@example.com"; // will be redacted in CommandText
3232
await conn.ExecuteAsync(
3333
Redaction.Apply($"/* email: {email} */ INSERT INTO Users(Name) VALUES (@name);"),
3434
new { name = Redaction.Param("User_" + i) },
3535
transaction: tx);
3636
}
37-
tx.Commit();
37+
await tx.CommitAsync();
3838
}
3939

4040
// Query back (async)

‎samples/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Tiny apps that consume the local `KeelMatrix.QueryWatch*` packages so you can se
1212
## Start here
1313
Follow the **[Quick Start — Samples (local)](../README.md#quick-start--samples-local)** in the root README.
1414

15-
> After you run `dotnet pack ...` at the repo root, use `./init.ps1` (or `./init.sh`) once to add local packages. No other tweaks are needed.
15+
> After you run `dotnet pack ...` at the repo root, use `pwsh -NoProfile -File ../build/Dev-PackInstallSamples.ps1` (or `bash ../build/Dev-PackInstallSamples.sh`) once to install local packages. No other tweaks are needed.
1616
1717
### Run a sample
1818
```bash

0 commit comments

Comments
 (0)