Merge the microbuild branch from https://github.com/aarnott/Library.Template

Specifically, this merges [6ac5aae from that repo](AArnott/Library.Template@6ac5aae).

Author: AArnott

.config/dotnet-tools.json

@@ -6,19 +6,29 @@
       "version": "7.4.6",
       "commands": [
         "pwsh"
-      ]
+      ],
+      "rollForward": false
     },
     "dotnet-coverage": {
-      "version": "17.12.6",
+      "version": "17.13.1",
       "commands": [
         "dotnet-coverage"
-      ]
+      ],
+      "rollForward": false
     },
     "nbgv": {
-      "version": "3.6.146",
+      "version": "3.7.112",
       "commands": [
         "nbgv"
-      ]
+      ],
+      "rollForward": false
+    },
+    "docfx": {
+      "version": "2.78.2",
+      "commands": [
+        "docfx"
+      ],
+      "rollForward": false
     }
   }
-}
+}

.devcontainer/Dockerfile

@@ -0,0 +1,14 @@
+# Refer to https://hub.docker.com/_/microsoft-dotnet-sdk for available versions
+FROM mcr.microsoft.com/dotnet/sdk:9.0.101-noble
+
+# Installing mono makes `dotnet test` work without errors even for net472.
+# But installing it takes a long time, so it's excluded by default.
+#RUN apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
+#RUN echo "deb https://download.mono-project.com/repo/ubuntu stable-bionic main" | tee /etc/apt/sources.list.d/mono-official-stable.list
+#RUN apt-get update
+#RUN DEBIAN_FRONTEND=noninteractive apt-get install -y mono-devel
+
+# Clear the NUGET_XMLDOC_MODE env var so xml api doc files get unpacked, allowing a rich experience in Intellisense.
+# See https://github.com/dotnet/dotnet-docker/issues/2790 for a discussion on this, where the prioritized use case
+# was *not* devcontainers, sadly.
+ENV NUGET_XMLDOC_MODE=

.devcontainer/devcontainer.json

@@ -0,0 +1,25 @@
+{
+  "name": "Dev space",
+  "dockerFile": "Dockerfile",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.shell.linux": "/usr/bin/pwsh"
+      },
+      "extensions": [
+        "ms-azure-devops.azure-pipelines",
+        "ms-dotnettools.csharp",
+        "k--kato.docomment",
+        "editorconfig.editorconfig",
+        "esbenp.prettier-vscode",
+        "pflannery.vscode-versionlens",
+        "davidanson.vscode-markdownlint",
+        "dotjoshjohnson.xml",
+        "ms-vscode-remote.remote-containers",
+        "ms-azuretools.vscode-docker",
+        "tintoy.msbuild-project-tools"
+      ]
+    }
+  },
+  "postCreateCommand": "./init.ps1 -InstallLocality machine"
+}

.github/.editorconfig

@@ -0,0 +1,2 @@
+[renovate.json*]
+indent_style = tab

.github/actions/publish-artifacts/action.yaml

@@ -0,0 +1,60 @@
+name: Publish artifacts
+description: Publish artifacts
+
+runs:
+  using: composite
+  steps:
+  - name: 📥 Collect artifacts
+    run: tools/artifacts/_stage_all.ps1
+    shell: pwsh
+    if: always()
+
+# TODO: replace this hard-coded list with a loop that utilizes the NPM package at
+# https://github.com/actions/toolkit/tree/main/packages/artifact (or similar) to push the artifacts.
+
+  - name: 📢 Upload project.assets.json files
+    if: always()
+    uses: actions/upload-artifact@v4
+    with:
+      name: projectAssetsJson-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/projectAssetsJson
+    continue-on-error: true
+  - name: 📢 Upload variables
+    uses: actions/upload-artifact@v4
+    with:
+      name: variables-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/Variables
+    continue-on-error: true
+  - name: 📢 Upload build_logs
+    if: always()
+    uses: actions/upload-artifact@v4
+    with:
+      name: build_logs-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/build_logs
+    continue-on-error: true
+  - name: 📢 Upload testResults
+    if: always()
+    uses: actions/upload-artifact@v4
+    with:
+      name: testResults-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/testResults
+    continue-on-error: true
+  - name: 📢 Upload coverageResults
+    if: always()
+    uses: actions/upload-artifact@v4
+    with:
+      name: coverageResults-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/coverageResults
+    continue-on-error: true
+  - name: 📢 Upload symbols
+    uses: actions/upload-artifact@v4
+    with:
+      name: symbols-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/symbols
+    continue-on-error: true
+  - name: 📢 Upload deployables
+    uses: actions/upload-artifact@v4
+    with:
+      name: deployables-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/deployables
+    if: always()

.github/dependabot.yml

@@ -0,0 +1,21 @@
+{
+	"$schema": "https://docs.renovatebot.com/renovate-schema.json",
+	"extends": ["config:recommended"],
+	"semanticCommits": "disabled",
+	"labels": ["dependencies"],
+	"packageRules": [
+		{
+			"matchPackageNames": ["nbgv", "nerdbank.gitversioning"],
+			"groupName": "nbgv and nerdbank.gitversioning updates"
+		},
+		{
+			"matchPackageNames": ["xunit*"],
+			"groupName": "xunit"
+		},
+		{
+			"matchDatasources": ["dotnet-version", "docker"],
+			"matchDepNames": ["dotnet-sdk", "mcr.microsoft.com/dotnet/sdk"],
+			"groupName": "Dockerfile and global.json updates"
+		}
+	]
+}

.github/renovate.json

@@ -0,0 +1,44 @@
+name: 📚 Docs
+
+on:
+  push:
+    branches:
+    - main
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+  contents: read
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  publish-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0 # avoid shallow clone so nbgv can do its work.
+    - name: ⚙ Install prerequisites
+      run: ./init.ps1 -UpgradePrerequisites
+
+    - run: dotnet docfx docfx/docfx.json
+      name: 📚 Generate documentation
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docfx/_site
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.github/workflows/docs.yml

@@ -1,8 +1,8 @@
-name: Library.Template update
+name: ⛜ Library.Template update
 
-# PREREQUISITE: This workflow requires the repo to be configured to allow workflows to push commits and create pull requests.
+# PREREQUISITE: This workflow requires the repo to be configured to allow workflows to create pull requests.
 # Visit https://github.com/USER/REPO/settings/actions
-# Under "Workflow permissions", select "Read and write permissions" and check "Allow GitHub Actions to create ...pull requests"
+# Under "Workflow permissions" check "Allow GitHub Actions to create ...pull requests"
 # Click Save.
 
 on:
@@ -13,15 +13,19 @@ on:
 jobs:
   merge:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0 # avoid shallow clone so nbgv can do its work.
 
     - name: merge
+      id: merge
       shell: pwsh
       run: |
-        $LibTemplateBranch = & ./azure-pipelines/Get-LibTemplateBasis.ps1 -ErrorIfNotRelated
+        $LibTemplateBranch = & ./tools/Get-LibTemplateBasis.ps1 -ErrorIfNotRelated
         if ($LASTEXITCODE -ne 0) {
           exit $LASTEXITCODE
         }
@@ -31,15 +35,37 @@ jobs:
           exit $LASTEXITCODE
         }
         $LibTemplateCommit = git rev-parse FETCH_HEAD
+        git diff --stat ...FETCH_HEAD
 
         if ((git rev-list FETCH_HEAD ^HEAD --count) -eq 0) {
           Write-Host "There are no Library.Template updates to merge."
+          echo "uptodate=true" >> $env:GITHUB_OUTPUT
           exit 0
         }
 
-        git -c http.extraheader="AUTHORIZATION: bearer $env:GH_TOKEN" push origin -u FETCH_HEAD:refs/heads/auto/libtemplateUpdate
+        # Pushing commits that add or change files under .github/workflows will cause our workflow to fail.
+        # But it usually isn't necessary because the target branch already has (or doesn't have) these changes.
+        # So if the merged doesn't bring in any changes to these files, try the merge locally and push that
+        # to keep github happy.
+        if ((git rev-list FETCH_HEAD ^HEAD --count -- .github/workflows) -eq 0) {
+          # Indeed there are no changes in that area. So merge locally to try to appease GitHub.
+          git checkout -b auto/libtemplateUpdate
+          git config user.name "Andrew Arnott"
+          git config user.email "[email protected]"
+          git merge FETCH_HEAD
+          if ($LASTEXITCODE -ne 0) {
+            Write-Host "Merge conflicts prevent creating the pull request. Please run tools/MergeFrom-Template.ps1 locally and push the result as a pull request."
+            exit 2
+          }
+
+          git -c http.extraheader="AUTHORIZATION: bearer $env:GH_TOKEN" push origin -u HEAD
+        } else {
+          Write-Host "Changes to github workflows are included in this update. Please run tools/MergeFrom-Template.ps1 locally and push the result as a pull request."
+          exit 1
+        }
     - name: pull request
       shell: pwsh
+      if: success() && steps.merge.outputs.uptodate != 'true'
       run: |
         # If there is already an active pull request, don't create a new one.
         $existingPR = gh pr list -H auto/libtemplateUpdate --json url | ConvertFrom-Json
@@ -51,6 +77,8 @@ jobs:
         $prTitle = "Merge latest Library.Template"
         $prBody = "This merges the latest features and fixes from [Library.Template's  branch](https://github.com/AArnott/Library.Template/tree/).
 
+        ⚠️ Do **not** squash this pull request when completing it. You must *merge* it.
+
         <details>
         <summary>Merge conflicts?</summary>
         Resolve merge conflicts locally by carrying out these steps:
@@ -63,9 +91,7 @@ jobs:
         git commit
         git push
         ```
-        </details>
-
-        ⚠️ Do **not** squash this pull request when completing it. You must *merge* it."
+        </details>"
 
         gh pr create -H auto/libtemplateUpdate -b $prBody -t $prTitle
       env:

.github/workflows/libtemplate-update.yml

@@ -0,0 +1,88 @@
+name: 🎁 Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      ship_run_id:
+        description: ID of the GitHub workflow run to ship
+        required: true
+
+run-name: ${{ github.ref_name }}
+
+permissions:
+  actions: read
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-24.04
+    steps:
+    - name: ⚙️ Initialization
+      shell: pwsh
+      run: |
+        if ('${{ secrets.NUGET_API_KEY }}') {
+          Write-Host "NUGET_API_KEY secret detected. NuGet packages will be pushed."
+          echo "NUGET_API_KEY_DEFINED=true" >> $env:GITHUB_ENV
+        }
+
+    - name: 🔎 Search for build of ${{ github.ref }}
+      shell: pwsh
+      id: findrunid
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        if ('${{ inputs.ship_run_id }}') {
+          $runid = '${{ inputs.ship_run_id }}'
+        } else {
+          $restApiRoot = '/repos/${{ github.repository }}'
+
+          # Resolve the tag reference to a commit sha
+          $resolvedRef = gh api `
+            -H "Accept: application/vnd.github+json" `
+            -H "X-GitHub-Api-Version: 2022-11-28" `
+            $restApiRoot/git/ref/tags/${{ github.ref_name }} `
+            | ConvertFrom-Json
+          $commitSha = $resolvedRef.object.sha
+
+          Write-Host "Resolved ${{ github.ref_name }} to $commitSha"
+
+          $releases = gh run list -R ${{ github.repository }} -c $commitSha -w .github/workflows/build.yml -s success --json databaseId,startedAt `
+            | ConvertFrom-Json | Sort-Object startedAt -Descending
+
+          if ($releases.length -eq 0) {
+            Write-Error "No successful builds found for ${{ github.ref }}."
+          } elseif ($releases.length -gt 1) {
+            Write-Warning "More than one successful run found for ${{ github.ref }}. Artifacts from the most recent successful run will ship."
+          }
+
+          $runid = $releases[0].databaseId
+        }
+
+        Write-Host "Using artifacts from run-id: $runid"
+
+        Echo "runid=$runid" >> $env:GITHUB_OUTPUT
+
+    - name: 🔻 Download deployables artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: deployables-Linux
+        path: ${{ runner.temp }}/deployables
+        run-id: ${{ steps.findrunid.outputs.runid }}
+        github-token: ${{ github.token }}
+
+    - name: 💽 Upload artifacts to release
+      shell: pwsh
+      if: ${{ github.event.release.assets_url }} != ''
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        Get-ChildItem '${{ runner.temp }}/deployables' |% {
+          Write-Host "Uploading $($_.Name) to release..."
+          gh release -R ${{ github.repository }} upload "${{ github.ref_name }}" $_.FullName
+        }
+
+    - name: 🚀 Push NuGet packages
+      run: dotnet nuget push ${{ runner.temp }}/deployables/*.nupkg --source https://api.nuget.org/v3/index.json -k '${{ secrets.NUGET_API_KEY }}'
+      if: ${{ env.NUGET_API_KEY_DEFINED == 'true' }}