[docs] Document argument-based built-in resource commands (set-parameter/delete-parameter)

[aspire-repo-bot]

Documents changes from microsoft/aspire#17021, authored by @JamesNK.

Targeting release/13.4 based on the source PR milestone 13.4.

Why this PR is needed

Aspire 13.4 updates built-in resource commands to use structured Arguments on ResourceCommandAnnotation so callers (dashboard, CLI, MCP) can supply values directly without interactive prompting. Two built-in parameter commands were renamed for CLI consistency:

• parameter-set → set-parameter
• parameter-delete → delete-parameter

The old names are kept as aliases. The renamed commands now accept named option flags (--value, --save-to-user-secrets, --delete-from-user-secrets), enabling non-interactive use from scripts and automation.

Documentation changes

Updated pages

• src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx — Added a new Built-in parameter commands section documenting set-parameter (with --value and --save-to-user-secrets options) and delete-parameter (with --delete-from-user-secrets), including the rename note.
• src/frontend/src/content/docs/whats-new/aspire-13-4.mdx — Added an Argument-based built-in resource commands section explaining the feature, CLI examples, and the command rename table.

Generated by PR Documentation Check for issue #17021 · ● 21.7M · ◷

[Copilot]

Pull request overview

Documents Aspire 13.4’s updated built-in parameter resource commands for aspire resource, including the move to argument-based (named option) invocation and the canonical rename to set-parameter / delete-parameter (with old names retained as aliases).

Changes:

• Adds a “what’s new” entry describing argument-based built-in resource commands and the command rename mapping.
• Updates the aspire resource CLI reference to include a new “Built-in parameter commands” section with options and examples.
• Expands the <command> argument description to include the new canonical parameter command names as examples.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/frontend/src/content/docs/whats-new/aspire-13-4.mdx	Adds a new “Argument-based built-in resource commands” section with examples and a rename table.
src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx	Documents set-parameter / delete-parameter built-ins, their options, and notes the rename/aliases.

Comments suppressed due to low confidence (1)

src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx:142

• The options table lists --delete-from-user-secrets as a value-less flag, but the examples pass an explicit boolean value (--delete-from-user-secrets true). Consider updating the option documentation to show the boolean value syntax (e.g., --delete-from-user-secrets <true|false>) or adjusting the example to match the intended usage.

  | Option | Description |
  | --- | --- |
  | `--delete-from-user-secrets` | Also remove the value from the .NET user secrets store. Optional. |

  ```bash title="Aspire CLI"
  aspire resource mydb-password delete-parameter
  aspire resource mydb-password delete-parameter --delete-from-user-secrets true

</details>



---

💡 <a href="/microsoft/aspire.dev/new/release/13.4?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

[IEvangelist]

Generated by running the doc-tester skill against PR #974 — built the docs locally with aspire run, browsed the changed pages on the local Astro frontend (not aspire.dev), inspected the rendered HTML, and validated link/component usage. The skill's "user-centric" rules were followed (no Aspire product source code was consulted).

Summary

The PR adds new docs for two argument-based built-in resource commands (set-parameter, delete-parameter) in two files:

• src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx — new Built-in parameter commands section. Renders correctly on the local site: the H2 anchor #built-in-parameter-commands is present, the option tables, code samples, and <Aside type="note"> all render as expected.
• src/frontend/src/content/docs/whats-new/aspire-13-4.mdx — new top-level Argument-based built-in resource commands section plus a "This release introduces:" bullet and a <LearnMore> callout.

The reference page changes are good. The whats-new changes have two blocking problems when considered against release/13.4: a broken <LearnMore> (the link silently disappears at render time) and a hard merge conflict against the page that release/13.4 has since grown.

Verdict

Request changes. The doc would mislead a reader on a key navigation step (the LearnMore renders as plain text, not a link), and the PR currently can't be merged into release/13.4 without manual conflict resolution that also has to reconcile content that already covers part of this topic.

Findings

🔴 Blocker — <LearnMore link="…"> renders as plain text, not a link

File: src/frontend/src/content/docs/whats-new/aspire-13-4.mdx, line 59

<LearnMore link="/reference/cli/commands/aspire-resource/#built-in-parameter-commands">Built-in parameter commands</LearnMore>

The LearnMore.astro component (src/frontend/src/components/LearnMore.astro) does not accept a link prop. It only renders its children:

<div class="learn-more">
  <Icon class="icon" name="open-book" />
  <span><slot /></span>
</div>

I verified this against the locally-built site. The rendered HTML for this LearnMore is literally:

<div class="learn-more …"><svg …open-book…></svg><span …>Built-in parameter commands</span></div>

No <a href>, no clickable target. The reader sees the open-book icon next to dead text — there is no way to navigate to the reference page from the whats-new page.

For comparison, every existing <LearnMore> on release/13.4's whats-new/aspire-13-4.mdx uses the standard pattern with a markdown link in the slot:

<LearnMore>
  For more information, see [`aspire resource`](/reference/cli/commands/aspire-resource/).
</LearnMore>

Suggested fix:

<LearnMore>
  For details and options, see [Built-in parameter commands](/reference/cli/commands/aspire-resource/#built-in-parameter-commands).
</LearnMore>

The destination anchor (#built-in-parameter-commands) is rendered correctly on the reference page and resolves locally, so only the source markup needs fixing.

Note: the PR also introduces (or carries over from a stale base) a second instance of the same bad pattern on line 72: <LearnMore link="/whats-new/upgrade-aspire/">Upgrade Aspire</LearnMore>. If that line is in the final merge, it should be fixed the same way.

🔴 Blocker — Merge conflict and topic duplication against release/13.4

GitHub reports mergeStateStatus: DIRTY, mergeable: CONFLICTING. Reproduced locally:

$ git merge --no-commit --no-ff upstream/release/13.4
Auto-merging src/frontend/src/content/docs/whats-new/aspire-13-4.mdx
CONFLICT (content): Merge conflict in src/frontend/src/content/docs/whats-new/aspire-13-4.mdx

The PR was authored against a near-empty stub of whats-new/aspire-13-4.mdx (~73 lines). The current release/13.4 version of that file is ~22 KB and already covers this area:

• An existing top-level "This release introduces:" bullet covers it: "Richer resource commands with typed arguments, visibility controls, immediate result display, named CLI options, resource-scoped help, …".
• An existing ### Resource command CLI improvements H3 (under 🛠️ CLI enhancements) already says: "Resource command inputs are now passed as named CLI options instead of positional arguments. … Running aspire resource <resource> --help also shows the commands available for that specific resource."
• An existing ### Resource command arguments, visibility, and results H3 covers typed-argument command authoring.

The PR's new H2 ## Argument-based built-in resource commands and its "This release introduces:" bullet aren't just hard to merge — they overlap with content already shipped on the page. The resolution should not be a mechanical "keep both"; the new material needs to be folded into the existing structure.

(reference/cli/commands/aspire-resource.mdx merges cleanly against release/13.4 and that file's surrounding ## Arguments / ## Options context is unchanged, so the conflict is isolated to whats-new.)

Suggested fix (whats-new only):

• Drop the new top-level "This release introduces:" bullet (it's redundant with the existing "Richer resource commands" bullet, which already lists named CLI options as a 13.4 highlight).
• Promote the renamed-commands content to a new H3 underneath the existing ### Resource command CLI improvements (or as a sibling H3 in the same section), instead of adding a brand-new top-level ## Argument-based built-in resource commands. Suggested heading: ### Built-in parameter commands (renamed).
• Move the parameter-set → set-parameter / parameter-delete → delete-parameter rename table into that H3, since today the rename isn't documented anywhere on the whats-new page.
• Use the corrected <LearnMore> pattern from the previous finding.

🟡 Major — Examples reference an undefined mydb-password parameter resource

Every example on both pages uses aspire resource mydb-password set-parameter … / aspire resource mydb-password delete-parameter …, but neither page shows how that resource gets into the AppHost. A reader following these docs as a "new user" has no way to reach a working aspire resource mydb-password … invocation without already knowing about AddParameter(...).

Both pages should either:

• Add a one-liner AppHost snippet showing where mydb-password comes from (e.g. builder.AddParameter("mydb-password", secret: true);), or
• Link to /fundamentals/external-parameters/ (which the aspire-resource.mdx page does not currently reference at all) the first time mydb-password appears.

A short cross-reference next to the ## Built-in parameter commands heading would be enough:

These commands operate on parameter resources declared in your AppHost (see External parameters).

🟡 Major — Boolean option syntax is shown but never explained

The examples use a --flag true form for the boolean options:

aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword" --save-to-user-secrets true
aspire resource mydb-password delete-parameter --delete-from-user-secrets true

But the option tables describe these flags as if they were bare switches:

--save-to-user-secrets — Save the value to the .NET user secrets store…
--delete-from-user-secrets — Also remove the value from the .NET user secrets store. Optional.

This leaves the reader uncertain whether:

• --save-to-user-secrets alone (no value) works,
• --save-to-user-secrets false is meaningful,
• and what the default is when the flag is omitted (set-parameter says "defaults to preserving any existing saved state" — but doesn't say what that resolves to in practice).

For docs targeting "scripts, CI/CD pipelines, and AI coding agents," this ambiguity is worth tightening up. Either show the accepted forms in the table (<true|false>) or pick one canonical syntax and use it consistently.

🟢 Minor — --help discoverability example only on whats-new

whats-new/aspire-13-4.mdx shows:

aspire resource mydb-password set-parameter --help

…but the reference page aspire-resource.mdx, which is the page a reader actually lands on for command reference, never demonstrates set-parameter --help / delete-parameter --help. The reference page should include the per-command --help example so users discover the option list the canonical way, especially since the page already establishes elsewhere that "the help output lists each argument with its type, whether it's required, its default value…".

🟢 Minor — "Required" for --value is buried in the cell description

In the set-parameter option table:

| `--value <value>` | The value to assign to the parameter. Required. |

Visually this looks like every other row. Other CLI reference pages in this repo use bold or a leading Required. tag, or a separate Required column. Minor consistency nit — not worth blocking on.

Knowledge Gaps

I followed the doc-tester skill rule of not reading Aspire product source. Two things in this PR I could not verify end-to-end from documentation + a working AppHost:

1. That set-parameter / delete-parameter actually exist on parameter resources in 13.4 today, and that parameter-set / parameter-delete still work as aliases. I have aspire CLI 13.4.0-preview.1.26269.1 installed and the docs site running, but a quick scratch AppHost with AddParameter("mydb-password", secret: true) couldn't successfully start under that SDK preview ("AppHost process has exited unexpectedly" — backchannel never came up). I did not chase this further to keep the review under user-centric rules.

   • User impact: Following these docs literally is the only way a new user would learn these commands exist — so when the docs ship, please confirm both the canonical and alias forms still resolve on the actual 13.4 release CLI, and that --save-to-user-secrets / --delete-from-user-secrets accept the <flag> true form shown.
   • Recommendation: A maintainer with a working 13.4 AppHost containing an AddParameter(...) resource should run aspire resource <param> set-parameter --help and paste the actual help output into the reference page (similar to the existing Echo a message… example on the page).

2. --save-to-user-secrets default behavior wording. The phrase "defaults to preserving any existing saved state" in the set-parameter option table is not something I could derive from any other page on the local site. I assumed it meant "if the parameter was previously saved to user secrets and you omit this flag, the saved copy is left as-is" — but the doc never says that explicitly. Worth either expanding or dropping the half-sentence.

What I checked that passed

• Both pages load with HTTP 200 from the locally-built site (http://localhost:59516).
• ## Built-in parameter commands renders as an H2 with id="built-in-parameter-commands" on the reference page, is in the page's right-rail TOC, and the section anchor resolves.
• The <Aside type="note"> callouts on both pages render with the correct note styling.
• Code samples (```bash title="Aspire CLI") render with the expected title and copy-to-clipboard control.
• The rename callout (parameter-set → set-parameter, parameter-delete → delete-parameter) is consistent across both pages.
• The aspire-resource.mdx patch applies cleanly to release/13.4 (no conflict in that file).

---

Review generated by an AI agent running the doc-tester skill end-to-end against this PR on the release/13.4 base. No files in the repo were modified.