docs: Add App Model API documentation for CORS, console apps, resource naming, and networking#454
docs: Add App Model API documentation for CORS, console apps, resource naming, and networking#454
Conversation
…etworking Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
IEvangelist
left a comment
IEvangelist
left a comment
There was a problem hiding this comment.
This PR looks good so far, but let's double check it for accuracy by using the .github/skills/doc-tester/SKILL.md skill. Please also consider all new comments and feedback. @copilot
…x code block titles, reorganize networking examples Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
Ran the doc-tester validation on all new and updated pages. Here's what was verified: All internal links return HTTP 200 — Content accuracy checks:
One structural fix made (commit e1a909e): An Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
IEvangelist
left a comment
IEvangelist
left a comment
There was a problem hiding this comment.
This PR looks good so far, but let's double check it for accuracy by using the .github/skills/doc-tester/SKILL.md skill. Please also consider all new comments and feedback/suggestions. @copilot
…ages, add LearnMore links Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
|
Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details. Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
There was a problem hiding this comment.
Pull request overview
Adds new AppHost documentation pages to close gaps around CORS, console/worker apps, and resource naming, and extends the networking fundamentals page with LAN binding and container-to-host guidance.
Changes:
- Added new AppHost docs: CORS configuration, console/worker apps, and resource naming conventions.
- Expanded
networking-overview.mdxwith LAN binding and container-to-host networking sections. - Updated the docs sidebar and refreshed the integrations catalog metadata.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| src/frontend/src/data/aspire-integrations.json | Updates integration package versions/icons/download counts; adds new CommunityToolkit entries. |
| src/frontend/src/content/docs/fundamentals/networking-overview.mdx | Adds LAN binding guidance and container-to-host networking + KnownNetworkIdentifiers examples. |
| src/frontend/src/content/docs/app-host/resource-naming.mdx | New page describing env var mapping, dash→underscore behavior, and naming guidance. |
| src/frontend/src/content/docs/app-host/cors-configuration.mdx | New page explaining when/how to configure CORS (dev/prod patterns + common issues). |
| src/frontend/src/content/docs/app-host/console-apps.mdx | New page documenting console/worker app orchestration, service discovery, and dashboard logs. |
| src/frontend/config/sidebar/docs.topics.ts | Adds new AppHost pages to the sidebar. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
src/frontend/src/content/docs/fundamentals/networking-overview.mdx
Outdated
Show resolved
Hide resolved
| // The container can reach the host-side service via the correct gateway address | ||
| var containerApp = builder.AddContainer("mycontainer", "myimage") | ||
| .WithEnvironment("HOST_URL", $"http://host.docker.internal:5000"); |
There was a problem hiding this comment.
This section says WithReference “automatically handles” container→host addressing, but the example hardcodes host.docker.internal via WithEnvironment and doesn’t use WithReference at all (and it isn’t cross-platform per the table just above). Please update the example to demonstrate the described behavior (e.g., service discovery/WithReference, or GetEndpoint(..., KnownNetworkIdentifiers.DefaultAspireContainerNetwork)) and avoid hardcoding a Docker Desktop–specific hostname.
| // The container can reach the host-side service via the correct gateway address | |
| var containerApp = builder.AddContainer("mycontainer", "myimage") | |
| .WithEnvironment("HOST_URL", $"http://host.docker.internal:5000"); | |
| // Host-side project (runs on the developer machine, not in a container) | |
| var api = builder.AddProject<Projects.Api>("api"); | |
| // The container can reach the host-side service via WithReference, | |
| // which automatically uses the correct host gateway address for the runtime | |
| var containerApp = builder.AddContainer("mycontainer", "myimage") | |
| .WithReference(api); |
There was a problem hiding this comment.
Fixed in commit 4d1b8d0. The example now uses WithReference(api) to demonstrate that Aspire automatically resolves the correct host gateway address, rather than hardcoding host.docker.internal.
| { | ||
| label: 'Console and worker apps', | ||
| slug: 'app-host/console-apps', | ||
| translations: { | ||
| en: 'Console and worker apps', | ||
| }, | ||
| }, |
There was a problem hiding this comment.
These new sidebar items include only an en translation, but other items in the same AppHost section provide both en and ja. Please add ja translations for these new entries (or follow the established pattern for this section) to keep locale coverage consistent.
| ## Resource name validation | ||
|
|
||
| Aspire validates resource names at startup. Valid resource names: | ||
|
|
||
| - Must be non-empty | ||
| - Must start with a lowercase letter | ||
| - May only contain lowercase letters, digits, and dashes (`-`) | ||
| - Must not contain consecutive dashes (`--`) |
There was a problem hiding this comment.
The “Resource name validation” rules here appear inconsistent with other docs in this repo that use underscores in resource names (for example postgres.AddDatabase("app_db") in integrations/databases/postgres/postgres-host.mdx). Please verify the actual ASPIRE006 naming constraints and align this list (and the earlier note about “dots or underscores are preserved”) so the site isn’t internally contradictory.
There was a problem hiding this comment.
Fixed in commit 4d1b8d0. Validation rules now include underscores as valid (consistent with app_db usage in the PostgreSQL docs). Also removed the contradictory "avoid underscores" best practice and updated it to note underscores are valid but dashes are preferred for consistency.
IEvangelist
left a comment
IEvangelist
left a comment
There was a problem hiding this comment.
This PR looks good so far, but let's double check it for accuracy by using the .github/skills/doc-tester/SKILL.md skill. Please also consider all new comments and feedback/suggestions. @copilot
|
|
||
| ## Adding a console app to the AppHost | ||
|
|
||
| Any .NET project — including console applications and Worker Service projects — can be added to the AppHost using `AddProject`. The project doesn't need to be a web app. |
There was a problem hiding this comment.
One thing to note, is that we support other console apps too - other than just .NET. We should really add a bit here about AddExecutable (and even provide links to AddPythonApp, and maybe AddNode*, perhaps they could just be links...but the idea is that we shouldn't isolate ourselves into just .NET. Obviously, the ServiceDefaults are only applicable to the .NET projects.
There was a problem hiding this comment.
Added a note and LearnMore links for AddExecutable, AddPythonApp, and AddNodeApp at the top of the "Adding a console app to the AppHost" section in commit 4d1b8d0.
…apps, naming fixes, networking accuracy Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
|
Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details. Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
Addresses gaps identified from 20K+ Discord community messages where users had no documentation for several common AppHost scenarios.
New pages
app-host/resource-naming.mdx— How resource names map to env vars (ConnectionStrings__<name>,services__<name>__<endpoint>__0), the dash→underscore transformation (my-service→ConnectionStrings__my_service), naming best practices (dashes preferred, underscores valid), and resource name validation rules (links to ASPIRE006 diagnostic).app-host/console-apps.mdx— Adding .NET console/worker projects to AppHost viaAddProject, plus links toAddExecutable,AddPythonApp, andAddNodeAppfor non-.NET apps. Covers wiring service discovery on non-ASP.NET Core hosts,BackgroundServicepatterns,WithExplicitStart()for interactive apps, and dashboard console output.app-host/cors-configuration.mdx— When CORS is (and isn't) needed with Aspire, ASP.NET Core Minimal API middleware setup withAddCors/UseCors, environment-based origins, usingWithReference(frontend)to auto-inject the frontend URL into API CORS config, common failure patterns (middleware ordering, preflight, credentials), and dashboard CORS env var.Updated pages
fundamentals/networking-overview.mdx— Two new sections:WithHttpEndpointmaps ports only; the app must also bind viaWithEnvironment), and executablesWithReferencefor automatic cross-platform host resolution,AddConnectionStringfor existing host services, andKnownNetworkIdentifiersSidebar
Added all three new pages under the AppHost section in
docs.topics.tswith Japanese (ja) translations.Original prompt
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.