Advise aspire certs trust in polyglot HTTPS dev-cert errors#17348
Merged
sebastienros merged 3 commits intoMay 21, 2026
Conversation
Kestrel's HTTPS dev-cert guidance points users at 'dotnet dev-certs https' and a go.microsoft.com fwlink. For TypeScript/Node.js (and other polyglot) app hosts that flow through PolyglotCapabilityErrorFormatter, this is poor advice because the .NET SDK may not be on PATH. Rewrite the guidance to point at 'aspire certs trust' (which both creates and trusts the cert in one step) and at https://aspire.dev/docs/ so polyglot users get advice that works in their environment. Native .NET app hosts do not flow through this formatter and are unaffected. Fixes #17273 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Per review feedback: ASP.NET Core's Kestrel throws a plain InvalidOperationException from TlsConfigurationLoader.UseHttpsWithDefaults with no HResult and no specific exception type, so there is no error code to key off. Confirmed by inspecting upstream sources: - CoreStrings.resx -> NoCertSpecifiedNoDevelopmentCertificateFound - TlsConfigurationLoader.cs -> throw new InvalidOperationException(...) The fwlink identifier 848054 has been the unique sentinel for this exact error since .NET Core 2.1, and it does not appear in any other Kestrel error. Switch to a single source-generated regex anchored on the fwlink that tolerates whitespace/line-ending variation. If a future framework release reworks the message such that the fwlink is gone, the rewrite degrades gracefully: the regex misses, the original text propagates, and no incorrect substitution occurs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Per review feedback: simplify the rewrite by using the fwlink ID 848054 purely as a detection sentinel and replacing the whole Kestrel message with a polyglot-friendly equivalent. This removes the dependency on the exact wording of every sentence in the Kestrel string -- only the fwlink needs to match for detection to fire, and the replacement is fully controlled by us instead of stitched together from the original message. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17348Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17348" |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the polyglot capability error formatting so that when ASP.NET Core Kestrel reports a missing/untrusted HTTPS development certificate (the message containing fwlink 848054), polyglot app hosts (TypeScript/Node.js, Python, etc.) receive Aspire CLI guidance instead of dotnet dev-certs guidance.
Changes:
- Add a rewrite step in
PolyglotCapabilityErrorFormatter.ScrubMessagethat detects the Kestrel HTTPS dev-cert error via the fwlink sentinel and replaces the entire message with an Aspire-specific, polyglot-friendly message (aspire certs trust+https://aspire.dev/docs/). - Add a regression test ensuring Kestrel’s original
dotnet dev-certsand fwlink guidance is removed and the Aspire guidance is present.
Show a summary per file
| File | Description |
|---|---|
| src/Aspire.Hosting.RemoteHost/Ats/PolyglotCapabilityInvocationException.cs | Rewrites the Kestrel dev-cert guidance for polyglot callers by detecting the fwlink sentinel and substituting Aspire CLI guidance. |
| tests/Aspire.Hosting.RemoteHost.Tests/CapabilityDispatcherTests.cs | Adds a regression test to validate the message rewrite behavior through CreateInternalError/ToCapabilityException(). |
Copilot's findings
- Files reviewed: 2/2 changed files
- Comments generated: 0
Contributor
|
❓ CLI E2E Tests unknown — 95 passed, 0 failed, 5 unknown (commit View all recordings
📹 Recordings uploaded automatically from CI run #26208483721 |
sebastienros
approved these changes
May 21, 2026
sebastienros
deleted the
mitchdenny/ts-apphost-aspire-certs-trust-guidance
branch
aspire-repo-bot Bot
added a commit
to microsoft/aspire.dev
that referenced
this pull request
May 21, 2026
TypeScript (and other polyglot) app host users may not have the .NET SDK on their PATH, so `dotnet dev-certs https --trust` guidance doesn't apply. Aspire now surfaces `aspire certs trust` in HTTPS error messages for polyglot hosts (microsoft/aspire#17348). Add an 'HTTPS development certificates' section to the TypeScript AppHost project structure page explaining how to resolve the error with `aspire certs trust`, with a tip for clean+trust recovery and a cross- reference to the full certificate-configuration docs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
Pull request created: #1032
|
Contributor
|
📝 Documentation has been drafted in microsoft/aspire.dev#1032 targeting Drafted a docs PR adding an "HTTPS development certificates" section to Note This draft PR needs human review before merging. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
When a TypeScript (or other polyglot) app host fails to start because the ASP.NET Core HTTPS developer certificate is missing or untrusted, Kestrel surfaces a message that tells users to run
dotnet dev-certs httpsanddotnet dev-certs https --trust, and points them athttps://go.microsoft.com/fwlink/?linkid=848054. That advice assumes the .NET SDK is onPATH, which is not guaranteed for Node.js / Python / etc. app host users, and the fwlink is not the right destination for Aspire docs.This change rewrites the message on its way through the polyglot capability layer so polyglot users see Aspire CLI guidance instead:
Approach
PolyglotCapabilityErrorFormatter.ScrubMessageis the single chokepoint that all exception messages flow through on their way to polyglot (non-.NET) hosts. Native .NET app hosts never go through this code path, so their guidance is unchanged.ASP.NET Core's Kestrel throws a plain
InvalidOperationExceptionfromTlsConfigurationLoader.UseHttpsWithDefaultswith noHResultand no specific exception type, so the message text is the only signal available. The fwlink ID848054has been the unique sentinel for this exact error since .NET Core 2.1 and does not appear in any other Kestrel error, so it is used purely as a detection sentinel; when it appears, the entire message is replaced with a single polyglot-friendly constant owned by us. This avoids any dependency on the exact wording of the surrounding sentences. If a future framework release ever removes the fwlink, the rewrite degrades gracefully: detection misses and the original message propagates unchanged.Verified with the existing
PolyglotFormatter_*tests plus a new regression test that pipes the exact Kestrel message throughCreateInternalErrorand asserts the rewrite.Fixes: #17273
Checklist
<remarks />and<code />elements on your triple slash comments?