[docs] Document AzureBicepResourceScope.CreateForSubscription/CreateForTenant - #1451
[docs] Document AzureBicepResourceScope.CreateForSubscription/CreateForTenant#1451aspire-repo-bot[bot] wants to merge 3 commits into
Conversation
…rTenant 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. |
Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
David Pine (IEvangelist)
left a comment
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
Docs accuracy review
Source of truth: microsoft/aspire release/13.5 @ cfbf1c432e94dfe4a3261593eeef8c93913079bb
Claims: 10 total — 6 verified, 3 verified with nuance, 1 contradicted, 0 unverifiable
Blind docs test: PR head 9ec0e8c14efceefdc7a482e13525f98358a05b4f served locally; /integrations/cloud/azure/customize-resources/#set-the-deployment-scope exercised with 1 critical issue and 1 warning.
Phase A — Claim verification
The C# sample-compilability claim is contradicted and called out inline. The underlying source-head APIs and the TypeScript limitation are otherwise accurate.
Verified and verified-with-nuance claims
- A-1 — Verified: An unset scope falls back to resource-group deployment in
BicepUtilities.SetScopeAsync. - A-2 — Verified with nuance: Subscription and tenant targets are valid Bicep/ARM deployment scopes; this is an Azure platform fact rather than an Aspire API fact.
- A-3 — Verified:
AzureBicepResource.Scope,CreateForSubscription, andCreateForTenantexist with the documented shapes. - A-5 — Verified:
CreateForTenant()is parameterless. - A-6 — Verified with nuance:
targetScopemust match the deployment scope, but Azure ARM enforces the mismatch at deployment time; Aspire does not validate it in the app model. - A-7 — Verified:
CreateForSubscription(object subscription)requires one non-null subscription value. - A-8 — Verified: Tenant scope targets the current tenant; the provisioner writes
scope["tenant"] = "current". - A-9 — Verified: The complete
Aspire.Hosting.Azure.ats.txtsurface contains neitherAzureBicepResourceScopenor a scope capability/property, so the feature is not exposed to TypeScript. - A-10 — Verified with nuance: The Bicep snippets are valid;
locationis a known parameter that Aspire supplies automatically. The outputs are illustrative literals.
Phase B — Documentation Test Report
Focus Area: Customize Azure resources — Set the deployment scope
Date: 2026-08-11
Tester: doc-tester agent
Summary
| Category | Passed | Failed | Warnings |
|---|---|---|---|
| Content Accuracy | 5 | 1 | 1 |
| Code Examples | 0 | 1 | 0 |
| CLI Commands | 0 | 0 | 0 |
| Links | 2 | 0 | 0 |
Critical Issues
Issue 1: The C# AppHost sample is not copy-paste compilable
Location: http://127.0.0.1:4321/integrations/cloud/azure/customize-resources/#set-the-deployment-scope
Type: Example
Severity: Critical
What the documentation says:
subscriptionScoped.Resource.Scope = AzureBicepResourceScope.CreateForSubscription(subscriptionId.Resource);
tenantScoped.Resource.Scope = AzureBicepResourceScope.CreateForTenant();
What actually happens:
Using Aspire CLI 13.5.0-preview.1.26405.3, I created a clean C# AppHost, added Aspire.Hosting.Azure, copied the block exactly from the rendered page, and ran dotnet build apphost.cs. Both calls fail because the block does not import the type's namespace:
apphost.cs(17,37): error CS0103: The name 'AzureBicepResourceScope' does not exist in the current context
apphost.cs(28,31): error CS0103: The name 'AzureBicepResourceScope' does not exist in the current context
The local C# API reference identifies the namespace as Aspire.Hosting.Azure. Adding using Aspire.Hosting.Azure; removes CS0103 and confirms the missing import is the first blocker.
Recommended Action:
- Add
using Aspire.Hosting.Azure;to the C# block, or fully qualifyAzureBicepResourceScope. - Re-run the block in a clean AppHost before merging.
Warnings
Warning 1: The matching staging package does not yet contain the factories
After adding the required namespace, Aspire.Hosting.Azure 13.5.0-preview.1.26405.3 reports CS0117 for both factory methods. The methods exist at the pinned release/13.5 source tip, so this is package lag rather than a source contradiction, but readers cannot run the example with the currently available matching staging package. Add a version/availability note or merge the docs with the package that first contains these APIs.
Passed Checks
- The changed route renders with no browser console errors.
- The new heading appears in the table of contents and its anchor navigates correctly.
- The C# and TypeScript tabs render, switch, and synchronize through the
aspire-langquery parameter. - The TypeScript limitation note is visible and understandable.
- The code-copy button returns the exact displayed C# block.
- The deployment-scope link opens the intended Microsoft Learn article successfully.
Recommendations
- Add the missing C# namespace import.
- Align the page with the first published 13.5 package containing both factories, or state the required version.
- No other changes are needed in the new section.
Knowledge Gap: Runnable 13.5 package
What I needed to know: Which published 13.5 package first contains the two factory methods.
Source of my knowledge: The rendered docs and matching staging binaries did not provide this; no intrinsic product knowledge was used.
User impact: A reader can understand the feature but cannot validate or run it with the currently available matching staging package.
Recommendation: Publish or identify the minimum package version alongside the example.
|
|
||
| output value string = 'subscription' | ||
| """); | ||
| subscriptionScoped.Resource.Scope = AzureBicepResourceScope.CreateForSubscription(subscriptionId.Resource); |
There was a problem hiding this comment.
This block is not compilable as shown. AzureBicepResourceScope is declared in Aspire.Hosting.Azure, while the AppHost SDK injects global usings only for Aspire.Hosting and Aspire.Hosting.ApplicationModel (source). A clean 13.5 staging AppHost fails here with CS0103. Please add using Aspire.Hosting.Azure; at the start of the block, or fully qualify the type.
There was a problem hiding this comment.
Fixed in 2a00c63 — added using Aspire.Hosting.Azure; at the top of the C# block so it compiles against a clean 13.5 AppHost, and the note now calls out the required directive explicitly.
There was a problem hiding this comment.
Pull request overview
Adds documentation to the Azure “Customize resources” page describing how to change the deployment scope for custom Bicep resources, reflecting the shipped AzureBicepResourceScope.CreateForSubscription/CreateForTenant factory method names.
Changes:
- Adds a new “Set the deployment scope” section under Custom Bicep templates with a C# example for subscription- and tenant-scoped Bicep deployments.
- Notes the
targetScoperequirement in Bicep and clarifies that TypeScript AppHost APIs don’t currently exposeResource.Scope.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| <Aside type="note"> | ||
| `targetScope` in the Bicep template must match the scope you assign in C#. `CreateForSubscription` requires a subscription identifier; `CreateForTenant` targets the current tenant and takes no arguments. | ||
| </Aside> |
There was a problem hiding this comment.
Good catch — addressed in 2a00c63. The note now explains that param location string is a well-known Aspire parameter the provisioner fills in automatically from the environment's location and passes to every Bicep deployment (subscription- and tenant-scoped ones included), so it should stay declared in the template.
Resolves the merge conflict in customize-resources.mdx by placing the new "Set the deployment scope" section after "Pass parameters and read outputs" (both were inserted at the same location on their respective branches). Addresses review feedback on the deployment-scope C# sample: - Add `using Aspire.Hosting.Azure;` so the block compiles (AzureBicepResourceScope is not covered by the AppHost SDK global usings). - Note that CreateForSubscription/CreateForTenant are available in Aspire 13.5+. - Explain that `param location string` is a well-known Aspire parameter the provisioner supplies automatically and must stay declared in the template. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Documents changes from microsoft/aspire#18976
@sebastienrosTargeting
release/13.5based on the source PR milestone13.5.Why
PR #18976 renamed
AzureBicepResourceScope.ForSubscription/ForTenanttoCreateForSubscription/CreateForTenant(verb-phrase naming per API review) before these factory methods shipped. The Customize Azure resources page did not previously document Bicep deployment scoping at all, so this adds a new section covering the API using its final, shipped names.What changed
src/frontend/src/content/docs/integrations/cloud/azure/customize-resources.mdx: added a new### Set the deployment scopesection under Custom Bicep templates, showing how to useAzureBicepResourceScope.CreateForSubscription(...)andAzureBicepResourceScope.CreateForTenant()to setResource.Scopeon a Bicep resource, with a C# example adapted from the shipped API and its unit test, plus a note about matchingtargetScopein the Bicep template.No pages were newly created; one existing page was updated.