Add dotnetup print-env-script command to generate shell environment configuration scripts (#52641)

Author: dsplaisted

.vsts-pr.yml

@@ -15,6 +15,7 @@ pr:
     - CODEOWNERS
     - .vsts-dnup-ci.yml
     - .vsts-dnup-pr.yml
+    - dotnetup.slnf
     - /eng/pipelines/templates/jobs/dotnetup/*
     - src/Installer/*
     - test/dotnetup.Tests/*

documentation/general/dotnetup/unix-environment-setup.md

@@ -0,0 +1,167 @@
+# Unix Environment Setup for dotnetup
+
+## Overview
+
+This document describes the design for setting up the .NET environment via initialization scripts using the `dotnetup print-env-script` command. This is the first step toward enabling automatic user profile configuration for Unix as described in [issue #51582](https://github.com/dotnet/sdk/issues/51582). Note that this also supports PowerShell and thus Windows, but on Windows the main method of configuring the environment will be to set environment variables which are stored in the registry instead of written by initialization scripts.
+
+## Background
+
+The dotnetup tool manages multiple .NET installations in a local user hive. For .NET to be accessible from the command line, the installation directory must be:
+1. Added to the `PATH` environment variable
+2. Set as the `DOTNET_ROOT` environment variable
+
+On Unix systems, this requires modifying shell configuration files (like `.bashrc`, `.zshrc`, etc.) or sourcing environment setup scripts.
+
+## Design Goals
+
+1. **Non-invasive**: Don't automatically modify user shell configuration files without explicit consent
+2. **Flexible**: Support multiple shells (bash, zsh, PowerShell)
+3. **Reversible**: Users should be able to easily undo environment changes
+4. **Single-file execution**: Generate scripts that can be sourced or saved for later use
+5. **Discoverable**: Make it easy for users to understand how to configure their environment
+
+## The `dotnetup print-env-script` Command
+
+### Command Structure
+
+```bash
+dotnetup print-env-script [--shell <shell>] [--dotnet-install-path <path>]
+```
+
+### Options
+
+- `--shell` / `-s`: The target shell for which to generate the environment script
+  - Supported values: `bash`, `zsh`, `pwsh`
+  - Optional: If not specified, automatically detects the current shell from the `$SHELL` environment variable
+  - On Windows, defaults to PowerShell (`pwsh`)
+
+- `--dotnet-install-path` / `-d`: The path to the .NET installation directory
+  - Optional: If not specified, uses the default user install path (`~/.local/share/dotnet` on Unix)
+
+### Usage Examples
+
+#### Auto-detect current shell
+```bash
+dotnetup print-env-script
+```
+
+#### Generate and source in one command
+```bash
+source <(dotnetup print-env-script)
+```
+
+#### Explicitly specify shell
+```bash
+dotnetup print-env-script --shell zsh
+```
+
+#### Save script for later use
+```bash
+dotnetup print-env-script --shell bash > ~/.dotnet-env.sh
+# Later, in .bashrc or manually:
+source ~/.dotnet-env.sh
+```
+
+#### Use custom installation path
+```bash
+dotnetup print-env-script --dotnet-install-path /opt/dotnet
+```
+
+## Generated Script Format
+
+The command generates shell-specific scripts that:
+1. Set the `DOTNET_ROOT` environment variable to the installation path
+2. Prepend the installation path to the `PATH` environment variable
+
+### Bash/Zsh Example
+```bash
+#!/usr/bin/env bash
+# This script configures the environment for .NET installed at /home/user/.local/share/dotnet
+# Source this script to add .NET to your PATH and set DOTNET_ROOT
+
+export DOTNET_ROOT='/home/user/.local/share/dotnet'
+export PATH='/home/user/.local/share/dotnet':$PATH
+```
+
+### PowerShell Example
+```powershell
+# This script configures the environment for .NET installed at /home/user/.local/share/dotnet
+# Source this script (dot-source) to add .NET to your PATH and set DOTNET_ROOT
+# Example: . ./dotnet-env.ps1
+
+$env:DOTNET_ROOT = '/home/user/.local/share/dotnet'
+$env:PATH = '/home/user/.local/share/dotnet' + [IO.Path]::PathSeparator + $env:PATH
+```
+
+## Implementation Details
+
+### Provider Model
+
+The implementation uses a provider model similar to `System.CommandLine.StaticCompletions`, making it easy to add support for additional shells in the future.
+
+**Interface**: `IEnvShellProvider`
+```csharp
+public interface IEnvShellProvider
+{
+    string ArgumentName { get; }           // Shell name for CLI (e.g., "bash")
+    string Extension { get; }               // File extension (e.g., "sh")
+    string? HelpDescription { get; }        // Help text for the shell
+    string GenerateEnvScript(string dotnetInstallPath);
+}
+```
+
+**Implementations**:
+- `BashEnvShellProvider`: Generates bash-compatible scripts
+- `ZshEnvShellProvider`: Generates zsh-compatible scripts
+- `PowerShellEnvShellProvider`: Generates PowerShell Core scripts
+
+### Shell Detection
+
+The command automatically detects the current shell when the `--shell` option is not provided:
+
+1. **On Unix**: Reads the `$SHELL` environment variable and extracts the shell name from the path
+   - Example: `/bin/bash` → `bash`
+2. **On Windows**: Defaults to PowerShell (`pwsh`)
+
+### Security Considerations
+
+**Path Escaping**: All installation paths are properly escaped to prevent shell injection vulnerabilities:
+- **Bash/Zsh**: Uses single quotes with `'\''` escaping for embedded single quotes
+- **PowerShell**: Uses single quotes with `''` escaping for embedded single quotes
+
+This ensures that paths containing special characters, spaces, or shell metacharacters are handled safely.
+
+## Advantages of Generated Scripts
+
+As noted in the discussion, generating scripts dynamically has several advantages over using embedded resource files:
+
+1. **Single-file execution**: Users can source the script directly from the command output without needing to extract files
+2. **Flexibility**: Easy to customize the installation path or add future features
+3. **No signing required**: Generated text doesn't require code signing, unlike downloaded executables or scripts
+4. **Immediate availability**: No download or extraction step needed
+5. **Transparency**: Users can easily inspect what the script does by running the command
+
+## Future Work
+
+This command provides the foundation for future enhancements:
+
+1. **Automatic profile modification**: Add a command to automatically update shell configuration files (`.bashrc`, `.zshrc`, etc.) with user consent
+2. **Profile backup**: Create backups of shell configuration files before modification
+3. **Uninstall/removal**: Add commands to remove dotnetup configuration from shell profiles
+4. **Additional shells**: Support for fish, tcsh, and other shells
+5. **Environment validation**: Commands to verify that the environment is correctly configured
+
+## Related Issues
+
+- [Issue #51582](https://github.com/dotnet/sdk/issues/51582): Parent issue tracking user profile modification on Unix
+- [dotnet/designs dnvm-e2e-experience](https://github.com/dotnet/designs/tree/dnvm-e2e-experience/proposed): Design proposal for local .NET hive management
+
+## Testing
+
+The implementation includes comprehensive tests:
+- Parser tests for command validation
+- Shell provider tests for script generation
+- Security tests for special character handling
+- Help documentation tests
+
+All tests ensure that the generated scripts are syntactically correct and properly escape paths.

dotnetup.slnf

@@ -5,7 +5,8 @@
       "src\\Installer\\dotnetup\\dotnetup.csproj",
       "src\\Installer\\Microsoft.Dotnet.Installation\\Microsoft.Dotnet.Installation.csproj",
       "test\\dotnetup.Tests\\dotnetup.Tests.csproj",
-      "src\\Resolvers\\Microsoft.DotNet.NativeWrapper\\Microsoft.DotNet.NativeWrapper.csproj"
+      "src\\Resolvers\\Microsoft.DotNet.NativeWrapper\\Microsoft.DotNet.NativeWrapper.csproj",
+      "src\\Cli\\Microsoft.DotNet.Cli.Utils\\Microsoft.DotNet.Cli.Utils.csproj"
     ]
   }
 }

src/Installer/Microsoft.Dotnet.Installation/Internal/DotnetArchiveExtractor.cs

@@ -310,6 +310,13 @@ private void ExtractTarFileEntry(TarEntry entry, string targetDir, IProgressTask
         using var outStream = File.Create(destPath);
         entry.DataStream?.CopyTo(outStream);
         installTask?.Value += 1;
+
+        // On Unix platforms, set the file permissions after extraction
+        if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+        {
+            File.SetUnixFileMode(destPath, entry.Mode);
+        }
+        
     }
 
     /// <summary>

src/Installer/dotnetup/ArchiveInstallationValidator.cs

@@ -103,6 +103,13 @@ public static bool ComponentFilesExist(DotnetInstall install)
 
     private bool ValidateWithHostFxr(string installRoot, ReleaseVersion resolvedVersion, InstallComponent component)
     {
+        if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+        {
+            //  Calling HostFxr is not working on Linux, so don't use it for validation until we fix that
+            //  See https://github.com/dotnet/sdk/issues/52821
+            return true;
+        }
+
         try
         {
             var environmentInfo = HostFxrWrapper.getInfo(installRoot);

src/Installer/dotnetup/Commands/PrintEnvScript/BashEnvShellProvider.cs

@@ -0,0 +1,35 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.DotNet.Tools.Bootstrapper.Commands.PrintEnvScript;
+
+public class BashEnvShellProvider : IEnvShellProvider
+{
+    public string ArgumentName => "bash";
+
+    public string Extension => "sh";
+
+    public string? HelpDescription => "Bash shell";
+
+    public override string ToString() => ArgumentName;
+
+    public string GenerateEnvScript(string dotnetInstallPath)
+    {
+        // Escape single quotes in the path for bash by replacing ' with '\''
+        var escapedPath = dotnetInstallPath.Replace("'", "'\\''");
+
+        return
+            $"""
+            #!/usr/bin/env bash
+            # This script configures the environment for .NET installed at {dotnetInstallPath}
+            # Source this script to add .NET to your PATH and set DOTNET_ROOT
+            #
+            # Note: If you had a different dotnet in PATH before sourcing this script,
+            # you may need to run 'hash -d dotnet' to clear the cached command location.
+            # When dotnetup modifies shell profiles directly, it will handle this automatically.
+
+            export DOTNET_ROOT='{escapedPath}'
+            export PATH='{escapedPath}':$PATH
+            """;
+    }
+}

src/Installer/dotnetup/Commands/PrintEnvScript/IEnvShellProvider.cs

@@ -0,0 +1,32 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.DotNet.Tools.Bootstrapper.Commands.PrintEnvScript;
+
+/// <summary>
+/// Provides shell-specific environment configuration scripts.
+/// </summary>
+public interface IEnvShellProvider
+{
+    /// <summary>
+    /// The name of this shell as exposed on the command line arguments.
+    /// </summary>
+    string ArgumentName { get; }
+
+    /// <summary>
+    /// The file extension typically used for this shell's scripts (sans period).
+    /// </summary>
+    string Extension { get; }
+
+    /// <summary>
+    /// This will be used when specifying the shell in CLI help text.
+    /// </summary>
+    string? HelpDescription { get; }
+
+    /// <summary>
+    /// Generates a shell-specific script that configures PATH and DOTNET_ROOT.
+    /// </summary>
+    /// <param name="dotnetInstallPath">The path to the .NET installation directory</param>
+    /// <returns>A shell script that can be sourced to configure the environment</returns>
+    string GenerateEnvScript(string dotnetInstallPath);
+}

src/Installer/dotnetup/Commands/PrintEnvScript/PowerShellEnvShellProvider.cs

@@ -0,0 +1,31 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.DotNet.Tools.Bootstrapper.Commands.PrintEnvScript;
+
+public class PowerShellEnvShellProvider : IEnvShellProvider
+{
+    public string ArgumentName => "pwsh";
+
+    public string Extension => "ps1";
+
+    public string? HelpDescription => "PowerShell Core (pwsh)";
+
+    public override string ToString() => ArgumentName;
+
+    public string GenerateEnvScript(string dotnetInstallPath)
+    {
+        // Escape single quotes in the path for PowerShell by replacing ' with ''
+        var escapedPath = dotnetInstallPath.Replace("'", "''");
+
+        return
+            $"""
+            # This script configures the environment for .NET installed at {dotnetInstallPath}
+            # Source this script (dot-source) to add .NET to your PATH and set DOTNET_ROOT
+            # Example: . ./dotnet-env.ps1
+            
+            $env:DOTNET_ROOT = '{escapedPath}'
+            $env:PATH = '{escapedPath}' + [IO.Path]::PathSeparator + $env:PATH
+            """;
+    }
+}

src/Installer/dotnetup/Commands/PrintEnvScript/PrintEnvScriptCommand.cs

@@ -0,0 +1,61 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.CommandLine;
+
+namespace Microsoft.DotNet.Tools.Bootstrapper.Commands.PrintEnvScript;
+
+internal class PrintEnvScriptCommand : CommandBase
+{
+    private readonly IEnvShellProvider? _shellProvider;
+    private readonly string? _dotnetInstallPath;
+    private readonly IDotnetInstallManager _dotnetInstaller;
+
+    public PrintEnvScriptCommand(ParseResult result, IDotnetInstallManager? dotnetInstaller = null) : base(result)
+    {
+        _dotnetInstaller = dotnetInstaller ?? new DotnetInstallManager();
+        _shellProvider = result.GetValue(PrintEnvScriptCommandParser.ShellOption);
+        _dotnetInstallPath = result.GetValue(PrintEnvScriptCommandParser.DotnetInstallPathOption);
+    }
+
+    public override int Execute()
+    {
+        try
+        {
+            // Check if shell provider was successfully determined
+            if (_shellProvider == null)
+            {
+                var shellPath = Environment.GetEnvironmentVariable("SHELL");
+                if (shellPath is null)
+                {
+                    Console.Error.WriteLine("Error: Unable to detect current shell. The SHELL environment variable is not set.");
+                    Console.Error.WriteLine($"Please specify the shell using --shell option. Supported shells: {string.Join(", ", PrintEnvScriptCommandParser.SupportedShells.Select(s => s.ArgumentName))}");
+                }
+                else
+                {
+                    var shellName = Path.GetFileName(shellPath);
+                    Console.Error.WriteLine($"Error: Unsupported shell '{shellName}'.");
+                    Console.Error.WriteLine($"Supported shells: {string.Join(", ", PrintEnvScriptCommandParser.SupportedShells.Select(s => s.ArgumentName))}");
+                    Console.Error.WriteLine("Please specify the shell using --shell option.");
+                }
+                return 1;
+            }
+
+            // Determine the dotnet install path
+            string installPath = _dotnetInstallPath ?? _dotnetInstaller.GetDefaultDotnetInstallPath();
+
+            // Generate the shell script
+            string script = _shellProvider.GenerateEnvScript(installPath);
+
+            // Output the script to stdout
+            Console.WriteLine(script);
+
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            Console.Error.WriteLine($"Error generating environment script: {ex.Message}");
+            return 1;
+        }
+    }
+}