Merge pull request #105 from AArnott/libtemplateUpdate

Merge latest Library.Template

.config/dotnet-tools.json

@@ -3,22 +3,32 @@
   "isRoot": true,
   "tools": {
     "powershell": {
-      "version": "7.4.5",
+      "version": "7.4.6",
       "commands": [
         "pwsh"
-      ]
+      ],
+      "rollForward": false
     },
     "dotnet-coverage": {
-      "version": "17.12.5",
+      "version": "17.12.6",
       "commands": [
         "dotnet-coverage"
-      ]
+      ],
+      "rollForward": false
     },
     "nbgv": {
-      "version": "3.6.143",
+      "version": "3.6.146",
       "commands": [
         "nbgv"
-      ]
+      ],
+      "rollForward": false
+    },
+    "docfx": {
+      "version": "2.78.1",
+      "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.400-jammy
+FROM mcr.microsoft.com/dotnet/sdk:9.0.100-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.

.devcontainer/devcontainer.json

@@ -10,11 +10,12 @@
     "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",
-    "ms-vscode.powershell"
+    "tintoy.msbuild-project-tools"
   ]
 }

.github/dependabot.yml

@@ -7,3 +7,7 @@ updates:
   directory: /
   schedule:
     interval: weekly
+- package-ecosystem: dotnet-sdk
+  directory: /
+  schedule:
+    interval: monthly

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+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
+
+# 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
+    - 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/libtemplate-update.yml

@@ -0,0 +1,98 @@
+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
+# Under "Workflow permissions" check "Allow GitHub Actions to create ...pull requests"
+# Click Save.
+
+on:
+  schedule:
+  - cron: "0 3 * * Mon" # Sun @ 8 or 9 PM Mountain Time (depending on DST)
+  workflow_dispatch:
+
+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
+        if ($LASTEXITCODE -ne 0) {
+          exit $LASTEXITCODE
+        }
+
+        git fetch https://github.com/aarnott/Library.Template $LibTemplateBranch
+        if ($LASTEXITCODE -ne 0) {
+          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
+        }
+
+        # 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 "andrewarnott@live.com"
+          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
+        if ($existingPR) {
+          Write-Host "::warning::Skipping pull request creation because one already exists at $($existingPR[0].url)"
+          exit 0
+        }
+
+        $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:
+
+        ```
+        git fetch
+        git checkout auto/libtemplateUpdate
+        git merge origin/main
+        # resolve conflicts
+        git commit
+        git push
+        ```
+        </details>"
+
+        gh pr create -H auto/libtemplateUpdate -b $prBody -t $prTitle
+      env:
+        GH_TOKEN: ${{ github.token }}

.gitignore

@@ -37,6 +37,9 @@ bld/
 # Uncomment if you have tasks that create the project's static files in wwwroot
 #wwwroot/
 
+# Jetbrains Rider cache directory
+.idea/
+
 # Visual Studio 2017 auto generated files
 Generated\ Files/
 

Directory.Build.props

@@ -51,7 +51,7 @@
 
   <Target Name="PrepareReleaseNotes" BeforeTargets="GenerateNuspec" DependsOnTargets="GetBuildVersion">
     <PropertyGroup>
-      <PackageReleaseNotes Condition="'$(PackageProjectUrl)'!=''">$(PackageProjectUrl)/releases/tag/v$(Version)</PackageReleaseNotes>
+      <PackageReleaseNotes Condition="'$(RepositoryUrl)'!=''">$(RepositoryUrl)/releases/tag/v$(Version)</PackageReleaseNotes>
     </PropertyGroup>
   </Target>
 </Project>

Directory.Build.targets

@@ -5,7 +5,7 @@
   </ItemGroup>
 
   <PropertyGroup>
-    <LangVersion Condition="'$(Language)'=='C#'">12</LangVersion>
+    <LangVersion Condition="'$(Language)'=='C#'">13</LangVersion>
     <LangVersion Condition="'$(Language)'=='VB'">16.9</LangVersion>
   </PropertyGroup>
   <ItemGroup>

Directory.Packages.props

@@ -6,17 +6,17 @@
     <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
   </PropertyGroup>
   <ItemGroup>
-    <PackageVersion Include="IsExternalInit" Version="1.0.3" />
-    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
     <PackageVersion Include="Validation" Version="2.5.51" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
     <PackageVersion Include="xunit" Version="2.9.2" />
   </ItemGroup>
   <ItemGroup>
     <GlobalPackageReference Include="CSharpIsNullAnalyzer" Version="0.1.593" />
     <GlobalPackageReference Include="DotNetAnalyzers.DocumentationAnalyzers" Version="1.0.0-beta.59" />
-    <GlobalPackageReference Include="Nerdbank.GitVersioning" Version="3.6.143" />
-    <GlobalPackageReference Include="Nullable" Version="1.3.1" />
+    <!-- The condition works around https://github.com/dotnet/sdk/issues/44951 -->
+    <GlobalPackageReference Include="Nerdbank.GitVersioning" Version="3.6.146" Condition="!('$(TF_BUILD)'=='true' and '$(dotnetformat)'=='true')" />
+    <GlobalPackageReference Include="PolySharp" Version="1.15.0" />
     <GlobalPackageReference Include="StyleCop.Analyzers.Unstable" Version="1.2.0.556" />
   </ItemGroup>
-</Project>
+</Project>

azure-pipelines/Get-CodeCovTool.ps1

@@ -68,7 +68,7 @@ if (!(Test-Path $finalToolPath)) {
     }
 
     Write-Host "Verifying hash on downloaded tool" -ForegroundColor Yellow
-    $actualHash = (Get-FileHash -Path $tool -Algorithm SHA256).Hash
+    $actualHash = (Get-FileHash -LiteralPath $tool -Algorithm SHA256).Hash
     $expectedHash = (Get-Content $sha).Split()[0]
     if ($actualHash -ne $expectedHash) {
         # Validation failed. Delete the tool so we can't execute it.

azure-pipelines/Get-LibTemplateBasis.ps1

@@ -0,0 +1,25 @@
+<#
+.SYNOPSIS
+    Returns the name of the well-known branch in the Library.Template repository upon which HEAD is based.
+#>
+[CmdletBinding(SupportsShouldProcess = $true)]
+Param(
+    [switch]$ErrorIfNotRelated
+)
+
+# This list should be sorted in order of decreasing specificity.
+$branchMarkers = @(
+    @{ commit = 'fd0a7b25ccf030bbd16880cca6efe009d5b1fffc'; branch = 'microbuild' };
+    @{ commit = '05f49ce799c1f9cc696d53eea89699d80f59f833'; branch = 'main' };
+)
+
+foreach ($entry in $branchMarkers) {
+    if (git rev-list HEAD | Select-String -Pattern $entry.commit) {
+        return $entry.branch
+    }
+}
+
+if ($ErrorIfNotRelated) {
+    Write-Error "Library.Template has not been previously merged with this repo. Please review https://github.com/AArnott/Library.Template/tree/main?tab=readme-ov-file#readme for instructions."
+    exit 1
+}

azure-pipelines/Merge-CodeCoverage.ps1

@@ -28,7 +28,7 @@ try {
     if ($reports) {
         $reports |% { $_.FullName } |% {
             # In addition to replacing {reporoot}, we also normalize on one kind of slash so that the report aggregates data for a file whether data was collected on Windows or not.
-            $xml = [xml](Get-Content -Path $_)
+            $xml = [xml](Get-Content -LiteralPath $_)
             $xml.coverage.packages.package.classes.class |? { $_.filename} |% {
                 $_.filename = $_.filename.Replace('{reporoot}', $RepoRoot).Replace([IO.Path]::AltDirectorySeparatorChar, [IO.Path]::DirectorySeparatorChar)
             }

azure-pipelines/artifacts/Variables.ps1

@@ -32,10 +32,10 @@ Get-ChildItem "$PSScriptRoot/../variables" |% {
 
     # If that didn't get us anything, just copy the script itself
     if (-not $value) {
-        $value = Get-Content -Path $_.FullName
+        $value = Get-Content -LiteralPath $_.FullName
     }
 
-    Set-Content -Path "$VariablesArtifactPath/$($_.Name)" -Value $value
+    Set-Content -LiteralPath "$VariablesArtifactPath/$($_.Name)" -Value $value
 }
 
 @{

azure-pipelines/artifacts/_pipelines.ps1

@@ -16,7 +16,7 @@ Function Set-PipelineVariable($name, $value) {
         return # already set
     }
 
-    #New-Item -Path "Env:\$name".ToUpper() -Value $value -Force | Out-Null
+    #New-Item -LiteralPath "Env:\$name".ToUpper() -Value $value -Force | Out-Null
     Write-Host "##vso[task.setvariable variable=$name]$value"
 }
 

azure-pipelines/artifacts/_stage_all.ps1

@@ -51,7 +51,7 @@ $Artifacts |% {
     if (Test-Path -PathType Leaf $_.Source) { # skip folders
         $TargetPath = Join-Path $DestinationFolder $Name
         if ($AvoidSymbolicLinks) {
-            Copy-Item -Path $_.Source -Destination $TargetPath
+            Copy-Item -LiteralPath $_.Source -Destination $TargetPath
         } else {
             Create-SymbolicLink -Link $TargetPath -Target $_.Source
         }

azure-pipelines/artifacts/coverageResults.ps1

@@ -6,8 +6,8 @@ $coverageFiles = @(Get-ChildItem "$RepoRoot/test/*.cobertura.xml" -Recurse | Whe
 if ($env:SYSTEM_DEFAULTWORKINGDIRECTORY) {
     Write-Host "Substituting $env:SYSTEM_DEFAULTWORKINGDIRECTORY with `"{reporoot}`""
     $coverageFiles |% {
-        $content = Get-Content -Path $_ |% { $_ -Replace [regex]::Escape($env:SYSTEM_DEFAULTWORKINGDIRECTORY), "{reporoot}" }
-        Set-Content -Path $_ -Value $content -Encoding UTF8
+        $content = Get-Content -LiteralPath $_ |% { $_ -Replace [regex]::Escape($env:SYSTEM_DEFAULTWORKINGDIRECTORY), "{reporoot}" }
+        Set-Content -LiteralPath $_ -Value $content -Encoding UTF8
     }
 } else {
     Write-Warning "coverageResults: Azure Pipelines not detected. Machine-neutral token replacement skipped."

azure-pipelines/build.yml

@@ -27,7 +27,7 @@ jobs:
 
 - job: Linux
   pool:
-    vmImage: Ubuntu 20.04
+    vmImage: Ubuntu-22.04
   steps:
   - checkout: self
     fetchDepth: 0 # avoid shallow clone so nbgv can do its work.
@@ -36,13 +36,15 @@ jobs:
   - template: dotnet.yml
     parameters:
       RunTests: ${{ parameters.RunTests }}
-  - script: dotnet format --verify-no-changes --no-restore
+  - script: dotnet format --verify-no-changes
     displayName: 💅 Verify formatted code
+    env:
+      dotnetformat: true # part of a workaround for https://github.com/dotnet/sdk/issues/44951
 
 - job: macOS
   condition: ${{ parameters.includeMacOS }}
   pool:
-    vmImage: macOS-12
+    vmImage: macOS-14
   steps:
   - checkout: self
     fetchDepth: 0 # avoid shallow clone so nbgv can do its work.

azure-pipelines/dotnet-test-cloud.ps1

@@ -61,7 +61,7 @@ Get-ChildItem -Recurse -Path $RepoRoot\test\*.trx |% {
   Copy-Item $_ -Destination $ArtifactStagingFolder/test_logs/
 
   if ($PublishResults) {
-    $x = [xml](Get-Content -Path $_)
+    $x = [xml](Get-Content -LiteralPath $_)
     $runTitle = $null
     if ($x.TestRun.TestDefinitions -and $x.TestRun.TestDefinitions.GetElementsByTagName('UnitTest')) {
       $storage = $x.TestRun.TestDefinitions.GetElementsByTagName('UnitTest')[0].storage -replace '\\','/'