docs: fix inaccurate APIs and workflow in Customize Azure resources

[David Pine (IEvangelist)]

Fixes#246

Problem

The Customize Azure resources page contains three concrete inaccuracies, each verified against the dotnet/aspire source and the live aspire.dev site:

1. Non-existent API: The custom Bicep example used builder.AddAzureBicepResource(name: ..., bicepFilePath: ...), which doesn't exist on IDistributedApplicationBuilder. The real API is AddBicepTemplate(name, bicepFile).
2. Invalid PrivateEndpoint snippet: The "Add Azure resources to the infrastructure" example used Subnet = new SubnetReference { Id = ... } (no such type) and omitted PrivateLinkServiceConnections, which is mandatory. The correct pattern (per AzurePrivateEndpointExtensions.cs#L122-L138) is pe.Subnet.Id = "..."; pe.PrivateLinkServiceConnections.Add(new NetworkPrivateLinkServiceConnection { ... }). Also, Aspire ships a first-class AddPrivateEndpoint extension that should be the recommended path for this scenario.
3. Wrong inspection workflow: "Open the ./infra directory inside your AppHost project" is incorrect. Aspire emits Bicep only at publish time via aspire publish -o <dir>, producing a main.bicep plus one <resource-name>.module.bicep per Azure resource. No ./infra/ folder is created at run time.

Changes

• PrivateEndpoint example (### Add Azure resources to the infrastructure):
  • Added using Azure.Provisioning.Network; to the snippet.
  • Fixed the Subnet assignment to use privateEndpoint.Subnet.Id = "...".
  • Added the required PrivateLinkServiceConnections.Add(new NetworkPrivateLinkServiceConnection { Name, PrivateLinkServiceId, GroupIds }) call.
  • Added an <Aside type="tip"> pointing readers at the first-class AddPrivateEndpoint extension from Aspire.Hosting.Azure.Network as the recommended path.
• Custom Bicep C# example (### Use custom Bicep files):
  • Replaced AddAzureBicepResource(name: ..., bicepFilePath: ...) with the real API AddBicepTemplate("storage", "./custom-storage.bicep").
• Inspect generated Bicep (### Inspect generated Bicep):
  • Replaced the "Open ./infra" steps with the actual workflow: aspire publish -o ./publish, then inspect the emitted main.bicep and <resource-name>.module.bicep files.
• See also:
  • Added a link to the Bicep samples in the dotnet/aspire repo (explicitly requested by the reporter).

Evidence

Before (captured from https://aspire.dev/integrations/cloud/azure/customize-resources/):

1. Run your AppHost locally.
2. Open the ./infra directory inside your AppHost project.
3. Review the generated .bicep files to verify your customizations.

varstorage=builder.AddAzureBicepResource(name:"storage",bicepFilePath:"./custom-storage.bicep")

varprivateEndpoint=newPrivateEndpoint("storagepe"){Location="eastus",Subnet=newSubnetReference{Id="..."}};

After (this PR; verified via local pnpm preview against the rendered HTML):

• Custom Bicep example renders builder.AddBicepTemplate("storage", "./custom-storage.bicep").
• PrivateEndpoint snippet uses the correct Subnet.Id / PrivateLinkServiceConnections.Add(...) pattern and an Aside points to AddPrivateEndpoint.
• Inspect section renders a Terminal codeblock with aspire publish -o ./publish.
• "See also" includes the Bicep samples link.

How I verified

1. Cross-checked every claim against the product source (dotnet/aspire):
   • AddBicepTemplate/AddBicepTemplateString signatures from src/Aspire.Hosting.Azure/AzureBicepResourceExtensions.cs.
   • PrivateEndpoint usage pattern from src/Aspire.Hosting.Azure.Network/AzurePrivateEndpointExtensions.cs#L122-L138.
   • Emitted Bicep filenames from src/Aspire.Hosting.Azure/AzurePublishingContext.cs and the real artifacts in playground/bicep/BicepSample.AppHost/*.module.bicep.
2. Reproduced all three issues on the live site via Playwright before editing.
3. Validated the edit locally:
   • pnpm build (full Astro + Starlight build, 12,226 pages) — passed; starlight-links-validator: All internal links are valid.
   • pnpm test:unit — 163/163 tests passed, including twoslash-blocks.vitest.test.ts.
   • pnpm preview + grep over rendered HTML confirms all four changes (AddBicepTemplate, AddPrivateEndpoint aside, aspire publish -o ./publish, Bicep samples link) are present in the final output, with no remaining occurrences of AddAzureBicepResource.
4. Anchor #add-private-endpoints on azure-virtual-network was confirmed to resolve by the build's link validator.

Out of scope (follow-up candidates)

The reporter also mentioned that the page is "lacking" coverage of customizing parameters/outputs and adding existing resources. That's a content addition rather than a correctness fix, so it's not included here — happy to file a follow-up issue if useful.

[Copilot]

Pull request overview

Fixes three concrete inaccuracies on the "Customize Azure resources" docs page: a nonexistent AddAzureBicepResource API, an invalid PrivateEndpoint snippet, and an incorrect "open ./infra" inspection workflow. Also adds a pointer to the first-class AddPrivateEndpoint extension and a link to upstream Bicep samples.

Changes:

• Rewrite the PrivateEndpoint example to use Subnet.Id + PrivateLinkServiceConnections.Add(...) and add an Aside recommending AddPrivateEndpoint.
• Replace AddAzureBicepResource(name:, bicepFilePath:) with the real AddBicepTemplate("storage", "./custom-storage.bicep") API.
• Replace the "Open ./infra" workflow with aspire publish -o ./publish and add a link to the dotnet/aspire Bicep samples.

---

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

[Adam Ratzman (adamint)]

#946 is the newer, more complete fix for issue #246 and is already under review. I think this PR should close as superseded rather than be updated; this branch also conflicts and has correctness problems that the newer PR avoids.

[Adam Ratzman (adamint)]

These properties are BicepValue<ResourceIdentifier>; bare strings don't compile. #942's resource/parameter shape is closer to the product code, so I think this is another reason to consolidate there.

[Adam Ratzman (adamint)]

Changing this to AddBicepTemplate still leaves the unchanged webapp.WithReference(storage) below with no matching overload. Could we use GetOutput("connectionString") with WithEnvironment, and compile the complete sample?

[Adam Ratzman (adamint)]

This is the intermediate filename, not the published layout. aspire publish writes each module to <resource-name>/<resource-name>.bicep; could we use that path instead?