Update to .NET 10, add DocFX workaround (#420)

* Add temporary workaround until docfx version is available that is compatible with .NET 10

* Install missing .NET versions

* Update website to .NET 10

Repro for NavigationException: Open site, paste /docs/v3/obsolete into browser, click Get Started > Documentation

Author: bart-vmware

.config/dotnet-tools.json

@@ -18,7 +18,6 @@ env:
   AZURE_WEBAPP_PACKAGE_PATH: '.'
   DOTNET_CLI_TELEMETRY_OPTOUT: 1
   DOTNET_NOLOGO: true
-  DOTNET_VERSION: '8.0.x'
   DOCFX_SOURCE_BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
 
 jobs:
@@ -31,7 +30,10 @@ jobs:
     - name: Setup .NET
       uses: actions/setup-dotnet@v4
       with:
-        dotnet-version: ${{ env.DOTNET_VERSION }}
+        dotnet-version: |
+          8.0.*
+          9.0.*
+          10.0.*
 
     - name: Generate API Browser docs
       shell: pwsh

.github/workflows/build-and-stage.yml

@@ -417,3 +417,6 @@ src/Steeltoe.io/wwwroot/*xrefmap.yml
 
 # Overrides
 !docs/articles/releases
+
+# Temporary workaround until a proper DocFX build supporting .NET 10 is available.
+docfx-net10-binaries/

.gitignore

@@ -42,12 +42,3 @@ The site should now be running at <https://localhost:8080>.
 > [!NOTE]
 > If this is your first time running the site and you skip steps 1 and 2, none of the static content will be processed.
 > You will encounter `InvalidFileLink` warnings from files at the path `docs/api` and 404 errors when browsing the site.
-
-### NavigationException while debugging
-
-This site uses `NavigationManager` to redirect to static content in several places.
-When running the app locally, you will experience a `NavigationException` every time you are redirected.
-If you've already run the docfx steps, let the debugger continue, and you should be redirected to the static content as expected.
-
-While annoying, this behavior is according to Blazor's design, and handling the exception would break the redirect.
-[Learn more about plans to address `NavigationException` in .NET 10](https://github.com/dotnet/aspnetcore/issues/59451).

README.md

@@ -6,16 +6,26 @@ param (
 
 set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
+
 Write-Host "Starting value of DOCFX_SOURCE_BRANCH_NAME: '$env:DOCFX_SOURCE_BRANCH_NAME'"
 $OriginalSourceBranchName = $env:DOCFX_SOURCE_BRANCH_NAME
 
-# Restore docfx tool
-dotnet tool restore
-
 # Get the script's directory
 $baseDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 Push-Location $baseDir
 
+function EnsureDocfxBinaries() {
+    # Temporary workaround until a proper DocFX build supporting .NET 10 is available.
+    $zipFile = [IO.Path]::Combine($env:TEMP, 'docfx-net10-binaries.zip')
+
+    if (!(Test-Path -Path 'docfx-net10-binaries')) {
+        Invoke-WebRequest -Uri 'https://ent.box.com/shared/static/7uekfex8ugc1kijt60lwx6q4n1r3d1m6.zip' -Method 'GET' -OutFile $zipFile
+        Expand-Archive $zipFile -Force
+    }
+}
+
+EnsureDocfxBinaries
+
 # Repository information
 $gitSourcesUrl = 'https://github.com/SteeltoeOSS/Steeltoe'
 
@@ -55,8 +65,8 @@ function Clone-Source-Build-Metadata
 
     Write-Output "Setting DOCFX_SOURCE_BRANCH_NAME to '$branch'"
     $env:DOCFX_SOURCE_BRANCH_NAME = $branch
-    Write-Output "Running command: dotnet docfx metadata $apiFile"
-    dotnet docfx metadata $apiFile
+    Write-Output "Running command: dotnet exec docfx-net10-binaries/docfx.dll metadata $apiFile"
+    dotnet exec docfx-net10-binaries/docfx.dll metadata $apiFile
 }
 
 $buildAll = $false;
@@ -90,7 +100,7 @@ if ($SteeltoeVersion -eq 'source')
 Write-Output "Setting DOCFX_SOURCE_BRANCH_NAME back to '$OriginalSourceBranchName'"
 $env:DOCFX_SOURCE_BRANCH_NAME = $OriginalSourceBranchName
 
-$buildArgs = @('docfx', 'build', (Join-Path '..' 'docs' 'docfx-all.json'))
+$buildArgs = @('exec', 'docfx-net10-binaries/docfx.dll', 'build', (Join-Path '..' 'docs' 'docfx-all.json'))
 if ($buildAll -eq $true) {
     $buildArgs += '--warningsAsErrors'
     $buildArgs += 'true'

build/build-metadata.ps1

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://json.schemastore.org/launchsettings.json",
   "profiles": {
     "localhost": {
       "commandName": "Project",

src/Steeltoe.io/Properties/launchSettings.json

@@ -1,6 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk.Web">
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFramework>net10.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
+    <BlazorDisableThrowNavigationException>true</BlazorDisableThrowNavigationException>
   </PropertyGroup>
 </Project>