docs: document the 'Use *.dev.localhost URLs?' interactive prompt for aspire new#697
docs: document the 'Use *.dev.localhost URLs?' interactive prompt for aspire new#697
aspire new#697Conversation
… aspire new Agent-Logs-Url: https://github.com/microsoft/aspire.dev/sessions/49848864-c0a9-482c-a045-a860f76cb80f Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
aspire new
There was a problem hiding this comment.
Pull request overview
Adds missing reference documentation for the aspire new interactive prompt “Use *.dev.localhost URLs?” so users understand the tradeoffs between wildcard subdomain HTTPS URLs and standard localhost URLs during template creation.
Changes:
- Adds an Interactive prompts section to the
aspire newcommand reference. - Documents what choosing Yes vs No does for generated service URLs.
- Adds a Safari-related note for
*.localhost-style subdomains.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…host wording Agent-Logs-Url: https://github.com/microsoft/aspire.dev/sessions/b4be3134-13a1-4f17-b67e-dd41e7a87ace Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
|
|
||
| This prompt determines whether the generated launch profile configures your Aspire services to be accessible via `*.dev.localhost` wildcard subdomain URLs (for example, `https://myservice.dev.localhost`) instead of standard `http://localhost` with port numbers. | ||
|
|
||
| #### What are \*.dev.localhost URLs? |
There was a problem hiding this comment.
This is missing lots of nuance about what these are and aren't. The biggest being that it only works in browsers.
| - Gives each service its own origin, which prevents cookie and authentication token collisions between services running on the same machine. | ||
| - More closely mirrors a production setup where services are hosted on separate (sub)domains. | ||
|
|
||
| **Prerequisite:** The ASP.NET Core HTTPS development certificate must be installed and trusted on your machine. Run the following command if you haven't done so already: |
There was a problem hiding this comment.
This is true, but I would just say developer cert and move all of the details about the cert to the cert article.
JamesNK
left a comment
JamesNK
left a comment
There was a problem hiding this comment.
Content is accurate, well-structured, and fills a real gap in the CLI reference. Just a few minor readability nits — nothing blocking. Nice work! 👍
| This prompt determines whether the generated launch profile configures your Aspire services to be accessible via `*.dev.localhost` wildcard subdomain URLs (for example, `https://myservice.dev.localhost`) instead of standard `http://localhost` with port numbers. | ||
|
|
There was a problem hiding this comment.
Nit: The Safari caveat is mentioned here and again in the <Aside> on line 73. Consider dropping the inline mention from this paragraph and relying solely on the callout — it's more prominent and avoids saying the same thing twice.
| This prompt determines whether the generated launch profile configures your Aspire services to be accessible via `*.dev.localhost` wildcard subdomain URLs (for example, `https://myservice.dev.localhost`) instead of standard `http://localhost` with port numbers. | |
| `*.dev.localhost` is a wildcard subdomain pattern that resolves to your local machine (`127.0.0.1` or `::1`) in most modern browsers without additional DNS configuration. The ASP.NET Core HTTPS development certificate includes `*.dev.localhost` as a Subject Alternative Name (SAN), so browsers trust connections to any subdomain under `*.dev.localhost` when the certificate is installed and trusted. |
| > **Use \*.dev.localhost URLs?** | ||
|
|
||
| This prompt determines whether the generated launch profile configures your Aspire services to be accessible via `*.dev.localhost` wildcard subdomain URLs (for example, `https://myservice.dev.localhost`) instead of standard `http://localhost` with port numbers. | ||
|
|
There was a problem hiding this comment.
Nit: This paragraph packs DNS resolution behavior, browser support exceptions, and HTTPS certificate details into one block. Consider splitting it into two paragraphs — one for DNS/browser resolution and one for the certificate trust story — to make it easier to scan.
| `127.0.0.1` by default. If you use Safari, choose **No** or add an entry to | ||
| your hosts file. | ||
| </Aside> | ||
|
|
||
| #### No — use standard localhost URLs (default) |
There was a problem hiding this comment.
Nit: "add an entry to your hosts file" leaves the reader guessing what the entry should be. A brief inline example would make this immediately actionable:
| `127.0.0.1` by default. If you use Safari, choose **No** or add an entry to | |
| your hosts file. | |
| </Aside> | |
| #### No — use standard localhost URLs (default) | |
| <Aside type="note"> | |
| Safari on macOS does not resolve `*.dev.localhost` subdomains to | |
| `127.0.0.1` by default. If you use Safari, choose **No** or add entries to | |
| your hosts file (for example, `127.0.0.1 myservice.dev.localhost`). | |
| </Aside> |
The
aspire newcommand reference page had no documentation for the "Use *.dev.localhost URLs?" interactive prompt, leaving users without enough context to make an informed choice.Changes
aspire-new.mdxwith a dedicated sub-section for the*.dev.localhostprompt*.dev.localhostsubdomains (HTTPS) vs. standardlocalhost:<port>(HTTP)aspire certs trustprerequisite with a<LearnMore>link to theaspire certs trustcommand referencehttp://localhost:<port>, no certificate setup required, works everywhere*.dev.localhostsubdomains don't resolve natively in Safari; added an<Aside>note pointing users to choose No or add a hosts-file entry