Interrupt on error when building docs locally. Added switch for faster inner loop.

Author: bkoelman

docs/build-dev.ps1

@@ -1,17 +1,37 @@
-# This script assumes that you have already installed docfx and httpserver.
+#Requires -Version 7.0
+
+# This script builds the documentation website, starts a web server and opens the site in your browser. Intended for local development.
+# It is assumed that you have already installed docfx and httpserver.
 # If that's not the case, run the next commands:
 #   choco install docfx -y
 #   npm install -g httpserver
 
-Remove-Item _site -Recurse -ErrorAction Ignore
+param(
+    # Specify -NoBuild to skip code build and examples generation. This runs faster, so handy when only editing Markdown files.
+    [switch] $NoBuild=$False
+)
+
+function VerifySuccessExitCode {
+    if ($LastExitCode -ne 0) {
+        throw "Command failed with exit code $LastExitCode."
+    }
+}
+
+if (-Not $NoBuild -Or -Not (Test-Path -Path _site)) {
+    Remove-Item _site -Recurse -ErrorAction Ignore
 
-dotnet build .. --configuration Release
-Invoke-Expression ./generate-examples.ps1
+    dotnet build .. --configuration Release
+    VerifySuccessExitCode
+
+    Invoke-Expression ./generate-examples.ps1
+}
 
 docfx ./docfx.json
-Copy-Item home/*.html _site/
-Copy-Item home/*.ico _site/
-Copy-Item -Recurse home/assets/* _site/styles/
+VerifySuccessExitCode
+
+Copy-Item -Force home/*.html _site/
+Copy-Item -Force home/*.ico _site/
+Copy-Item -Force -Recurse home/assets/* _site/styles/
 
 cd _site
 $webServerJob = httpserver &

docs/generate-examples.ps1

@@ -8,7 +8,7 @@ function Get-WebServer-ProcessId {
         $processId = $(lsof -ti:14141)
     }
     elseif ($IsWindows) {
-        $processId = $(Get-NetTCPConnection -LocalPort 14141 -ErrorAction SilentlyContinue).OwningProcess
+        $processId = $(Get-NetTCPConnection -LocalPort 14141 -ErrorAction SilentlyContinue).OwningProcess?[0]
     }
     else {
         throw [System.Exception] "Unsupported operating system."
@@ -22,7 +22,11 @@ function Kill-WebServer {
 
     if ($processId -ne $null) {
         Write-Output "Stopping web server"
-        Get-Process -Id $processId | Stop-Process
+        Get-Process -Id $processId | Stop-Process -ErrorVariable stopErrorMessage
+
+        if ($stopErrorMessage) {
+            throw "Failed to stop web server: $stopErrorMessage"
+        }
     }
 }
 
@@ -40,18 +44,21 @@ function Start-WebServer {
 Kill-WebServer
 Start-WebServer
 
-Remove-Item -Force -Path .\request-examples\*.json
+try {
+    Remove-Item -Force -Path .\request-examples\*.json
 
-$scriptFiles = Get-ChildItem .\request-examples\*.ps1
-foreach ($scriptFile in $scriptFiles) {
-    $jsonFileName = [System.IO.Path]::GetFileNameWithoutExtension($scriptFile.Name) + "_Response.json"
+    $scriptFiles = Get-ChildItem .\request-examples\*.ps1
+    foreach ($scriptFile in $scriptFiles) {
+        $jsonFileName = [System.IO.Path]::GetFileNameWithoutExtension($scriptFile.Name) + "_Response.json"
 
-    Write-Output "Writing file: $jsonFileName"
-    & $scriptFile.FullName > .\request-examples\$jsonFileName
+        Write-Output "Writing file: $jsonFileName"
+        & $scriptFile.FullName > .\request-examples\$jsonFileName
 
-    if ($LastExitCode -ne 0) {
-        throw [System.Exception] "Example request from '$($scriptFile.Name)' failed with exit code $LastExitCode."
+        if ($LastExitCode -ne 0) {
+            throw [System.Exception] "Example request from '$($scriptFile.Name)' failed with exit code $LastExitCode."
+        }
     }
 }
-
-Kill-WebServer
+finally {
+    Kill-WebServer
+}