[docs] Update ASPIREAZURE003 diagnostic docs to cover AzureRoleAssignmentResource (13.4)#1140
Conversation
AzureRoleAssignmentResource is now marked [Experimental("ASPIREAZURE003")]
as part of the 13.4 API review fixes (microsoft/aspire#17706). Update the
diagnostic page to list all APIs that trigger ASPIREAZURE003 and add an
experimental caution to the role-assignments programmatic inspection section.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
aspire-repo-bot
Bot
added
the
docs-from-code
There was a problem hiding this comment.
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
ASPIREAZURE003diagnostic page to list both VNet APIs (13.2) andAzureRoleAssignmentResource(13.4), and adds a second example. - Adds an experimental-API caution callout and a
#pragma warning disable ASPIREAZURE003line 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
left a comment
IEvangelist
left a comment
There was a problem hiding this comment.
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 triggerASPIREAZURE003" 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
-
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:6carries 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. -
Aspire.Hosting.Azure.NetworkAPIs trigger ASPIREAZURE003 (since 13.2) (line 22) —verified.src/Aspire.Hosting.Azure.Network/AssemblyInfo.cs:6applies the diagnostic at assembly scope. Repo history confirms this assembly + diagnostic shipped in 13.2. -
AzureRoleAssignmentResourcefromAspire.Hosting.Azuretriggers ASPIREAZURE003 (since 13.4) (line 23) —verified.src/Aspire.Hosting.Azure/AzureRoleAssignmentResource.cs:23declares[Experimental("ASPIREAZURE003", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]on apublic sealed class. The attribute was added by PR #17706 (the source PR this docs change is tracking), which merged intorelease/13.4as commitda473d27f. -
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 directnewis 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. -
Suppression directives (
.editorconfigdotnet_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 ASPIREAZURE003is 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
-
TypeScript method
withSearchRoleAssignments(replacing the previouswithRoleAssignmentscall) is correct for Azure AI Search (line 89, line 96) —verified.src/Aspire.Hosting.Azure.Search/AzureSearchExtensions.cs:152decoratesWithRoleAssignments<T>with[AspireExport("withSearchRoleAssignments")], so the canonical TypeScript surface name is exactlywithSearchRoleAssignments. This is a bonus bug fix tangential to source PR #17706 — the rename is independently verifiable against source. -
AzureRoleAssignmentResourceis "marked as experimental ASPIREAZURE003 as of Aspire 13.4" (lines 104–106 — the:::caution[Experimental API]Aside) —verified. Same evidence as claim #3. -
AzureRoleAssignmentResourceexposes 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 whichWithRoleAssignmentswas called; identity = the user-assigned managed identity).
-
OfType<AzureRoleAssignmentResource>().Where(r => r.TargetAzureResource == keyVault.Resource)is a valid enumeration pattern (code example around lines 125–155) —verified. The class ispublic sealed, the properties are public, and there is no restriction on enumerating via the standardIDistributedApplicationBuilder.Resourcesmodel + LINQ. The#pragma warning disable ASPIREAZURE003 // AzureRoleAssignmentResource is Experimentalon line 127 correctly accompanies the existingASPIREAZURE001pragma. -
(verified-with-nuance) The "APIs that trigger
ASPIREAZURE003" bullet list (aspireazure003.mdxlines 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/aspiresource 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- ` items.
## ExamplesH2 renders with both H3 subsections —Azure Virtual Network (since 13.2)(idazure-virtual-network-since-132) andAzure role assignment resource (since 13.4)(idazure-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 titleC# — AppHost.cs, syntax highlighting, and a working Copy-to-clipboard button (data attribute matches the rendered source). ## To correct this errorsection renders with three suppression bullets unchanged.- On-this-page TOC includes
Examples, both H3 children, andTo correct this errorin correct order.
with two-
/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 aswithSearchRoleAssignments", which matches the renamed surface above it. - The
inspect-role-assignmentsC# example renders with both#pragma warning disabledirectives at the top (ASPIREAZURE001forAzureEnvironmentResource,ASPIREAZURE003forAzureRoleAssignmentResource), and the rest of the pipeline-step body is unchanged. - The 3-row property table for
AzureRoleAssignmentResourcerenders cleanly with correct column alignment.
- The new
Recommendations
- (Non-blocking, mirrors Phase A nuance #10) Consider broadening the "APIs that trigger
ASPIREAZURE003" bullet list onaspireazure003.mdxto include the Sql and otherAspire.Hosting.Azureannotations 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 innew 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 (therole-assignments.mdxpage covers that with theOfType<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/.astroand restartaspire startto flush stale rendered content — a parallel-worktree Astro dev server had grabbed port 4321 and a cached build was serving an oldergit-commit-idfor this branch's content. After the restart, the correct PR 1140 content (headd0b044be5) 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).
- Broaden ASPIREAZURE003 affected API list (PRRT_kwDOQK_VN86F5tQC) Verified against microsoft/aspire@2574ef5 on branch release/13.4. Edited per the doc-writer skill. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
CI Failure -- Requires Fix in This PRThe 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 The fix is to shorten the page See: |
CI Failure - Action RequiredCI has failed twice with the same issue, which is tied to changes in this PR: Test: Failing page:
The Fix options:
Since this has failed consistently across multiple CI runs, automatic retriggering has been skipped - the fix needs to be made in the PR first. |
|
|
1 similar comment
|
|
CI failure requires PR content fixThis PR has failed CI twice on the same test: SEO meta description length check in ests/unit/seo-lengths.vitest.test.ts. Error:
The description field in diagnostics/aspireazure003.mdx exceeds the maximum allowed character length for SEO meta descriptions. This is not a transient/infrastructure failure — it's caused by content introduced in this PR. Fix needed: Shorten the description frontmatter in diagnostics/aspireazure003.mdx to fit within the allowed SEO length limit (typically ≤ 160 chars total, check the exact limit in the test). Tagging @joperezr to review and fix. |
|
CI has been retriggered multiple times and is still failing in content-related validation/build jobs. Latest failed run: https://github.com/microsoft/aspire.dev/actions/runs/26699410966 This looks more likely to be caused by the PR changes than transient infrastructure flakiness. Please investigate. |
|
The \ rontend-build / Frontend Build\ step is failing because a test detects that one or more pages introduced by this PR have an \og:title\ (Open Graph title) outside the required 30–65 character range: \ This is not a transient/infrastructure failure — the test is checking content added by this PR. The CI has been retriggered, but it will continue to fail until the \og:title\ for the affected page(s) is adjusted to be between 30 and 65 characters. Please update the affected .mdx\ file(s) to ensure the \ itle\ frontmatter field (which becomes the \og:title) is within the required length range. |
IEvangelist
requested review from
JamesNK,
aaronpowell,
maddymontaquila and
mitchdenny
as code owners
Documents changes from microsoft/aspire#17706 by
@joperezr.Targeting
release/13.4based on the source PR milestone13.4(exact match onmicrosoft/aspire.dev).Why this PR is needed
In microsoft/aspire#17706,
AzureRoleAssignmentResourcewas marked[Experimental("ASPIREAZURE003")]as part of 13.4 API review fixes. TheASPIREAZURE003diagnostic previously only documented Azure Virtual Network types (Aspire.Hosting.Azure.Network). Starting in 13.4, directly usingAzureRoleAssignmentResourcealso 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 thatAzureRoleAssignmentResourcealso triggers the diagnostic.integrations/cloud/azure/role-assignments.mdx— Added an experimental caution callout to the "Inspect role assignments programmatically" section noting thatAzureRoleAssignmentResourceis experimental (ASPIREAZURE003) as of 13.4. Updated the code example to include the#pragma warning disable ASPIREAZURE003suppression alongside the existingASPIREAZURE001suppression.Files modified
src/frontend/src/content/docs/diagnostics/aspireazure003.mdx(updated)src/frontend/src/content/docs/integrations/cloud/azure/role-assignments.mdx(updated)