[docs] Document DotnetProjectResource publish limitation - #1501
[docs] Document DotnetProjectResource publish limitation#1501aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
aspire-repo-bot
Bot
added
the
docs-from-code
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
David Pine (IEvangelist)
left a comment
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
Automated docs-accuracy review — PR #1501
Phase A source of truth: microsoft/aspire @ release/13.5 — SHA 8ab6999850d96e0023670799edbd4bdc245ad63c (the branch this PR targets).
Claims extracted: 6 non-narrative — ✅ 5 verified, ❌ 1 contradicted, 0 unverifiable.
Phase B (doc-tester): 1 route exercised (/integrations/frameworks/dotnet/dotnet-host/) on a local pnpm dev server serving PR head 60d2a04 — 0 critical, 0 warnings, page renders cleanly.
⚠️ Verdict: Request changes. The core behavioral claim describes microsoft/aspire#19190, which merged tomain(milestone 13.6), not torelease/13.5— the branch this docs PR targets. Onrelease/13.5that behavior does not exist, so the rendered 13.5 page tells readers something the 13.5 product does not do. Details in the inline comment.
Phase A — Claim verification
The one blocking claim is filed as an inline comment on the affected lines. Evidence for the rest:
✅ Verified claims (5) — click to audit
| # | Claim | Verdict | Evidence (microsoft/aspire @ release/13.5, SHA 8ab6999) |
|---|---|---|---|
| 1 | DotnetProjectResource exists, added via AddDotnetProject / addDotnetProject |
✅ verified | src/Aspire.Hosting.Dotnet/DotnetProjectResource.cs:23; src/Aspire.Hosting.Dotnet/DotnetProjectHostingExtensions.cs:47 (public AddDotnetProject) and :60 ([AspireExport("addDotnetProject")]) |
| 2 | AddProject<TProject>(...) — for a project referenced by a C# AppHost |
✅ verified | src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs:67 (AddProject<TProject> where TProject : IProjectMetadata, new()) |
| 3 | AddCSharpApp(...) / addCSharpApp(...) |
✅ verified | src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs:351 (public AddCSharpApp); export [AspireExport("addCSharpApp")] at :364 |
| 4 | PublishAsDockerFile(...) / publishAsDockerFile(...) |
✅ verified | src/Aspire.Hosting/ExecutableResourceBuilderExtensions.cs:79 (PublishAsDockerFile<T> where T : ExecutableResource); export at src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs:965 (MethodName = "publishAsDockerFile") |
| 5 | ExcludeFromManifest() / excludeFromManifest() |
✅ verified | src/Aspire.Hosting/api/Aspire.Hosting.cs:1065 (public API surface, ExcludeFromManifest<T>); excludeFromManifest export in src/Aspire.Hosting/api/Aspire.Hosting.Capabilities.txt:295 |
All four suggested alternatives are real public APIs on release/13.5, and both PublishAsDockerFile and ExcludeFromManifest are applicable to a DotnetProjectResource because it derives from ExecutableResource.
Phase B — Doc-tester results (rendered site only; source not consulted)
Focus area: the new ## Publishing section on the .NET / C# AppHost integration page.
Served: local Astro pnpm dev at http://localhost:4321/, PR head 60d2a04393e670705ea910e881063f8c71519f75.
Route exercised: /integrations/frameworks/dotnet/dotnet-host/ (+ #publishing anchor).
| Category | Passed | Failed | Warnings |
|---|---|---|---|
| Content rendering | 1 | 0 | 0 |
| Page structure / TOC | 1 | 0 | 0 |
| Links | 1 | 0 | 0 |
| Console health | 1 | 0 | 0 |
Critical issues: None. The page returns 200 (title "Set up .NET / C# apps in the AppHost | Aspire") with 0 console errors/warnings. The new Publishing section renders in full — the H2 heading, a #publishing TOC entry correctly placed between "Configure options" and "See also", the body paragraph, and the four-item alternatives list, all with correct inline-code formatting.
Warnings: None blocking.
Passed checks:
- Section content matches the PR source; no truncation or MDX render failure.
- No broken links introduced; the "See also" section and surrounding content stay intact.
- No layout or structure regressions from the insertion.
Recommendations (non-blocking):
- The alternative APIs (
AddProject<TProject>,AddCSharpApp,PublishAsDockerFile,ExcludeFromManifest) are inline code with no links to their reference docs — consider linking them so a reader can act on each option. (Consistent with the rest of the page's style, so optional.) executable.v0and "machine-local paths" are unexplained jargon for a newcomer, though acceptable on an advanced publishing topic.
Knowledge gap: As a blind user I cannot confirm whether aspire publish / aspire deploy actually fails as described — that requires running the CLI or reading source, which is out of scope for this phase. Phase A evaluated that claim against source and flagged it (see the inline comment).
Automated doc-pr-reviewer run · Phase A read microsoft/aspire @ release/13.5 (8ab6999) · Phase B served PR head 60d2a04 via local pnpm dev.
| Automatic project publishing for `DotnetProjectResource` isn't currently supported. A plain | ||
| `DotnetProjectResource` causes `aspire publish` and `aspire deploy` to fail with an actionable error | ||
| instead of emitting an `executable.v0` manifest containing machine-local paths. |
There was a problem hiding this comment.
❌ Contradicted on the source-of-truth branch (microsoft/aspire @ release/13.5, SHA 8ab6999).
A plain
DotnetProjectResourcecausesaspire publishandaspire deployto fail with an actionable error instead of emitting anexecutable.v0manifest containing machine-local paths.
This "fail with an actionable error" behavior was introduced by microsoft/aspire#19190 — but that PR merged to main with milestone 13.6 (merge commit 065001e147cdea1d0b4bcd78afc1deec9f7507c5) and is not present in release/13.5, the branch this docs PR targets. On release/13.5 the opposite is true — publishing a DotnetProjectResource does not throw:
- The entire
Aspire.Hosting.Dotnetproject has no publish/deploy/manifest guard: the onlyDistributedApplicationExceptionthrown byDotnetProjectHostingExtensions.csis for an invalid project path (:213), not for publishing. DotnetProjectResourceis anExecutableResource(src/Aspire.Hosting.Dotnet/DotnetProjectResource.cs:23), and executable resources are still serialized astype: "executable.v0"bysrc/Aspire.Hosting/Publishing/ManifestPublishingContext.cs:256— i.e. exactly theexecutable.v0-with-machine-local-paths output the doc claims was replaced.tests/Aspire.Hosting.Dotnet.Tests/DotnetProjectResourceTests.cs:267(AddDotnetProject_..._InPublishMode) exercises the resource underDistributedApplicationOperation.Publishand expects no exception.
Because this renders on the release/13.5 docs site, a 13.5 reader is told publishing throws an actionable error, when in 13.5 it still emits the executable.v0 manifest. Please target this at a 13.6 docs branch/SHA once one exists, or qualify the section so 13.6-only behavior isn't described as current on 13.5.
(The four suggested alternatives themselves are all valid on release/13.5; this comment is only about the publish-failure behavior.)
There was a problem hiding this comment.
PR to add this error to 13.5 is in review/waiting for approval microsoft/aspire#19399
| - Use `AddProject<TProject>(...)` for a project referenced by a C# AppHost. | ||
| - Use `AddCSharpApp(...)` / `addCSharpApp(...)` for a path-based project or file-based app that | ||
| should use standard .NET project publishing. | ||
| - Call `PublishAsDockerFile(...)` / `publishAsDockerFile(...)` to configure container publishing |
There was a problem hiding this comment.
Could we mention that this requires an existing Dockerfile in the project directory? PublishAsDockerFile() configures a Dockerfile build; without one this alternative just moves the user to another publish failure.
3 participants
Documents changes from microsoft/aspire#19190
@karolz-msTargeting
release/13.5— the latest release branch onmicrosoft/aspire.dev— becauserelease/13.6(from the source PR milestone13.6) does not exist there.Why
DotnetProjectResource(added viaAddDotnetProject/addDotnetProject) previously failed silently when a user attempted toaspire publish/aspire deployit. The source PR replaces the silent failure with an actionableDistributedApplicationExceptionand updates the integration README with a new## Publishingsection describing the limitation and the supported alternatives.What changed
src/frontend/src/content/docs/integrations/frameworks/dotnet/dotnet-host.mdx: added a## Publishingsection (mirroring the README addition) explaining that automatic publishing isn't supported forDotnetProjectResource, and listing the alternatives:AddProject<TProject>(...),AddCSharpApp(...)/addCSharpApp(...),PublishAsDockerFile(...)/publishAsDockerFile(...), andExcludeFromManifest()/excludeFromManifest().Page updated (no new pages created).