Skip to content

Add Python and uv installation validation with user notifications - #12787

Merged
David Fowler (davidfowl) merged 15 commits into
mainfrom
copilot/open-new-pr-contents
Nov 8, 2025
Merged

David Fowler (davidfowl) merged 15 commits into
mainfrom
copilot/open-new-pr-contents

Conversation

Copilot AI commented Nov 7, 2025 •

Copy link
Copy Markdown
Contributor

Description

This PR adds a notification system that guides developers when Python or uv are not installed before Python resources start. The validation shows helpful notifications with installation instructions but allows the application to fail naturally, preserving the original error behavior.

Shared Infrastructure (Internal Shared Source)

  • Moved CoalescingAsyncOperation and RequiredCommandValidator to src/Shared/ as internal shared source code
  • Files are compiled only into projects that use them (Aspire.Hosting.DevTunnels, Aspire.Hosting.Python) via <Compile Include="$(SharedDir)..."> references
  • RequiredCommandValidator provides base pattern for validating executable presence on PATH with configurable exception behavior
  • CoalescingAsyncOperation ensures single concurrent execution while coalescing multiple callers
  • Message strings parameterized via protected virtual methods with default string literals
  • OnResolvedAsync is protected internal virtual to allow test access
  • Added throwOnFailure parameter to control exception throwing behavior
  • No InternalsVisibleTo attributes needed

Python Environment Validation

  • Created PythonInstallationManager and UvInstallationManager classes extending RequiredCommandValidator
  • PythonInstallationManager validates Python for PythonVenvCreatorResource (before venv creation)
  • UvInstallationManager validates uv for PythonInstallerResource (when using uv package manager)
  • UvInstallationManager is also registered explicitly in the WithUv extension method for consistency
  • Validation added via OnBeforeResourceStarted hooks on child resources
  • Both resources have ExcludeFromManifest ensuring they only exist in RunMode
  • Uses throwOnFailure: false to show helpful notifications without preventing natural failure behavior
  • Uses IInteractionService to show notifications when commands are not found
  • Installation links: Python (https://www.python.org/downloads/), uv (https://docs.astral.sh/uv/getting-started/installation/)

DevTunnels Updates

  • Updated to consume shared utilities from src/Shared/ directory
  • OnResolvedAsync is protected internal override to maintain testability
  • No behavioral changes

Key Implementation Details

  1. Validation placement: Hooks are on child resources (PythonVenvCreatorResource and PythonInstallerResource), not the parent
  2. Python validation: Runs before venv creation via PythonVenvCreatorResource
  3. uv validation: Runs before package installation when uv is the package manager via PythonInstallerResource
  4. Additional uv registration: UvInstallationManager is also explicitly registered in the WithUv method for clarity
  5. Exception behavior: Added EnsureInstalledAsync(bool throwOnFailure = true) overload
    • Default is true (throws on failure) for backward compatibility
    • Set to false for Python and uv validation to allow natural app failure while showing notifications
  6. RunMode enforcement: Child resources use ExcludeFromManifest (implicit RunMode-only behavior)
  7. No changes to Aspire.Hosting resource strings - reverted unused resource string additions

Testing Results

  • ✅ All 28 DevTunnels tests passed
  • ✅ All 92 Python tests passed
  • ✅ Build verification successful for all projects
  • ✅ No InternalsVisibleTo needed - using shared source code pattern

Checklist

  • Is this feature complete?
    • Yes. Ready to ship.
    • No. Follow-up changes expected.
  • Are you including unit tests for the changes and scenario tests if relevant?
    • Yes
    • No
  • Did you add public API?
    • Yes
    • No
  • Does the change make any security assumptions or guarantees?
    • Yes
    • No
  • Does the change require an update in our Aspire docs?
    • Yes
    • No
Original prompt

Open a new PR with the contents of #12663


💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Copilot AI and others added 3 commits November 7, 2025 02:14
Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
…move venv check and logging

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
Copilot AI changed the title [WIP] Open new pull request with existing contents Add Python and uv installation validation with user notifications Nov 7, 2025
@davidfowl

Copy link
Copy Markdown
Collaborator

Copilot Don't make RequiredCommandValidator and CoalescingAsyncOperation. Keep it internal and treat it as shared source code.

…as internal, parameterize message strings

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>

Copilot AI commented Nov 7, 2025

Copy link
Copy Markdown
Contributor Author

Copilot Don't make RequiredCommandValidator and CoalescingAsyncOperation. Keep it internal and treat it as shared source code.

Done. Moved both classes to src/Shared/ as internal shared source code. They're now compiled into each project (Aspire.Hosting, DevTunnels, Python) via <Compile Include="$(SharedDir)..."> references. Message strings are parameterized with protected virtual methods that default to string literals. Commit: 456b148

@github-actions

github-actions Bot commented Nov 7, 2025 •

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 12787

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 12787"

1 similar comment
@github-actions

github-actions Bot commented Nov 7, 2025

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 12787

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 12787"

@davidfowl

Copy link
Copy Markdown
Collaborator

Copilot /Users/runner/work/aspire/aspire/tests/Aspire.Hosting.DevTunnels.Tests/DevTunnelCliInstallationManagerTests.cs(32,58): error CS0122: 'DevTunnelCliInstallationManager.OnResolvedAsync(string, CancellationToken)' is inaccessible due to its protection level [/Users/runner/work/aspire/aspire/tests/Aspire.Hosting.DevTunnels.Tests/Aspire.Hosting.DevTunnels.Tests.csproj]
/Users/runner/work/aspire/aspire/tests/Aspire.Hosting.DevTunnels.Tests/DevTunnelCliInstallationManagerTests.cs(32,14): error CS8130: Cannot infer the type of implicitly-typed deconstruction variable 'isValid'. [/Users/runner/work/aspire/aspire/tests/Aspire.Hosting.DevTunnels.Tests/Aspire.Hosting.DevTunnels.Tests.csproj]
/Users/runner/work/aspire/aspire/tests/Aspire.Hosting.DevTunnels.Tests/DevTunnelCliInstallationManagerTests.cs(32,23): error CS8130: Cannot infer the type of implicitly-typed deconstruction variable 'validationMessage'. [/Users/runner/work/aspire/aspire/tests/Aspire.Hosting.DevTunnels.Tests/Aspire.Hosting.DevTunnels.Tests.csproj]
0 Warning(s)
3 Error(s)

Time Elapsed 00:01:11.55
Build failed with exit code 1. Ch

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>

Copilot AI commented Nov 7, 2025

Copy link
Copy Markdown
Contributor Author

Copilot /Users/runner/work/aspire/aspire/tests/Aspire.Hosting.DevTunnels.Tests/DevTunnelCliInstallationManagerTests.cs(32,58): error CS0122: 'DevTunnelCliInstallationManager.OnResolvedAsync(string, C...

Fixed. Made OnResolvedAsync protected internal virtual in the base class to allow test access. DevTunnels tests now pass (28/28 ✅). Commit: 68c1262

@dotnet-policy-service dotnet-policy-service Bot added this to the 13.1 milestone Nov 7, 2025
@davidfowl
David Fowler (davidfowl) marked this pull request as ready for review November 7, 2025 04:35
Copilot AI review requested due to automatic review settings November 7, 2025 04:35
@davidfowl

Copy link
Copy Markdown
Collaborator
image

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR refactors the RequiredCommandValidator and CoalescingAsyncOperation classes from the Aspire.Hosting.DevTunnels namespace to the more general Aspire.Hosting.Utils namespace, making them reusable across the codebase. The refactoring introduces virtual methods for customizing error messages and adds Python environment validation support.

Key Changes

  • Moved RequiredCommandValidator and CoalescingAsyncOperation from Aspire.Hosting.DevTunnels to Aspire.Hosting.Utils namespace for broader reuse
  • Replaced hardcoded resource string references with virtual methods (GetCommandNotFoundMessage, GetCommandNotFoundWithLinkMessage, GetValidationFailedMessage) to enable customization
  • Added PythonInstallationManager and UvInstallationManager classes to validate Python and uv command availability before running Python applications

Reviewed Changes

Copilot reviewed 39 out of 41 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
src/Shared/RequiredCommandValidator.cs Moved to Utils namespace, added virtual methods for error messages, changed ResolveCommand to protected internal
src/Shared/CoalescingAsyncOperation.cs Moved to Utils namespace, added XML documentation for Dispose method
src/Aspire.Hosting.Python/PythonInstallationManager.cs New class to validate Python installation with platform-specific command resolution
src/Aspire.Hosting.Python/UvInstallationManager.cs New class to validate uv command availability
src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs Integrated Python/uv validation before resource startup
src/Aspire.Hosting/Resources/MessageStrings.* Added unused resource strings (should be removed)
src/Aspire.Hosting.Python/Resources/MessageStrings.* Added unused resource strings (should be removed)
src/Aspire.Hosting.DevTunnels/*.cs Updated using directives to reference new Utils namespace
src/Aspire.Hosting/Aspire.Hosting.csproj Added shared file links for new Utils classes
src/Aspire.Hosting.Python/Aspire.Hosting.Python.csproj Added shared file links and resource file configuration
src/Aspire.Hosting.DevTunnels/Aspire.Hosting.DevTunnels.csproj Added shared file links for new Utils classes
Files not reviewed (2)
  • src/Aspire.Hosting.Python/Resources/MessageStrings.Designer.cs: Language not supported
  • src/Aspire.Hosting/Resources/MessageStrings.Designer.cs: Language not supported
Comments suppressed due to low confidence (4)

src/Shared/CoalescingAsyncOperation.cs:11

  • The XML documentation for this internal class is too verbose. According to the coding guidelines, internal APIs should have brief <summary> tags only. The detailed explanation in lines 6-11 should be simplified to a concise description.
    src/Shared/RequiredCommandValidator.cs:21
  • The XML documentation for this internal class is too verbose. According to the coding guidelines, internal APIs should have brief <summary> tags only and avoid verbose <remarks> sections. The <remarks> section should be removed, and the <summary> should be simplified to a concise description of what the class does.
    src/Shared/RequiredCommandValidator.cs:62
  • The XML documentation for these internal methods is too verbose. According to the coding guidelines, internal APIs should have brief <summary> tags only. The detailed explanations in lines 38-40, 46-49, and 55-58 are excessive for internal methods. Consider simplifying to concise one-line summaries.
    src/Shared/RequiredCommandValidator.cs:71
  • The XML documentation for this internal method includes a <remarks> section. According to the coding guidelines, internal APIs should have brief <summary> tags only and avoid <remarks>. The <remarks> section should be removed.

Comment on lines +135 to +143
<data name="RequiredCommandNotification" xml:space="preserve">
<value>Required command '{0}' was not found on PATH or at a specified location.</value>
</data>
<data name="RequiredCommandNotificationWithLink" xml:space="preserve">
<value>Required command '{0}' was not found. See installation instructions for more details.</value>
</data>
<data name="RequiredCommandNotificationWithValidation" xml:space="preserve">
<value>{0} See installation instructions for more details.</value>
</data>

Copilot AI Nov 7, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These resource strings appear to be unused. The RequiredCommandValidator class was refactored to use virtual methods (GetCommandNotFoundMessage, GetCommandNotFoundWithLinkMessage, GetValidationFailedMessage) instead of these resource strings. Since no code references these resource strings, they should be removed from the resx files to avoid maintaining dead code.

Suggested change
<data name="RequiredCommandNotification" xml:space="preserve">
<value>Required command '{0}' was not found on PATH or at a specified location.</value>
</data>
<data name="RequiredCommandNotificationWithLink" xml:space="preserve">
<value>Required command '{0}' was not found. See installation instructions for more details.</value>
</data>
<data name="RequiredCommandNotificationWithValidation" xml:space="preserve">
<value>{0} See installation instructions for more details.</value>
</data>

Copilot uses AI. Check for mistakes.
Comment on lines +30 to +44
<trans-unit id="RequiredCommandNotification">
<source>Required command '{0}' was not found on PATH or at a specified location.</source>
<target state="new">Required command '{0}' was not found on PATH or at a specified location.</target>
<note />
</trans-unit>
<trans-unit id="RequiredCommandNotificationWithLink">
<source>Required command '{0}' was not found. See installation instructions for more details.</source>
<target state="new">Required command '{0}' was not found. See installation instructions for more details.</target>
<note />
</trans-unit>
<trans-unit id="RequiredCommandNotificationWithValidation">
<source>{0} See installation instructions for more details.</source>
<target state="new">{0} See installation instructions for more details.</target>
<note />
</trans-unit>

Copilot AI Nov 7, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These resource strings appear to be unused. The RequiredCommandValidator class was refactored to use virtual methods instead of resource strings. Since no code references these resource strings, they should be removed from all localization files to avoid maintaining dead code.

Suggested change
<trans-unit id="RequiredCommandNotification">
<source>Required command '{0}' was not found on PATH or at a specified location.</source>
<target state="new">Required command '{0}' was not found on PATH or at a specified location.</target>
<note />
</trans-unit>
<trans-unit id="RequiredCommandNotificationWithLink">
<source>Required command '{0}' was not found. See installation instructions for more details.</source>
<target state="new">Required command '{0}' was not found. See installation instructions for more details.</target>
<note />
</trans-unit>
<trans-unit id="RequiredCommandNotificationWithValidation">
<source>{0} See installation instructions for more details.</source>
<target state="new">{0} See installation instructions for more details.</target>
<note />
</trans-unit>

Copilot uses AI. Check for mistakes.
Comment on lines +108 to +133
/// <summary>
/// Looks up a localized string similar to Required command '{0}' was not found on PATH or at a specified location..
/// </summary>
internal static string RequiredCommandNotification {
get {
return ResourceManager.GetString("RequiredCommandNotification", resourceCulture);
}
}

/// <summary>
/// Looks up a localized string similar to Required command '{0}' was not found. See installation instructions for more details..
/// </summary>
internal static string RequiredCommandNotificationWithLink {
get {
return ResourceManager.GetString("RequiredCommandNotificationWithLink", resourceCulture);
}
}

/// <summary>
/// Looks up a localized string similar to {0} See installation instructions for more details..
/// </summary>
internal static string RequiredCommandNotificationWithValidation {
get {
return ResourceManager.GetString("RequiredCommandNotificationWithValidation", resourceCulture);
}
}

Copilot AI Nov 7, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These generated properties for resource strings appear to be unused. The RequiredCommandValidator class was refactored to use virtual methods instead of these resource strings. These properties should be removed by removing the corresponding entries from MessageStrings.resx.

Suggested change
/// <summary>
/// Looks up a localized string similar to Required command '{0}' was not found on PATH or at a specified location..
/// </summary>
internal static string RequiredCommandNotification {
get {
return ResourceManager.GetString("RequiredCommandNotification", resourceCulture);
}
}
/// <summary>
/// Looks up a localized string similar to Required command '{0}' was not found. See installation instructions for more details..
/// </summary>
internal static string RequiredCommandNotificationWithLink {
get {
return ResourceManager.GetString("RequiredCommandNotificationWithLink", resourceCulture);
}
}
/// <summary>
/// Looks up a localized string similar to {0} See installation instructions for more details..
/// </summary>
internal static string RequiredCommandNotificationWithValidation {
get {
return ResourceManager.GetString("RequiredCommandNotificationWithValidation", resourceCulture);
}
}

Copilot uses AI. Check for mistakes.
Comment on lines +61 to +63
<data name="UvNotFoundWhenRequired" xml:space="preserve">
<value>The 'uv' command was not found, but is required for this Python application. Install uv by following the instructions at https://docs.astral.sh/uv/getting-started/installation/</value>
</data>

Copilot AI Nov 7, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This resource string appears to be unused. The UvInstallationManager relies on the base RequiredCommandValidator class's virtual methods for error messages. Since no code references this resource string, it should be removed from the resx file to avoid maintaining dead code.

Suggested change
<data name="UvNotFoundWhenRequired" xml:space="preserve">
<value>The 'uv' command was not found, but is required for this Python application. Install uv by following the instructions at https://docs.astral.sh/uv/getting-started/installation/</value>
</data>

Copilot uses AI. Check for mistakes.
Comment on lines +5 to +9
<trans-unit id="UvNotFoundWhenRequired">
<source>The 'uv' command was not found, but is required for this Python application. Install uv by following the instructions at https://docs.astral.sh/uv/getting-started/installation/</source>
<target state="new">The 'uv' command was not found, but is required for this Python application. Install uv by following the instructions at https://docs.astral.sh/uv/getting-started/installation/</target>
<note />
</trans-unit>

Copilot AI Nov 7, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This resource string appears to be unused. The UvInstallationManager relies on the base RequiredCommandValidator class's virtual methods for error messages. Since no code references this resource string, it should be removed from all localization files to avoid maintaining dead code.

Suggested change
<trans-unit id="UvNotFoundWhenRequired">
<source>The 'uv' command was not found, but is required for this Python application. Install uv by following the instructions at https://docs.astral.sh/uv/getting-started/installation/</source>
<target state="new">The 'uv' command was not found, but is required for this Python application. Install uv by following the instructions at https://docs.astral.sh/uv/getting-started/installation/</target>
<note />
</trans-unit>

Copilot uses AI. Check for mistakes.
@davidfowl

Copy link
Copy Markdown
Collaborator

Copilot Delete the unused resource strings.

…ource validation

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>

Copilot AI commented Nov 8, 2025

Copy link
Copy Markdown
Contributor Author

Copilot Add an overload of EnsureInstalledAsync that takes a bool that says don't throw if the command isn't valid. Default this parameter to true, but set it to false for PythonInstallationManager a...

Done. Added EnsureInstalledAsync(bool throwOnFailure = true) overload:

  • Defaults to true (throw on failure) for backward compatibility
  • Set to false for both PythonInstallationManager and UvInstallationManager so the app fails naturally while still showing helpful notifications
  • Removed RunMode checks since both PythonVenvCreatorResource and PythonInstallerResource have ExcludeFromManifest (only run in run mode)

Commit: 7b2115d

@davidfowl

Copy link
Copy Markdown
Collaborator

Copilot Add UvInstallationManager in the UseUv method

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>

Copilot AI commented Nov 8, 2025

Copy link
Copy Markdown
Contributor Author

Copilot Add UvInstallationManager in the UseUv method

Added explicit UvInstallationManager service registration in the WithUv method. This ensures the validation service is registered when developers use .WithUv(), making the dependency more explicit. Commit: 9e1b4fd

@mitchdenny

Copy link
Copy Markdown
Member

I tested this out on Ubuntu 24.04 - works well.

@davidfowl

Copy link
Copy Markdown
Collaborator

Copilot Undo the changes under Aspire.Hosting/Resources. These are not being used anywhere

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>

Copilot AI commented Nov 8, 2025

Copy link
Copy Markdown
Contributor Author

Copilot Undo the changes under Aspire.Hosting/Resources. These are not being used anywhere

Removed all unused resource strings from src/Aspire.Hosting/Resources/. The three resource strings (RequiredCommandNotification, RequiredCommandNotificationWithLink, RequiredCommandNotificationWithValidation) and their translations have been reverted. Commit: 9ac9fd2

@davidfowl
David Fowler (davidfowl) enabled auto-merge (squash) November 8, 2025 15:32
@davidfowl
David Fowler (davidfowl) merged commit 8e2e80c into main Nov 8, 2025
@davidfowl
David Fowler (davidfowl) deleted the copilot/open-new-pr-contents branch November 8, 2025 15:41
@davidfowl

Copy link
Copy Markdown
Collaborator

/backport to release/13.0

@github-actions

github-actions Bot commented Nov 8, 2025

Copy link
Copy Markdown
Contributor

Started backporting to release/13.0: https://github.com/dotnet/aspire/actions/runs/19195175938

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants