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.
| For container resources, configure the binding when adding the endpoint. The `WithHttpEndpoint` host port is bound by the DCP proxy on the host, but you can control the container's internal binding address: | ||
|
|
||
| ```csharp title="C# — AppHost.cs" | ||
| var builder = DistributedApplication.CreateBuilder(args); | ||
|
|
||
| // Bind the container to listen on all interfaces inside the container | ||
| builder.AddContainer("myapp", "myregistry/myapp") |
There was a problem hiding this comment.
WithHttpEndpoint(port: ..., targetPort: ...) configures host↔container port mapping, but it doesn’t make the containerized app listen on 0.0.0.0 inside the container. The current text implies Aspire can control the container’s internal bind address here. Please adjust the wording and/or show setting the app’s listen address via container args/env (the app itself must bind to 0.0.0.0).
| For container resources, configure the binding when adding the endpoint. The `WithHttpEndpoint` host port is bound by the DCP proxy on the host, but you can control the container's internal binding address: | |
| ```csharp title="C# — AppHost.cs" | |
| var builder = DistributedApplication.CreateBuilder(args); | |
| // Bind the container to listen on all interfaces inside the container | |
| builder.AddContainer("myapp", "myregistry/myapp") | |
| For container resources, `WithHttpEndpoint` configures host↔container port mapping via the DCP proxy on the host. The application inside the container must still be configured to listen on `0.0.0.0` (for example, via environment variables or arguments): | |
| ```csharp title="C# — AppHost.cs" | |
| var builder = DistributedApplication.CreateBuilder(args); | |
| // Map host port 8080 to container port 80 and configure the app to listen on all interfaces | |
| builder.AddContainer("myapp", "myregistry/myapp") | |
| .WithEnvironment("ASPNETCORE_URLS", "http://0.0.0.0:80") |
There was a problem hiding this comment.
Fixed in commit 4d1b8d0. The text now clarifies that WithHttpEndpoint only maps host↔container ports, and the example shows using WithEnvironment("ASPNETCORE_URLS", "http://0.0.0.0:80") to configure the app inside the container to actually bind on all interfaces.
| // 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.
| The `processor` project receives the `ConnectionStrings__cache` environment variable at runtime, just like any other project type. | ||
|
|
||
| <Aside type="note"> | ||
| The console app project must target `net9.0` or later and reference the service defaults project to benefit from telemetry and service discovery. For more information, see [Service defaults](/fundamentals/service-defaults/). |
There was a problem hiding this comment.
This note says console apps must target net9.0 or later, but the service defaults docs describe the ServiceDefaults project as a net10.0 library and the examples here use Microsoft.Extensions.* 10.0.0 packages. Please align the minimum target framework guidance with the current Aspire/.NET version used in this repo (likely net10.0).
| The console app project must target `net9.0` or later and reference the service defaults project to benefit from telemetry and service discovery. For more information, see [Service defaults](/fundamentals/service-defaults/). | |
| The console app project must target `net10.0` or later and reference the service defaults project to benefit from telemetry and service discovery. For more information, see [Service defaults](/fundamentals/service-defaults/). |
There was a problem hiding this comment.
Fixed in commit 4d1b8d0: net9.0 updated to net10.0.
| { | ||
| 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.
|
|
||
| ## Configuring CORS in development | ||
|
|
||
| During development, the recommended approach is to allow your frontend's development server origin. Use `WithCors` in your API's `Program.cs`: |
There was a problem hiding this comment.
The text says to use WithCors in Program.cs, but the example uses the standard ASP.NET Core AddCors/UseCors APIs and there is no WithCors method in this context. Please update the wording to avoid pointing readers at a non-existent API (for example, say “configure CORS with AddCors/UseCors”).
| During development, the recommended approach is to allow your frontend's development server origin. Use `WithCors` in your API's `Program.cs`: | |
| During development, the recommended approach is to allow your frontend's development server origin. Configure CORS with `AddCors` and `UseCors` in your API's `Program.cs`: |
There was a problem hiding this comment.
Fixed in commit 4d1b8d0: "Use WithCors" replaced with "Configure CORS with AddCors and UseCors".
| In your .NET application, the configuration system maps double underscores (`__`) to the colon (`:`) separator used by `IConfiguration`. This means `ConnectionStrings__app_db` is accessible as `ConnectionStrings:app-db` in the configuration API: | ||
|
|
||
| ```csharp title="C# — Program.cs" | ||
| // This resolves ConnectionStrings__app_db (injected by Aspire) | ||
| var connectionString = builder.Configuration.GetConnectionString("app-db"); |
There was a problem hiding this comment.
This section claims ConnectionStrings__app_db is accessible as ConnectionStrings:app-db and that GetConnectionString("app-db") will resolve it. __ maps to : in configuration keys, but _ is not converted back to -, so the resulting key would be ConnectionStrings:app_db. Please correct the explanation and the retrieval example to match the actual key that will be present.
| In your .NET application, the configuration system maps double underscores (`__`) to the colon (`:`) separator used by `IConfiguration`. This means `ConnectionStrings__app_db` is accessible as `ConnectionStrings:app-db` in the configuration API: | |
| ```csharp title="C# — Program.cs" | |
| // This resolves ConnectionStrings__app_db (injected by Aspire) | |
| var connectionString = builder.Configuration.GetConnectionString("app-db"); | |
| In your .NET application, the configuration system maps double underscores (`__`) to the colon (`:`) separator used by `IConfiguration`. This means `ConnectionStrings__app_db` is accessible as `ConnectionStrings:app_db` in the configuration API: | |
| ```csharp title="C# — Program.cs" | |
| // This resolves ConnectionStrings__app_db (injected by Aspire) | |
| var connectionString = builder.Configuration.GetConnectionString("app_db"); |
There was a problem hiding this comment.
Fixed in commit 4d1b8d0. The example now correctly uses GetConnectionString("app_db") (underscore, not dash) since __ maps to : but single _ is preserved as-is.
| ## 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
| label: 'Console and worker apps', | ||
| slug: 'app-host/console-apps', | ||
| translations: { | ||
| en: 'Console and worker apps', | ||
| }, | ||
| }, | ||
| { | ||
| label: 'Resource naming', | ||
| slug: 'app-host/resource-naming', | ||
| translations: { | ||
| en: 'Resource naming', | ||
| }, | ||
| }, | ||
| { | ||
| label: 'CORS configuration', | ||
| slug: 'app-host/cors-configuration', | ||
| translations: { | ||
| en: 'CORS configuration', | ||
| }, |
There was a problem hiding this comment.
Please add the missing translations for the other supported locales.
There was a problem hiding this comment.
Added Japanese translations for all three new entries in commit 4d1b8d0: コンソール アプリとワーカー アプリ, リソースの名前付け, and CORS の構成.
|
|
||
| ## 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.