update to the latest library template

.config/dotnet-tools.json

@@ -3,32 +3,32 @@
   "isRoot": true,
   "tools": {
     "powershell": {
-      "version": "7.4.6",
+      "version": "7.5.0",
       "commands": [
         "pwsh"
       ],
       "rollForward": false
     },
     "dotnet-coverage": {
-      "version": "17.12.6",
+      "version": "17.14.2",
       "commands": [
         "dotnet-coverage"
       ],
       "rollForward": false
     },
     "nbgv": {
-      "version": "3.6.146",
+      "version": "3.7.115",
       "commands": [
         "nbgv"
       ],
       "rollForward": false
     },
     "docfx": {
-      "version": "2.77.0",
+      "version": "2.78.3",
       "commands": [
         "docfx"
       ],
       "rollForward": false
     }
   }
-}
+}

.devcontainer/Dockerfile

@@ -1,5 +1,5 @@
 # Refer to https://hub.docker.com/_/microsoft-dotnet-sdk for available versions
-FROM mcr.microsoft.com/dotnet/sdk:8.0.402-jammy
+FROM mcr.microsoft.com/dotnet/sdk:9.0.202-noble@sha256:332e0362dd210a10348d436a5fb7f87aeec28c2c53ac2c3c2659e57c22294d0e
 
 # Installing mono makes `dotnet test` work without errors even for net472.
 # But installing it takes a long time, so it's excluded by default.

.devcontainer/devcontainer.json

@@ -1,20 +1,25 @@
 {
   "name": "Dev space",
   "dockerFile": "Dockerfile",
-  "settings": {
-    "terminal.integrated.shell.linux": "/usr/bin/pwsh"
+  "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",
-  "extensions": [
-    "ms-azure-devops.azure-pipelines",
-    "ms-dotnettools.csharp",
-    "k--kato.docomment",
-    "editorconfig.editorconfig",
-    "pflannery.vscode-versionlens",
-    "davidanson.vscode-markdownlint",
-    "dotjoshjohnson.xml",
-    "ms-vscode-remote.remote-containers",
-    "ms-azuretools.vscode-docker",
-    "ms-vscode.powershell"
-  ]
+  "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@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+    with:
+      name: projectAssetsJson-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/projectAssetsJson
+    continue-on-error: true
+  - name: 📢 Upload variables
+    uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # 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@ea165f8d65b6e75b540449e92b4886f43607fa02 # 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@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+    with:
+      name: testResults-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/testResults
+    continue-on-error: true
+  - name: 📢 Upload coverageResults
+    if: always()
+    uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+    with:
+      name: coverageResults-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/coverageResults
+    continue-on-error: true
+  - name: 📢 Upload symbols
+    uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+    with:
+      name: symbols-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/symbols
+    continue-on-error: true
+  - name: 📢 Upload deployables
+    uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+    with:
+      name: deployables-${{ runner.os }}
+      path: ${{ runner.temp }}/_artifacts/deployables
+    if: always()

.github/renovate.json

@@ -0,0 +1,8 @@
+{
+	"$schema": "https://docs.renovatebot.com/renovate-schema.json",
+	"extends": [
+		"github>microsoft/vs-renovate-presets:microbuild",
+		"github>microsoft/vs-renovate-presets:vs_main_dependencies"
+	],
+	"packageRules": []
+}

.github/workflows/build.yml

@@ -39,22 +39,22 @@ jobs:
         }
       shell: pwsh
     - name: ⚙️ Set pipeline variables based on source
-      run: azure-pipelines/variables/_pipelines.ps1
+      run: tools/variables/_define.ps1
       shell: pwsh
     - name: 🛠 build
       run: dotnet build src -t:build,pack --no-restore -c ${{ env.BUILDCONFIGURATION }} /bl:"${{ runner.temp }}/_artifacts/build_logs/build.binlog"
     - name: 🧪 test
-      run: azure-pipelines/dotnet-test-cloud.ps1 -Configuration ${{ env.BUILDCONFIGURATION }} -Agent ${{ runner.os }}
+      run: tools/dotnet-test-cloud.ps1 -Configuration ${{ env.BUILDCONFIGURATION }} -Agent ${{ runner.os }}
       shell: pwsh
     - name: 💅🏻 Verify formatted code
       run: dotnet format --verify-no-changes --no-restore
       shell: pwsh
       if: runner.os == 'Linux'
     - name: ⚙ Update pipeline variables based on build outputs
-      run: azure-pipelines/variables/_pipelines.ps1
+      run: tools/variables/_define.ps1
       shell: pwsh
     - name: 📥 Collect artifacts
-      run: azure-pipelines/artifacts/_stage_all.ps1
+      run: tools/artifacts/_stage_all.ps1
       shell: pwsh
       if: always()
     - name: 📢 Upload project.assets.json files

.github/workflows/docs.yml

@@ -10,6 +10,7 @@ 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.
@@ -24,18 +25,20 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # 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
+      uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
       with:
         path: docfx/_site
 
     - name: Deploy to GitHub Pages
       id: deployment
-      uses: actions/deploy-pages@v4
+      uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.github/workflows/docs_validate.yml

@@ -0,0 +1,30 @@
+name: 📃 Docfx Validate
+
+on:
+  pull_request:
+  workflow_dispatch:
+  push:
+    branches:
+    - main
+    - microbuild
+
+jobs:
+  build:
+    name: 📚 Doc validation
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0 # avoid shallow clone so nbgv can do its work.
+    - name: 🔗 Markup Link Checker (mlc)
+      uses: becheran/mlc@v0.21.0
+      with:
+        args: --do-not-warn-for-redirect-to https://learn.microsoft.com*,https://dotnet.microsoft.com/*,https://dev.azure.com/*,https://app.codecov.io/* -p docfx -i https://aka.ms/onboardsupport,https://aka.ms/spot,https://msrc.microsoft.com/*,https://www.microsoft.com/msrc*,https://microsoft.com/msrc*
+    - name: ⚙ Install prerequisites
+      run: |
+        ./init.ps1 -UpgradePrerequisites
+        dotnet --info
+      shell: pwsh
+    - name: 📚 Verify docfx build
+      run: dotnet docfx docfx/docfx.json --warningsAsErrors --disableGitFeatures
+      if: runner.os == 'Linux'

.github/workflows/libtemplate-update.yml

@@ -1,4 +1,4 @@
-name: Library.Template update
+name: ⛜ Library.Template update
 
 # PREREQUISITE: This workflow requires the repo to be configured to allow workflows to create pull requests.
 # Visit https://github.com/USER/REPO/settings/actions
@@ -17,15 +17,15 @@ jobs:
       contents: write
       pull-requests: write
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # 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
         }
@@ -45,7 +45,7 @@ jobs:
 
         # 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
+        # So if the merge 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.
@@ -77,7 +77,7 @@ 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."
+        ⚠️ Do **not** squash this pull request when completing it. You must *merge* it.
 
         <details>
         <summary>Merge conflicts?</summary>
@@ -91,7 +91,7 @@ jobs:
         git commit
         git push
         ```
-        </details>
+        </details>"
 
         gh pr create -H auto/libtemplateUpdate -b $prBody -t $prTitle
       env:

CONTRIBUTING.md

@@ -11,6 +11,73 @@ https://cla.microsoft.com.
 
 ## Pull requests
 
-When you submit a pull request, a CLA-bot will automatically determine whether you need
-to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
-instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
+## Prerequisites
+
+All dependencies can be installed by running the `init.ps1` script at the root of the repository
+using Windows PowerShell or [PowerShell Core][pwsh] (on any OS).
+Some dependencies installed by `init.ps1` may only be discoverable from the same command line environment the init script was run from due to environment variables, so be sure to launch Visual Studio or build the repo from that same environment.
+Alternatively, run `init.ps1 -InstallLocality Machine` (which may require elevation) in order to install dependencies at machine-wide locations so Visual Studio and builds work everywhere.
+
+The only prerequisite for building, testing, and deploying from this repository
+is the [.NET SDK](https://get.dot.net/).
+You should install the version specified in `global.json` or a later version within
+the same major.minor.Bxx "hundreds" band.
+For example if 2.2.300 is specified, you may install 2.2.300, 2.2.301, or 2.2.310
+while the 2.2.400 version would not be considered compatible by .NET SDK.
+See [.NET Core Versioning](https://learn.microsoft.com/dotnet/core/versions/) for more information.
+
+## Package restore
+
+The easiest way to restore packages may be to run `init.ps1` which automatically authenticates
+to the feeds that packages for this repo come from, if any.
+`dotnet restore` or `nuget restore` also work but may require extra steps to authenticate to any applicable feeds.
+
+## Building
+
+This repository can be built on Windows, Linux, and OSX.
+
+Building, testing, and packing this repository can be done by using the standard dotnet CLI commands (e.g. `dotnet build`, `dotnet test`, `dotnet pack`, etc.).
+
+[pwsh]: https://docs.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-6
+
+## Releases
+
+Use `nbgv tag` to create a tag for a particular commit that you mean to release.
+[Learn more about `nbgv` and its `tag` and `prepare-release` commands](https://dotnet.github.io/Nerdbank.GitVersioning/docs/nbgv-cli.html).
+
+Push the tag.
+
+### GitHub Actions
+
+When your repo is hosted by GitHub and you are using GitHub Actions, you should create a GitHub Release using the standard GitHub UI.
+Having previously used `nbgv tag` and pushing the tag will help you identify the precise commit and name to use for this release.
+
+After publishing the release, the `.github\workflows\release.yml` workflow will be automatically triggered, which will:
+
+1. Find the most recent `.github\workflows\build.yml` GitHub workflow run of the tagged release.
+1. Upload the `deployables` artifact from that workflow run to your GitHub Release.
+1. If you have `NUGET_API_KEY` defined as a secret variable for your repo or org, any nuget packages in the `deployables` artifact will be pushed to nuget.org.
+
+### Azure Pipelines
+
+When your repo builds with Azure Pipelines, use the `azure-pipelines/release.yml` pipeline.
+Trigger the pipeline by adding the `auto-release` tag on a run of your main `azure-pipelines.yml` pipeline.
+
+## Tutorial and API documentation
+
+API and hand-written docs are found under the `docfx/` directory. and are built by [docfx](https://dotnet.github.io/docfx/).
+
+You can make changes and host the site locally to preview them by switching to that directory and running the `dotnet docfx --serve` command.
+After making a change, you can rebuild the docs site while the localhost server is running by running `dotnet docfx` again from a separate terminal.
+
+The `.github/workflows/docs.yml` GitHub Actions workflow publishes the content of these docs to github.io if the workflow itself and [GitHub Pages is enabled for your repository](https://docs.github.com/en/pages/quickstart).
+
+## Updating dependencies
+
+This repo uses Renovate to keep dependencies current.
+Configuration is in the `.github/renovate.json` file.
+[Learn more about configuring Renovate](https://docs.renovatebot.com/configuration-options/).
+
+When changing the renovate.json file, follow [these validation steps](https://docs.renovatebot.com/config-validation/).
+
+If Renovate is not creating pull requests when you expect it to, check that the [Renovate GitHub App](https://github.com/apps/renovate) is configured for your account or repo.