Fix toolchain version sorting and docs

Author: johnml1135

Build/Agent/FwBuildEnvironment.psm1

@@ -28,8 +28,27 @@ function Get-PreferredVcToolBinPath {
         return $null
     }
 
+    $versionSort = {
+        $parsedVersion = [version]'0.0'
+        $isVersion = [version]::TryParse($_.Name, [ref]$parsedVersion)
+        if ($isVersion) {
+            return $parsedVersion
+        }
+
+        return [version]'0.0'
+    }
+
+    $sortProperties = @(
+        @{ Expression = {
+                $parsedVersion = [version]'0.0'
+                [version]::TryParse($_.Name, [ref]$parsedVersion)
+            }; Descending = $true }
+        @{ Expression = $versionSort; Descending = $true }
+        @{ Expression = { $_.Name }; Descending = $true }
+    )
+
     $preferred = Get-ChildItem -Path $toolsRoot -Directory -ErrorAction SilentlyContinue |
-        Sort-Object Name -Descending |
+        Sort-Object -Property $sortProperties |
         ForEach-Object { Join-Path $_.FullName 'bin\HostX64\x64' } |
         Where-Object { Test-Path $_ } |
         Select-Object -First 1

Build/Agent/Verify-FwDependencies.ps1

@@ -5,6 +5,8 @@
 .DESCRIPTION
     Checks for required tools and SDKs needed to build FieldWorks.
     Can be run locally for testing or called from GitHub Actions workflows.
+    By default, the script writes host output only and does not emit result objects.
+    Use -PassThru when a caller needs structured results returned on the pipeline.
 
     Expected dependencies (typically pre-installed on windows-latest):
     - Visual Studio 2022 with Desktop & C++ workloads
@@ -24,7 +26,8 @@
     If specified, prints the full per-dependency section headers and success details instead of the compact summary-only output.
 
 .PARAMETER PassThru
-    If specified, returns the dependency result objects for scripting callers instead of writing them implicitly.
+    If specified, returns the dependency result objects for scripting callers.
+    Without -PassThru, the script is quiet-by-default and writes host output only.
 
 .EXAMPLE
     # Quick check
@@ -45,6 +48,9 @@
 .EXAMPLE
     # Capture structured results for automation
     $results = .\Build\Agent\Verify-FwDependencies.ps1 -IncludeOptional -PassThru
+
+.NOTES
+    Behavioral change: this script no longer emits dependency result objects unless -PassThru is specified.
 #>
 
 [CmdletBinding()]
@@ -217,7 +223,7 @@ $results += Test-Dependency -Name "WiX Toolset (v6 via NuGet)" -Required "Option
         throw "Installer project not found: $wixProj"
     }
 
-    [xml]$wixProjXml = Get-Content -LiteralPath $wixProj
+    [xml]$wixProjXml = Get-Content -LiteralPath $wixProj -Raw
     $projectNode = $wixProjXml.Project
     $hasWixSdk = $false
 

Build/Src/FwBuildTasks/Make.cs

@@ -121,8 +121,7 @@ private static string FindVisualStudioToolPath(string vcInstallDir, string toolN
 				return null;
 
 			string[] versionDirs = Directory.GetDirectories(toolsRoot);
-			Array.Sort(versionDirs, StringComparer.OrdinalIgnoreCase);
-			Array.Reverse(versionDirs);
+			Array.Sort(versionDirs, CompareVersionDirectories);
 
 			foreach (string versionDir in versionDirs)
 			{
@@ -144,6 +143,30 @@ private static string FindVisualStudioToolPath(string vcInstallDir, string toolN
 			return null;
 		}
 
+		private static int CompareVersionDirectories(string left, string right)
+		{
+			string leftName = Path.GetFileName(left);
+			string rightName = Path.GetFileName(right);
+
+			Version leftVersion;
+			Version rightVersion;
+			bool leftIsVersion = Version.TryParse(leftName, out leftVersion);
+			bool rightIsVersion = Version.TryParse(rightName, out rightVersion);
+
+			if (leftIsVersion && rightIsVersion)
+			{
+				int versionComparison = rightVersion.CompareTo(leftVersion);
+				if (versionComparison != 0)
+					return versionComparison;
+			}
+			else if (leftIsVersion != rightIsVersion)
+			{
+				return rightIsVersion.CompareTo(leftIsVersion);
+			}
+
+			return StringComparer.OrdinalIgnoreCase.Compare(rightName, leftName);
+		}
+
 		private void CheckToolPath()
 		{
 			string path = Environment.GetEnvironmentVariable("PATH");