English
Developer commands
Step 1. A script for the everyday commands
Why. By the end of the tutorial the everyday work needs more than a dozen commands with long options: start the database and apply the migrations, run the API with the right launch profile, run the Angular server from its folder, run every CI check before a push. Typing them from memory is slow and error-prone, and a newcomer has to find them in the documentation first.
A small script in the repository root turns each of them into one short, discoverable command: ./Run.ps1 api, ./Run.ps1 test, ./Run.ps1 check. It is written in PowerShell 7, which runs on Windows, macOS and Linux, so everyone on the team uses the same script.
Do. Create Run.ps1 in the repository root. It is the final version of the script; some commands need parts of the project that we build later (see the table after the listing).
powershell
#!/usr/bin/env pwsh
#Requires -Version 7.0
# Chatex developer commands. Run without arguments (or with 'help') to list them.
# Extra arguments after 'test' and 'migration' are passed on, see the examples in the help.
param(
[ValidateSet('help', 'setup', 'db', 'db-stop', 'migration', 'api', 'web', 'build', 'test', 'format', 'check', 'clean')]
[string] $Command = 'help'
)
$ErrorActionPreference = 'Stop'
$Root = $PSScriptRoot
$Web = Join-Path $Root 'Source/Chatex.Web'
$Solution = 'Chatex.slnx'
$DataProject = 'Source/Chatex.Data'
$ApiProject = 'Source/Chatex.Api'
$Commands = [ordered]@{
'help' = 'Show this list.'
'setup' = 'First run: restore tools and packages, start the database and apply the migrations.'
'db' = 'Start PostgreSQL in Docker (compose.yaml) and apply the migrations.'
'db-stop' = 'Stop the PostgreSQL container; the data stays in its volume.'
'migration' = 'Add an EF Core migration: migration <Name>.'
'api' = 'Run the API on http://localhost:5214 (API reference at /scalar).'
'web' = 'Run the Angular dev server on http://localhost:4200 (start the API first).'
'build' = 'Build the solution and the web app.'
'test' = 'Run the backend and frontend tests; with arguments, run dotnet test with them instead.'
'format' = 'Format C# (dotnet format) and the web app (Prettier).'
'check' = 'Run everything CI runs: format checks, Release build, migration check, tests, audit, lint, build.'
'clean' = 'Delete build output (bin, obj, dist and the Angular cache).'
}
function Show-Help {
Write-Host 'Chatex developer commands' -ForegroundColor Cyan
Write-Host ''
Write-Host ' ./Run.ps1 <command> [arguments]'
Write-Host ''
foreach ($entry in $Commands.GetEnumerator()) {
Write-Host (' {0,-10} ' -f $entry.Key) -ForegroundColor Green -NoNewline
Write-Host $entry.Value
}
Write-Host ''
Write-Host 'Examples:' -ForegroundColor Cyan
Write-Host ' ./Run.ps1 setup'
Write-Host ' ./Run.ps1 migration AddMessageReactions'
Write-Host ' ./Run.ps1 test --project Tests/Chatex.Core.Tests --filter-class "*ChatServiceTests"'
Write-Host ' ./Run.ps1 check'
Write-Host ''
Write-Host 'Needs the .NET 10 SDK, Node.js 24 and Docker. See Docs/GettingStarted.md.'
}
# Runs a program in a folder (the repository root by default) and stops the script if it fails.
function Invoke-Step {
param(
[Parameter(Mandatory)] [string] $FilePath,
[string[]] $ArgumentList = @(),
[string] $WorkingDirectory = $Root
)
Write-Host "> $FilePath $($ArgumentList -join ' ')" -ForegroundColor DarkGray
Push-Location $WorkingDirectory
try {
& $FilePath @ArgumentList
if ($LASTEXITCODE -ne 0) {
throw "'$FilePath $($ArgumentList -join ' ')' failed with exit code $LASTEXITCODE."
}
}
finally {
Pop-Location
}
}
function Start-Database {
Invoke-Step docker 'compose', 'up', '--detach', '--wait'
Invoke-Step dotnet 'ef', 'database', 'update', '--project', $DataProject
}
switch ($Command) {
'help' {
Show-Help
}
'setup' {
Invoke-Step dotnet 'tool', 'restore'
Invoke-Step dotnet 'restore', $Solution
Invoke-Step npm 'ci' -WorkingDirectory $Web
Start-Database
Write-Host 'Ready: ./Run.ps1 api, then ./Run.ps1 web in a second terminal.' -ForegroundColor Cyan
}
'db' {
Start-Database
}
'db-stop' {
Invoke-Step docker 'compose', 'stop'
}
'migration' {
if ($args.Count -ne 1) {
throw 'Usage: ./Run.ps1 migration <Name>'
}
Invoke-Step dotnet 'ef', 'migrations', 'add', $args[0], '--project', $DataProject, '--output-dir', 'Migrations'
}
'api' {
Invoke-Step dotnet 'run', '--project', $ApiProject, '--launch-profile', 'http'
}
'web' {
Invoke-Step npm 'start' -WorkingDirectory $Web
}
'build' {
Invoke-Step dotnet 'build', $Solution
Invoke-Step npm 'run', 'build' -WorkingDirectory $Web
}
'test' {
if ($args.Count -gt 0) {
Invoke-Step dotnet (@('test') + $args)
}
else {
Invoke-Step dotnet 'test', '--solution', $Solution
Invoke-Step npm 'test', '--', '--watch=false' -WorkingDirectory $Web
}
}
'format' {
Invoke-Step dotnet 'format', $Solution
Invoke-Step npm 'run', 'format' -WorkingDirectory $Web
}
'check' {
# The same steps as .github/workflows/ci.yml.
Invoke-Step dotnet 'restore', $Solution
Invoke-Step dotnet 'tool', 'restore'
Invoke-Step dotnet 'format', $Solution, '--verify-no-changes', '--no-restore'
Invoke-Step dotnet 'build', $Solution, '-c', 'Release', '--no-restore'
Invoke-Step dotnet 'ef', 'migrations', 'has-pending-model-changes', '--project', $DataProject, '--configuration', 'Release', '--no-build'
Invoke-Step dotnet 'test', '--solution', $Solution, '-c', 'Release', '--no-build'
Invoke-Step npm 'ci' -WorkingDirectory $Web
Invoke-Step npm 'audit', '--omit=dev', '--audit-level=high' -WorkingDirectory $Web
Invoke-Step npm 'run', 'format:check' -WorkingDirectory $Web
Invoke-Step npm 'run', 'lint' -WorkingDirectory $Web
Invoke-Step npm 'test', '--', '--watch=false' -WorkingDirectory $Web
Invoke-Step npm 'run', 'build' -WorkingDirectory $Web
Write-Host 'All checks passed.' -ForegroundColor Green
}
'clean' {
$folders = @(
Get-ChildItem -Path (Join-Path $Root 'Source'), (Join-Path $Root 'Tests') -Directory |
ForEach-Object { Join-Path $_.FullName 'bin'; Join-Path $_.FullName 'obj' }
Join-Path $Web 'dist'
Join-Path $Web '.angular/cache'
) | Where-Object { Test-Path $_ }
foreach ($folder in $folders) {
Write-Host "Deleting $folder" -ForegroundColor DarkGray
Remove-Item -Recurse -Force $folder
}
}
}How it works:
param(...)with[ValidateSet(...)]— the first argument must be one of the listed commands. A typo such as./Run.ps1 tsetfails at once with the list of valid values, and the terminal completes the command names with Tab. Without an argument the command ishelp.$ErrorActionPreference = 'Stop'— an error in a PowerShell command stops the script instead of letting it continue with the next step.$Commands— an ordered dictionary of the commands and their descriptions;Show-Helpprints it, so the help always matches the script.Invoke-Step— runs an external program (dotnet,npm,docker) in a given folder, prints the command in grey and stops the script if the program fails. External programs do not raise PowerShell errors; they report failure through their exit code, which PowerShell stores in$LASTEXITCODE. Without this check,checkwould happily run the tests after a failed build.switch ($Command)— one branch per command. Extra arguments that are not declared inparamland in the automatic variable$args;testandmigrationpass them on todotnet.checkruns exactly the steps of the CI workflow (topic 22), so you can find a problem before you push.
Not every command works yet. Table 2.2 shows when each one becomes usable.
Table 2.2. The commands of Run.ps1
| Command | What it does | Works from |
|---|---|---|
help | lists the commands | now |
api | runs the API on http://localhost:5214 | now (it still says "Hello World!") |
db-stop | stops the PostgreSQL container | now |
db | starts PostgreSQL and applies the migrations | topic 4 (the first migration) |
migration <Name> | adds an EF Core migration | topic 4 |
test [options] | runs the tests | topic 6 with options, for example ./Run.ps1 test --solution Chatex.slnx; without options from topic 15 |
clean | deletes bin, obj and the Angular build output | topic 6 (it looks into the folder Tests/, which does not exist yet) |
build, format | builds or formats the backend and the web app | topic 15 (until then use dotnet build and dotnet format Chatex.slnx) |
web | runs the Angular dev server on http://localhost:4200 | topic 15 |
setup | first run: tools, packages, database | topic 15 |
check | everything CI runs | topic 22 |
Check
powershell
./Run.ps1The script prints the list of commands. Then run the API through it:
powershell
./Run.ps1 apiThe grey line > dotnet run --project Source/Chatex.Api --launch-profile http shows the command it runs, and the API listens on http://localhost:5214. Stop it with Ctrl+C.
"Running scripts is disabled on this system"
Windows PowerShell blocks scripts by default, and PowerShell 7 on Windows may block scripts that were downloaded from the internet. Run the script from PowerShell 7, and if it is still blocked, allow local scripts for your user once:
powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSignedStep 2. The first commit
Why. The skeleton is complete: it builds with zero warnings under strict rules, the database runs, and the commands are documented in the script. This is a good state to come back to, so we save it.
Do. Look at what will be committed, then commit:
powershell
git status --shortpowershell
git add .powershell
git commit -m "Create the solution with shared build settings and a local database"Check
powershell
git log --onelineThe history has one commit. git status reports nothing to commit, working tree clean, and no bin/ or obj/ folder was committed:
powershell
git ls-filesThe list contains .editorconfig, .gitattributes, .gitignore, Chatex.slnx, Directory.Build.props, Directory.Packages.props, Run.ps1, compose.yaml, dotnet-tools.json, global.json and the files of the three projects under Source/.
If you have a GitHub account, now is also a good time to create an empty private repository there and push to it; we need it for CI in topic 22:
powershell
git remote add origin https://github.com/<your-account>/Chatex.gitpowershell
git push -u origin main