The cibuild was failing on documentation example generation. We had a fixed sleep of 10 seconds after starting the webserver, which turned out to be insufficient.

Switched to polling with 1 second interval for webserver to become online.
Also changed to run this during PR build (without push), so we'll know in advance if docs generation breaks.
Fixed invalid port number on mac/linux builds.

Author: Bart Koelman

Diff for: appveyor.yml

@@ -13,34 +13,34 @@ before_build:
         if (-Not $env:APPVEYOR_PULL_REQUEST_TITLE) {
             # https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html
             git checkout $env:APPVEYOR_REPO_BRANCH -q
-            choco install docfx -y
         }
+        choco install docfx -y
 
 after_build:
   - pwsh: |
+        CD ./docs
+        & ./generate-examples.ps1
+        & docfx docfx.json
+        if ($lastexitcode -ne 0) {
+          throw [System.Exception] "docfx build failed with exit code $lastexitcode."
+        }
+        
+        git config --global credential.helper store
+        Add-Content "$env:USERPROFILE\.git-credentials" "https://$($env:ACCESS_TOKEN):[email protected]`n"
+        git config --global user.email "[email protected]"
+        git config --global user.name "Jared Nance"
+        git config --global core.autocrlf false
+        git config --global core.safecrlf false
+        git clone https://github.com/json-api-dotnet/JsonApiDotNetCore.git -b gh-pages origin_site -q
+        Copy-Item origin_site/.git _site -recurse
+        Copy-Item CNAME _site/CNAME
+        Copy-Item home/*.html _site/
+        Copy-Item home/*.ico _site/
+        Copy-Item -Recurse home/assets/* _site/styles/
+        CD _site
+        git add -A 2>&1
+        git commit -m "CI Updates" -q
         if (-Not $env:APPVEYOR_PULL_REQUEST_TITLE) {
-            CD ./docs
-            & ./generate-examples.ps1
-            & docfx docfx.json
-            if ($lastexitcode -ne 0) {
-              throw [System.Exception] "docfx build failed with exit code $lastexitcode."
-            }
-            
-            git config --global credential.helper store
-            Add-Content "$env:USERPROFILE\.git-credentials" "https://$($env:ACCESS_TOKEN):[email protected]`n"
-            git config --global user.email "[email protected]"
-            git config --global user.name "Jared Nance"
-            git config --global core.autocrlf false
-            git config --global core.safecrlf false
-            git clone https://github.com/json-api-dotnet/JsonApiDotNetCore.git -b gh-pages origin_site -q
-            Copy-Item origin_site/.git _site -recurse
-            Copy-Item CNAME _site/CNAME
-            Copy-Item home/*.html _site/
-            Copy-Item home/*.ico _site/
-            Copy-Item -Recurse home/assets/* _site/styles/
-            CD _site
-            git add -A 2>&1
-            git commit -m "CI Updates" -q
             git push origin gh-pages -q
             echo "Documentation updated successfully."
         }

Diff for: docs/generate-examples.ps1

@@ -2,34 +2,46 @@
 
 # This script generates response documents for ./request-examples
 
-function Kill-WebServer {
+function Get-WebServer-ProcessId {
     $processId = $null
     if ($IsMacOs || $IsLinux) {
-        $processId = $(lsof -ti:8080)
+        $processId = $(lsof -ti:14141)
     }
     elseif ($IsWindows) {
         $processId = $(Get-NetTCPConnection -LocalPort 14141 -ErrorAction SilentlyContinue).OwningProcess
     }
+    else {
+        throw [System.Exception] "Unsupported operating system."
+    }
+
+    return $processId
+}
+
+function Kill-WebServer {
+    $processId = Get-WebServer-ProcessId
 
     if ($processId -ne $null) {
         Write-Output "Stopping web server"
         Get-Process -Id $processId | Stop-Process
     }
-
 }
 
-function Start-Webserver {
+function Start-WebServer {
     Write-Output "Starting web server"
     Start-Job -ScriptBlock { dotnet run --project ..\src\Examples\GettingStarted\GettingStarted.csproj } | Out-Null
+
+    $webProcessId = $null
+    Do {
+        Start-Sleep -Seconds 1
+        $webProcessId = Get-WebServer-ProcessId
+    } While ($webProcessId -eq $null)
 }
 
 Kill-WebServer
-Start-Webserver
+Start-WebServer
 
 Remove-Item -Force -Path .\request-examples\*.json
 
-Start-Sleep -Seconds 10
-
 $scriptFiles = Get-ChildItem .\request-examples\*.ps1
 foreach ($scriptFile in $scriptFiles) {
     $jsonFileName = [System.IO.Path]::GetFileNameWithoutExtension($scriptFile.Name) + "_Response.json"
@@ -38,7 +50,7 @@ foreach ($scriptFile in $scriptFiles) {
     & $scriptFile.FullName > .\request-examples\$jsonFileName
 
     if ($LastExitCode -ne 0) {
-        throw [System.Exception] "Example request from '$($scriptFile.Name)' failed."
+        throw [System.Exception] "Example request from '$($scriptFile.Name)' failed with exit code $LastExitCode."
     }
 }