dotnetup: classify PATH dotnet by managed hive; fix env config doc

documentation/general/dotnetup/designs/dotnetup-env.md

@@ -154,9 +154,11 @@ DotnetAccessMode.Shell      = old ShellProfile         // shell profile file onl
 DotnetAccessMode.Everywhere = old FullPathReplacement  // env-var PATH + shell profile
 ```
 
-The JSON serialization writes the new lowercase names (`none` / `shell` / `everywhere`).
-On read, the converter also accepts the legacy spellings (`full`, `fullpathreplacement`,
-etc.) so configs written by earlier internal builds keep their chosen mode.
+The JSON serialization writes the new lowercase names (`none` / `shell` / `everywhere`)
+via the built-in string-enum converter (camel-case, integer values rejected). Legacy
+spellings from earlier internal builds (`full` / `fullpathreplacement`, and the old
+`pathPreference` property) are **not** accepted: an unrecognized value is treated as a
+corrupt config, which re-defaults on the next write rather than silently mapping to a mode.
 
 ## `dotnetup` on PATH: an orthogonal setting
 

src/Installer/dotnetup.Library/Commands/Dotnet/DotnetCommand.cs

@@ -59,13 +59,13 @@ protected override void ExecuteCore()
     }
 
     /// <summary>
-    /// Resolves the dotnet installation path using the same logic as other dotnetup commands:
-    /// configured install type (user install) falls back to the default install path.
+    /// Resolves the dotnet installation path: when the PATH-resolved install is a
+    /// dotnetup-managed hive, use it; otherwise fall back to the default install path.
     /// </summary>
     private string ResolveDotnetPath()
     {
         var configuredRoot = _dotnetEnvironment.GetCurrentPathConfiguration();
-        if (configuredRoot is not null && configuredRoot.InstallType == InstallType.User)
+        if (configuredRoot is { IsDotnetupHive: true })
         {
             return configuredRoot.Path;
         }

src/Installer/dotnetup.Library/Commands/Init/InitWorkflows.cs

@@ -446,9 +446,10 @@ internal static List<string> FormatMigrationDisplayItems(List<MigrationWorkflow.
             return [];
         }
 
-        // Find the system install path for display purposes
+        // Find the system install path for display purposes. Whether the dotnet winning on PATH is
+        // a dotnetup hive is irrelevant here; we want its location only when it is a system install.
         var currentInstall = dotnetEnvironment.GetCurrentPathConfiguration();
-        string systemPath = currentInstall?.InstallType == InstallType.System
+        string systemPath = currentInstall is not null && InstallPathClassifier.IsAdminInstallPath(currentInstall.Path)
             ? currentInstall.Path
             : DotnetEnvironmentManager.GetSystemDotnetPaths().FirstOrDefault() ?? "the system .NET location";
 

src/Installer/dotnetup.Library/Commands/Shared/InstallPathClassifier.cs

@@ -10,9 +10,12 @@ namespace Microsoft.DotNet.Tools.Bootstrapper.Commands.Shared;
 internal static class InstallPathClassifier
 {
     /// <summary>
-    /// Determines whether the given path is an admin/system-managed .NET install location.
-    /// These locations are managed by system package managers or OS installers and should not
-    /// be used by dotnetup for user-level installations.
+    /// Determines whether the given path is in a well-known system/admin .NET install location
+    /// (for example <c>Program Files\dotnet</c> on Windows).  These locations are usually managed
+    /// by system package managers or OS installers and should not be used by dotnetup.
+    /// 
+    /// This is a location heuristic only, it doesn't verify that the install there is actually managed
+    /// by an OS installer or package manager.
     /// </summary>
     public static bool IsAdminInstallPath(string path)
     {

src/Installer/dotnetup.Library/Commands/Shared/InstallWorkflow.cs

@@ -338,7 +338,7 @@ private void RecordInstallTelemetry(
         _command.SetCommandTag(TelemetryTagNames.InstallRequestedVersion, VersionSanitizer.Sanitize(requestedVersionOrChannel));
         _command.SetCommandTag(TelemetryTagNames.InstallPathExplicit, (explicitInstallPath is not null).ToString());
         _command.SetCommandTag(TelemetryTagNames.InstallHasGlobalJson, (globalJson?.GlobalJsonPath is not null).ToString());
-        _command.SetCommandTag(TelemetryTagNames.InstallExistingInstallType, currentInstallRoot?.InstallType.ToString() ?? "none");
+        _command.SetCommandTag(TelemetryTagNames.InstallExistingInstallType, currentInstallRoot is null ? "none" : InstallPathClassifier.ClassifyInstallPath(currentInstallRoot.Path));
         _command.SetCommandTag(TelemetryTagNames.InstallPathType, InstallPathClassifier.ClassifyInstallPath(pathResolution.ResolvedInstallPath, pathResolution.PathSource));
         _command.SetCommandTag(TelemetryTagNames.InstallPathSource, pathResolution.PathSource.ToString().ToLowerInvariant());
         _command.SetCommandTag(TelemetryTagNames.InstallResolvedVersion, resolved.ResolvedVersion.ToString());

src/Installer/dotnetup.Library/Commands/Shared/UninstallWorkflow.cs

@@ -155,7 +155,9 @@ private static void CheckAndReportStillPresent(
 
     /// <summary>
     /// Resolves the install path for uninstall using the same logic as the install command:
-    /// only use the configured path if it's a user install, otherwise fall back to default.
+    /// only use the configured path if it is a dotnetup-managed hive, otherwise fall back to
+    /// default. This prevents uninstall from targeting a dotnet that dotnetup does not own (e.g.
+    /// a system install or a hand-extracted dotnet that happens to win on PATH).
     /// </summary>
     internal static string ResolveInstallPath(string? explicitInstallPath, IDotnetEnvironmentManager dotnetEnvironment)
     {
@@ -165,7 +167,7 @@ internal static string ResolveInstallPath(string? explicitInstallPath, IDotnetEn
         }
 
         var configuredInstall = dotnetEnvironment.GetCurrentPathConfiguration();
-        if (configuredInstall is { InstallType: InstallType.User })
+        if (configuredInstall is { IsDotnetupHive: true })
         {
             return configuredInstall.Path;
         }

src/Installer/dotnetup.Library/DotnetEnvironmentManager.cs

@@ -2,7 +2,6 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using Microsoft.Dotnet.Installation.Internal;
-using Microsoft.DotNet.Tools.Bootstrapper.Commands.Shared;
 using Microsoft.DotNet.Tools.Bootstrapper.Shell;
 using Microsoft.DotNet.Tools.Bootstrapper.Telemetry;
 using Spectre.Console;
@@ -43,11 +42,22 @@ public DotnetEnvironmentManager()
             ResolveCurrentInstallRootPath(foundDotnet),
             InstallerUtilities.GetDefaultInstallArchitecture());
 
-        // Classify the resolved dotnet by location. InstallPathClassifier.IsAdminInstallPath is the
-        // canonical "is this a system/admin-managed install?" check (Program Files on Windows; the
-        // standard /usr and /opt locations on Unix) used across dotnetup, so both platforms share it.
-        bool isAdminInstall = InstallPathClassifier.IsAdminInstallPath(currentInstallRoot.Path);
-        return new(currentInstallRoot, isAdminInstall ? InstallType.System : InstallType.User);
+        // Report whether the resolved dotnet is a dotnetup-managed hive — an install dotnetup owns
+        // and may run or uninstall from — rather than classifying it as "system vs user". A dotnet
+        // that merely lives in a user-writable location (e.g. a hand-extracted C:\dotnet on PATH) is
+        // NOT dotnetup's and must not be treated as such. Today the only supported hive is the
+        // default install path; configurable hives are tracked in
+        // https://github.com/dotnet/sdk/issues/55346, at which point this check would also consult
+        // the persisted root.
+        //
+        // Resolve the default path's symlinks too so the comparison is symmetric: currentInstallRoot.Path
+        // is already realpath-resolved above, and the default path's base (LocalApplicationData /
+        // XDG_DATA_HOME, which is not required to be a real directory) may itself be a symlink. Without
+        // this, a symlinked data directory would make dotnetup fail to recognize its own hive.
+        string defaultInstallPath = GetDefaultDotnetInstallPath();
+        string resolvedDefaultInstallPath = ExecutablePathResolver.ResolveRealPath(defaultInstallPath) ?? defaultInstallPath;
+        bool isDotnetupHive = DotnetupUtilities.PathsEqual(currentInstallRoot.Path, resolvedDefaultInstallPath);
+        return new(currentInstallRoot, isDotnetupHive);
     }
 
     public string GetDefaultDotnetInstallPath()

src/Installer/dotnetup.Library/DotnetupPaths.cs

@@ -121,10 +121,19 @@ public static string ManifestPath
     /// Gets the default dotnet install path managed by dotnetup.
     /// This is the user-local dotnet root (e.g. %LOCALAPPDATA%\dotnet on Windows).
     /// </summary>
+    /// <remarks>
+    /// Can be overridden via DOTNET_TESTHOOK_DEFAULT_DOTNET_PATH environment variable.
+    /// </remarks>
     public static string DefaultDotnetInstallPath
     {
         get
         {
+            var overridePath = Environment.GetEnvironmentVariable("DOTNET_TESTHOOK_DEFAULT_DOTNET_PATH");
+            if (!string.IsNullOrEmpty(overridePath))
+            {
+                return overridePath;
+            }
+
             var baseDir = GetBaseDirectory();
             if (string.IsNullOrEmpty(baseDir))
             {

src/Installer/dotnetup.Library/ExecutablePathResolver.cs

@@ -22,13 +22,28 @@ internal static class ExecutablePathResolver
     /// </summary>
     public static string? ResolveRealDirectory(string? executablePath)
     {
-        if (string.IsNullOrEmpty(executablePath))
+        string? resolvedPath = ResolveRealPath(executablePath);
+        return resolvedPath is null ? null : Path.GetDirectoryName(resolvedPath);
+    }
+
+    /// <summary>
+    /// Returns <paramref name="path"/> itself with symlinks resolved (unlike
+    /// <see cref="ResolveRealDirectory"/>, which resolves the containing directory of an
+    /// executable). Use this to canonicalize a directory that may be reached through a symlinked
+    /// parent, such as a dotnet install root under a symlinked <c>LocalApplicationData</c> /
+    /// <c>XDG_DATA_HOME</c>. Returns <c>null</c> when the path is null or empty.
+    /// <see cref="FileInterop.ResolveRealPath"/> is a no-op on Windows, and on Unix returns
+    /// <c>null</c> for a path that does not yet exist; in both cases the normalized full path is
+    /// returned so callers still get a usable value.
+    /// </summary>
+    public static string? ResolveRealPath(string? path)
+    {
+        if (string.IsNullOrEmpty(path))
         {
             return null;
         }
 
-        string fullPath = Path.GetFullPath(executablePath);
-        string resolvedPath = FileInterop.ResolveRealPath(fullPath) ?? fullPath;
-        return Path.GetDirectoryName(resolvedPath);
+        string fullPath = Path.GetFullPath(path);
+        return FileInterop.ResolveRealPath(fullPath) ?? fullPath;
     }
 }

src/Installer/dotnetup.Library/IDotnetEnvironmentManager.cs

@@ -16,6 +16,11 @@ internal interface IDotnetEnvironmentManager
 {
     string GetDefaultDotnetInstallPath();
 
+    /// <summary>
+    /// Resolves the <c>dotnet</c> that currently wins on <c>PATH</c> and reports whether it is a
+    /// dotnetup-managed hive (i.e. an install dotnetup owns and may run or uninstall from).
+    /// Returns <c>null</c> when no <c>dotnet</c> is found on <c>PATH</c>.
+    /// </summary>
     DotnetInstallRootConfiguration? GetCurrentPathConfiguration();
 
     string? GetLatestInstalledSystemVersion();
@@ -75,7 +80,7 @@ public string? SdkPath
 
 public record DotnetInstallRootConfiguration(
     DotnetInstallRoot InstallRoot,
-    InstallType InstallType)
+    bool IsDotnetupHive)
 {
     public string Path => InstallRoot.Path;
 }

src/Installer/dotnetup.Library/Strings.resx

@@ -163,7 +163,7 @@
     <value>Arguments to forward to dotnet.</value>
   </data>
   <data name="DotnetCommandDotnetNotFound" xml:space="preserve">
-    <value>Error: dotnet executable not found at '{0}'.</value>
+    <value>dotnet executable not found at '{0}'.</value>
   </data>
   <data name="DotnetCommandInstallFirst" xml:space="preserve">
     <value>Run 'dotnetup install' to install a .NET SDK first.</value>
@@ -283,7 +283,7 @@ Or open a new terminal.</value>
     <value>Open a new terminal for the change to take effect.</value>
   </data>
   <data name="EnvOpenNewTerminalForOtherSurfaces" xml:space="preserve">
-    <value>Open a new terminal for the change to take effect in other terminals and applications.</value>
+    <value>Other open terminals and applications will pick up this change after they're restarted.</value>
   </data>
   <data name="EnvShellRequiredForProfile" xml:space="preserve">
     <value>Could not detect the current shell, which is required to update the dotnetup profile entry. Re-run with --shell &lt;{0}&gt; to specify it explicitly.</value>