[docs] Update ASPIREAZURE003 diagnostic docs to cover AzureRoleAssignmentResource (13.4)

[aspire-repo-bot]

Documents changes from microsoft/aspire#17706 by @joperezr.

Targeting release/13.4 based on the source PR milestone 13.4 (exact match on microsoft/aspire.dev).

Why this PR is needed

In microsoft/aspire#17706, AzureRoleAssignmentResource was marked [Experimental("ASPIREAZURE003")] as part of 13.4 API review fixes. The ASPIREAZURE003 diagnostic previously only documented Azure Virtual Network types (Aspire.Hosting.Azure.Network). Starting in 13.4, directly using AzureRoleAssignmentResource also triggers this compiler error — a user-facing change that users who rely on this type will encounter.

What was changed

• diagnostics/aspireazure003.mdx — Updated the page title, description, and intro to reflect that ASPIREAZURE003 now covers multiple Azure experimental APIs (not just Virtual Network). Added a second example section showing that AzureRoleAssignmentResource also triggers the diagnostic.

• integrations/cloud/azure/role-assignments.mdx — Added an experimental caution callout to the "Inspect role assignments programmatically" section noting that AzureRoleAssignmentResource is experimental (ASPIREAZURE003) as of 13.4. Updated the code example to include the #pragma warning disable ASPIREAZURE003 suppression alongside the existing ASPIREAZURE001 suppression.

Files modified

• src/frontend/src/content/docs/diagnostics/aspireazure003.mdx (updated)
• src/frontend/src/content/docs/integrations/cloud/azure/role-assignments.mdx (updated)

Generated by PR Documentation Check for issue #17706 · ● 13.5M · ◷

[Copilot]

Pull request overview

Updates Aspire docs to reflect that as of 13.4, AzureRoleAssignmentResource is now public and gated by the ASPIREAZURE003 experimental diagnostic (previously only used for Azure Virtual Network APIs).

Changes:

• Broadens the ASPIREAZURE003 diagnostic page to list both VNet APIs (13.2) and AzureRoleAssignmentResource (13.4), and adds a second example.
• Adds an experimental-API caution callout and a #pragma warning disable ASPIREAZURE003 line to the role assignments programmatic inspection sample.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/frontend/src/content/docs/diagnostics/aspireazure003.mdx	Reframes the diagnostic from VNet-only to multiple Azure experimental APIs; adds 13.4 example.
src/frontend/src/content/docs/integrations/cloud/azure/role-assignments.mdx	Adds experimental-API callout and an extra #pragma warning disable ASPIREAZURE003 in the pipeline sample.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[IEvangelist]

Automated docs-from-code review

Source-of-truth branch: microsoft/aspire@release/13.4 @ 2574ef57e97fc393aff67592fd442afca6a6d02f
Source PR documented: microsoft/aspire#17706 (merge commit da473d27f)
PR head reviewed: d0b044be58134f9b49795751a20e6d460a88c41e

Phase A — Claim verification: 10 verifiable claims extracted across 2 files.

Verdict	Count
verified	9
verified-with-nuance	1
unverifiable	0
contradicted	0

Phase B — Doc-tester run (local frontend http://localhost:57862/): 2 doc routes exercised (/diagnostics/aspireazure003/ and /integrations/cloud/azure/role-assignments/). 0 critical issues, 0 warnings, 1 knowledge-gap echo of the Phase A nuance.

Verdict: COMMENT — the docs accurately describe the new AzureRoleAssignmentResource experimental mark and render cleanly. One non-blocking suggestion: the "APIs that trigger ASPIREAZURE003" bullet list is presented as exhaustive but omits several other release/13.4 APIs that also raise the diagnostic; see the inline comment below.

---

Phase A — Claim verification

Inline comments (this review)

• aspireazure003.mdx ~line 20 — verified-with-nuance: the "APIs that trigger ASPIREAZURE003" list is incomplete; details + suggested additions are in the inline thread.

No contradictions or unverifiable claims

Verified claims (full catalog)

Click to expand — 10 claims with source evidence

diagnostics/aspireazure003.mdx

1. Diagnostic message wording — "Azure types and members are for evaluation purposes only…" (line 16) — verified. Matches the boiler-plate message used by the experimental ASPIREAZURE003 surfaces (e.g. Aspire.Hosting.Azure.Network/AssemblyInfo.cs:6 carries the assembly-wide [Experimental("ASPIREAZURE003", UrlFormat = "https://aka.ms/aspire/diagnostics#{0}")] whose default Roslyn message is "is for evaluation purposes only…"). Broadening "Azure Virtual Network types" → "Azure types and members" correctly reflects that ASPIREAZURE003 is no longer scoped to one assembly.

2. Aspire.Hosting.Azure.Network APIs trigger ASPIREAZURE003 (since 13.2) (line 22) — verified. src/Aspire.Hosting.Azure.Network/AssemblyInfo.cs:6 applies the diagnostic at assembly scope. Repo history confirms this assembly + diagnostic shipped in 13.2.

3. AzureRoleAssignmentResource from Aspire.Hosting.Azure triggers ASPIREAZURE003 (since 13.4) (line 23) — verified. src/Aspire.Hosting.Azure/AzureRoleAssignmentResource.cs:23 declares [Experimental("ASPIREAZURE003", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")] on a public sealed class. The attribute was added by PR #17706 (the source PR this docs change is tracking), which merged into release/13.4 as commit da473d27f.

4. new AzureRoleAssignmentResource("role", ...) is the user-facing surface that raises the diagnostic (lines 41–42) — verified. The class is public with a public constructor, so direct new is the natural source of the diagnostic. Constructor signature in source: AzureRoleAssignmentResource(string name, AzureProvisioningResource targetAzureResource, IResource? ownerResource, AzureUserAssignedIdentityResource? identityResource, Action<AzureResourceInfrastructure> configureInfrastructure) — the example's ("role", ...) placeholder accurately models this.

5. Suppression directives (.editorconfig dotnet_diagnostic.ASPIREAZURE003.severity = none, <NoWarn>$(NoWarn);ASPIREAZURE003</NoWarn>, #pragma warning disable ASPIREAZURE003) (lines 51–66) — verified. All three are standard Roslyn suppression mechanics and #pragma warning disable ASPIREAZURE003 is the same form used throughout the Aspire source itself (e.g. src/Aspire.Hosting.Azure.Sql/AzureSqlExtensions.cs:4, src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppEnvironmentResource.cs:6, etc.).

integrations/cloud/azure/role-assignments.mdx

6. TypeScript method withSearchRoleAssignments (replacing the previous withRoleAssignments call) is correct for Azure AI Search (line 89, line 96) — verified. src/Aspire.Hosting.Azure.Search/AzureSearchExtensions.cs:152 decorates WithRoleAssignments<T> with [AspireExport("withSearchRoleAssignments")], so the canonical TypeScript surface name is exactly withSearchRoleAssignments. This is a bonus bug fix tangential to source PR #17706 — the rename is independently verifiable against source.

7. AzureRoleAssignmentResource is "marked as experimental ASPIREAZURE003 as of Aspire 13.4" (lines 104–106 — the :::caution[Experimental API] Aside) — verified. Same evidence as claim #3.

8. AzureRoleAssignmentResource exposes three properties — TargetAzureResource, OwnerResource, IdentityResource (lines 115–121 table) — verified. Source confirms exactly these three properties:

   • TargetAzureResource → AzureProvisioningResource (src/Aspire.Hosting.Azure/AzureRoleAssignmentResource.cs:35)
   • OwnerResource → IResource? (line 47)
   • IdentityResource → AzureUserAssignedIdentityResource? (line 53)
     The descriptions are accurate narrative interpretations (target = scope; owner = the resource on which WithRoleAssignments was called; identity = the user-assigned managed identity).

9. OfType<AzureRoleAssignmentResource>().Where(r => r.TargetAzureResource == keyVault.Resource) is a valid enumeration pattern (code example around lines 125–155) — verified. The class is public sealed, the properties are public, and there is no restriction on enumerating via the standard IDistributedApplicationBuilder.Resources model + LINQ. The #pragma warning disable ASPIREAZURE003 // AzureRoleAssignmentResource is Experimental on line 127 correctly accompanies the existing ASPIREAZURE001 pragma.

10. (verified-with-nuance) The "APIs that trigger ASPIREAZURE003" bullet list (aspireazure003.mdx lines 20–23) — substance is correct (both listed surfaces ARE marked), but the list reads as exhaustive ("the following APIs") while release/13.4 marks several additional public surfaces with [Experimental("ASPIREAZURE003")] that aren't covered by either bullet. See the inline comment for the full list and rationale.

---

Phase B — Doc-tester report

Note: this report comes from a "blind user" perspective — I navigated the local frontend with Playwright-style checks against the rendered HTML and did not consult microsoft/aspire source while gathering it.

Pages exercised (local frontend http://localhost:57862/):

• /diagnostics/aspireazure003/
• /integrations/cloud/azure/role-assignments/

Category	Passed	Failed	Warnings
Content rendering	8	0	0
Code examples	4	0	0
Internal links	2	0	0
Component rendering (Asides, code blocks, tables)	4	0	0

Critical issues

None.

Warnings

None.

Passed checks

• /diagnostics/aspireazure003/

  • Blockquote at top renders the new wording: "Azure types and members are for evaluation purposes only and are subject to change or removal in future updates."
  • **APIs that trigger \ASPIREAZURE003`:**bullet list renders as a
    with two
    • ` items.
    • ## Examples H2 renders with both H3 subsections — Azure Virtual Network (since 13.2) (id azure-virtual-network-since-132) and Azure role assignment resource (since 13.4) (id azure-role-assignment-resource-since-134) — both linked from the on-this-page sidebar.
    • The new C# code block (var roleAssignment = new AzureRoleAssignmentResource("role", ...);) renders inside an Expressive Code <figure> with title C# — AppHost.cs, syntax highlighting, and a working Copy-to-clipboard button (data attribute matches the rendered source).
    • ## To correct this error section renders with three suppression bullets unchanged.
    • On-this-page TOC includes Examples, both H3 children, and To correct this error in correct order.

  • /integrations/cloud/azure/role-assignments/

    • The new :::caution[Experimental API] block renders as a Starlight caution Aside (<aside class="starlight-aside starlight-aside--caution">) with the warning icon and the title "Experimental API".
    • Inside the Aside, the cross-link to /diagnostics/aspireazure003/ is well-formed (site-relative, trailing slash, valid target).
    • The TypeScript example shows await api.withSearchRoleAssignments(search, [AzureSearchRole.SearchIndexDataReader]); and renders with TwoSlash type info hover targets (no Pivot/Tabs issues).
    • The narrative paragraph below the TS example correctly says "C# WithRoleAssignments … or a resource-specific TypeScript role assignment method such as withSearchRoleAssignments", which matches the renamed surface above it.
    • The inspect-role-assignments C# example renders with both #pragma warning disable directives at the top (ASPIREAZURE001 for AzureEnvironmentResource, ASPIREAZURE003 for AzureRoleAssignmentResource), and the rest of the pipeline-step body is unchanged.
    • The 3-row property table for AzureRoleAssignmentResource renders cleanly with correct column alignment.

  Recommendations

  1. (Non-blocking, mirrors Phase A nuance #10) Consider broadening the "APIs that trigger ASPIREAZURE003" bullet list on aspireazure003.mdx to include the Sql and other Aspire.Hosting.Azure annotations that also raise the diagnostic in 13.4. See the inline comment for specifics. As a blind reader hitting the diagnostic from one of those APIs, the current page wording (especially "the following APIs") doesn't signal that the page applies to me.

  Knowledge gaps

  None of consequence. The Azure role assignment resource (since 13.4) example uses ... as a literal placeholder in new AzureRoleAssignmentResource("role", ...); this is conventional in diagnostic-explainer docs and the section's purpose is clearly to trigger the diagnostic rather than to teach how to construct the resource (the role-assignments.mdx page covers that with the OfType<AzureRoleAssignmentResource>() enumeration pattern). Reasonable to leave as-is.

  ---

  Tooling note (not a finding against the PR)

  During Phase B I had to clear src/frontend/node_modules/.astro + src/frontend/.astro and restart aspire start to flush stale rendered content — a parallel-worktree Astro dev server had grabbed port 4321 and a cached build was serving an older git-commit-id for this branch's content. After the restart, the correct PR 1140 content (head d0b044be5) was served on the apphost-assigned port (57862). Mentioning here for traceability; not actionable on the PR.

  — posted by the hourly docs-from-code reviewer (Phase A + Phase B both ran; this is a complete, non-partial review).

[IEvangelist]

CI Failure -- Requires Fix in This PR

The CI build has failed multiple times on this PR with the same error. The failure is due to a change in the PR itself, not a transient issue.

Error: The og:title for diagnostics/aspireazure003.mdx is 66 characters, which exceeds the allowed maximum of 65 characters.

The fix is to shorten the page title frontmatter to 65 characters or fewer (ideally 50-60 for optimal SEO), or add a seoTitle frontmatter override.

See: tests/unit/seo-lengths.vitest.test.ts