docs: fix inaccurate APIs and instructions on Customize Azure resources#942
Open
IEvangelist wants to merge 1 commit into
Open
docs: fix inaccurate APIs and instructions on Customize Azure resources#942IEvangelist wants to merge 1 commit into
IEvangelist wants to merge 1 commit into
Conversation
The Customize Azure resources page documented APIs that don't exist and described run-time behavior that doesn't match the product: - `AddAzureBicepResource(name, bicepFilePath)` is not a real method. Replaced with the actual `AddBicepTemplate(name, bicepFile)`, and mentioned `AddBicepTemplateString` for inline templates. - The `PrivateEndpoint` sample used a non-existent `SubnetReference` type and was missing `PrivateLinkServiceConnections`. Rewrote the sample to set `Subnet.Id` via a `ProvisioningParameter` and to add a `NetworkPrivateLinkServiceConnection`, matching the pattern Aspire uses internally. Added a tip pointing users at the higher-level `AddPrivateEndpoint` extension for the common case. - `Inspect generated Bicep` told users to `Run your AppHost locally` and open `./infra`. At run time Aspire emits Bicep to a temp subdirectory; `./infra` is only populated by `aspire publish -o ./infra`. Replaced the steps with the publish workflow and noted the run-time behavior in an Aside. Fixes #246 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Updates the Customize Azure resources documentation to match current Aspire/Azure Provisioning APIs and the actual Bicep generation workflow, so readers can compile samples and find the expected output files.
Changes:
- Replaced a non-existent
AddAzureBicepResourcedoc sample withAddBicepTemplate(and referencedAddBicepTemplateStringfor inline templates). - Rewrote the
PrivateEndpointConfigureInfrastructuresample to use realAzure.Provisioning.Networktypes and produce valid Bicep. - Corrected “Inspect generated Bicep” instructions to use
aspire publish -o ...and documented the emitted layout.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+409
to
+411
| var account = infra.GetProvisionableResources() | ||
| .OfType<StorageAccount>() | ||
| .Single(); |
| }); | ||
| ``` | ||
|
|
||
| `PrivateEndpoint` and `NetworkPrivateLinkServiceConnection` come from the `Azure.Provisioning.Network` namespace, and `ProvisioningParameter` comes from `Azure.Provisioning`. Adding a `ProvisioningParameter` lets you pass the subnet ID into the generated Bicep at deployment time. |
Comment on lines
+409
to
+411
| var account = infra.GetProvisionableResources() | ||
| .OfType<StorageAccount>() | ||
| .Single(); |
eerhardt
reviewed
May 13, 2026
| var subnetId = new ProvisioningParameter("subnetId", typeof(string)); | ||
| infra.Add(subnetId); | ||
|
|
||
| var privateEndpoint = new PrivateEndpoint("storagepe"); |
Member
There was a problem hiding this comment.
This seems like a contrived example - especially since our Aside even says "don't do this". Is there a better scenario we could illustrate here? Setting some other properties on the Storage account?
One idea is to enable an Microsoft.Storage/storageAccounts/inventoryPolicies
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #246
Summary
The Customize Azure resources page contained three documented APIs / behaviors that don't match the current product. New users following the page can't compile the samples and can't find the files the page says will appear. This PR replaces those samples with ones that match the current
Aspire.Hosting.Azure,Aspire.Hosting.Azure.Network, andAzure.ProvisioningAPIs.Changes
builder.AddAzureBicepResource(name: "storage", bicepFilePath: "./custom-storage.bicep")with the actual method,builder.AddBicepTemplate("storage", "./custom-storage.bicep"). Added a one-liner pointing readers atAddBicepTemplateStringfor inline templates.PrivateEndpointC# sample to use real types fromAzure.Provisioning.Network: dropped the fakeSubnetReferenceinitializer, setprivateEndpoint.Subnet.Idvia anAzure.Provisioning.ProvisioningParameter, and added the missingPrivateLinkServiceConnections.Add(new NetworkPrivateLinkServiceConnection { ... })so the emitted Bicep is actually valid. Added a tip<Aside>pointing readers at the higher-levelAddPrivateEndpointextension in the Azure Virtual Network integration, which is the idiomatic API for most users. Added a short sentence explaining which namespaces the types come from../infra" instructions with theaspire publish -o ./infraworkflow. Added a<Aside type="note">explaining thataspire runwrites Bicep to a temp directory used by the local provisioner — it does not populate./infrain the AppHost project. Updated the directory-walkthrough to describe the actual emitted layout (main.bicepplus one module per resource).Evidence the issue still reproduces on the live site
Verified before editing by browsing https://aspire.dev/integrations/cloud/azure/customize-resources/ with playwright-cli on 2026-05-13:
builder.AddAzureBicepResource(name: "storage", bicepFilePath: "./custom-storage.bicep")— that method does not exist inAspire.Hosting.Azure. The only public surface isAddBicepTemplate(name, bicepFile)/AddBicepTemplateString(name, bicepContent)defined inAzureBicepResourceExtensions.cs.PrivateEndpointsample assignsSubnet = new SubnetReference { Id = "..." }—SubnetReferenceis not a real type inAzure.Provisioning.Network. In Aspire's own code (AzurePrivateEndpointExtensions.cs) theSubnet.Idproperty is set directly. The sample is also missing thePrivateLinkServiceConnectionscollection, which means the Bicep it produces would be incomplete../infradirectory inside your AppHost project". Runningaspire rundoes not populate a project-local./infra—AzureProvisioningResource.GetBicepTemplateFilewrites toDirectory.CreateTempSubdirectory("aspire"). Bicep only lands on disk in a stable location when you runaspire publish -o <path>.What doc-tester validated
microsoft/aspire:AddBicepTemplate/AddBicepTemplateString—Aspire.Hosting.Azure/AzureBicepResourceExtensions.csPrivateEndpoint.Subnet.Id+PrivateLinkServiceConnections.Add(new NetworkPrivateLinkServiceConnection { … })—Aspire.Hosting.Azure.Network/AzurePrivateEndpointExtensions.csaspire publish -o <path>emission layout —Aspire.Hosting.Azure/AzurePublishingContext.csAddPrivateEndpointfollows the doc link conventions: site-relative (/integrations/...), trailing slash on the page, and#add-private-endpointsmatches the rendered headingidon the target page.pnpm exec astro sync— passes.AddAzureBicepResource,SubnetReference) are no longer present, and the new strings (AddBicepTemplate(,NetworkPrivateLinkServiceConnection,new ProvisioningParameter,aspire publish -o ./infra) are present.How I verified
cd D:\GitHub\aspire.dev\src\frontendpnpm exec astro sync— succeeds.pnpm devand browse tohttp://localhost:<port>/integrations/cloud/azure/customize-resources/:AddPrivateEndpointlink — it should jump to the Add private endpoints heading on the Azure Virtual Network page.AddBicepTemplate(...)(notAddAzureBicepResource).aspire publish -o ./infraand notes thataspire runuses a temp directory.Out of scope (deferring to a follow-up)
The reporter listed three additional wishlist items in the issue body that are orthogonal to the inaccuracies above and would meaningfully grow the page. I've kept this PR focused on the broken/inaccurate content so it stays easy to review. Tracking these as a follow-up:
ParameterResource(or other resource expressions) through to a custom Bicep template.AddBicepTemplateresource and using them elsewhere in the AppHost.existingkeyword in a custom template.