docs: fix inaccurate Customize Azure resources page

[IEvangelist]

Fixes #246

Problem

The page at https://aspire.dev/integrations/cloud/azure/customize-resources/ contains three concrete API inaccuracies that mislead readers building custom Bicep workflows. Verified each claim against the microsoft/aspire main source tree and against the live page on aspire.dev (see Evidence below).

Changes

All edits are scoped to src/frontend/src/content/docs/integrations/cloud/azure/customize-resources.mdx plus one allowlist entry pair in src/frontend/tests/unit/twoslash-blocks-audit.ts (see Twoslash note below).

• AddBicepTemplate instead of AddAzureBicepResource in the C# Use custom Bicep files sample. AddAzureBicepResource is not a public API; the real APIs are AddBicepTemplate(name, bicepFile) and AddBicepTemplateString(name, bicepContent). The TypeScript sample was already using the correct addBicepTemplate name.
• Replaced .WithReference(storage) on the bicep resource with .WithEnvironment("STORAGE_CONNECTION_STRING", storage.GetOutput("connectionString")). AzureBicepResource does not implement IResourceWithConnectionString, so the original snippet did not compile. Showing GetOutput here also addresses one of the reporter's wishlist items (consuming outputs from a custom Bicep template).
• Rewrote Inspect generated Bicep. Running the AppHost locally (aspire run) does not write Bicep into the project — local provisioning compiles each module into a Directory.CreateTempSubdirectory("aspire") location (see AzureProvisioningResource.cs and AzureBicepResource.cs). Updated the steps to use aspire publish (or aspire deploy) and to look in the aspire-output folder (the publish/deploy default per PublishCommandStrings.resx — "Defaults to the AppHost directory's 'aspire-output' folder if not specified"). Added a note callout calling out the difference and a tip callout pointing to the Azure Portal Export template trick.
• Replaced the hallucinated SubnetReference example in Add Azure resources to the infrastructure with the idiomatic Aspire pattern using AzurePrivateEndpointExtensions.AddPrivateEndpoint (from Aspire.Hosting.Azure.Network). Added a TypeScript note that the high-level builders are C#-only today, plus a fallback paragraph pointing readers at ConfigureInfrastructure + Azure.Provisioning for advanced needs not covered by Aspire-native builders.
• New Pass parameters and read outputs subsection under Custom Bicep templates with C# and TypeScript samples for AddParameter(name, secret: true), WithParameter(name, parameterResource), and GetOutput(name). Added a bulleted list of the supported WithParameter value types (ParameterResource, BicepOutputReference, ReferenceExpression, IResourceWithConnectionString, EndpointReference) and a LearnMore link to the playground/bicep sample for end-to-end scenarios — closes the wishlist items in the issue.
• Added a tip about AddBicepTemplateString / addBicepTemplateString for inline Bicep snippets.
• See also: added the playground/bicep sample link.

Evidence

Confirmed the issue still reproduces on the live aspire.dev page today via Playwright + DOM probe:

hasAddAzureBicepResource:    true  // "Use custom Bicep files" C# tab
hasInfraDir:                 true  // "Inspect generated Bicep" steps
hasPrivateEndpointConstructor: true // "Add Azure resources to the infrastructure"
hasSubnetReference:          true  // ...same section
hasAddBicepTemplate:         false // C# tab uses the wrong name

Quoted before/after for each section:

Use custom Bicep files (C#):

- var storage = builder.AddAzureBicepResource(
-     name: "storage",
-     bicepFilePath: "./custom-storage.bicep")
+ var storage = builder.AddBicepTemplate("storage", "./custom-storage.bicep")
      .WithParameter("storageAccountName", "mystorageaccount");

  builder.AddProject<Projects.WebApp>("webapp")
-        .WithReference(storage);
+        .WithEnvironment("STORAGE_CONNECTION_STRING", storage.GetOutput("connectionString"));

Add Azure resources to the infrastructure (C#):

- storage.ConfigureInfrastructure(infra =>
- {
-     var privateEndpoint = new PrivateEndpoint("storagepe")
-     {
-         Location = "eastus",
-         Subnet = new SubnetReference
-         {
-             Id = "/subscriptions/.../subnets/mysubnet"
-         }
-     };
-     infra.Add(privateEndpoint);
- });
+ var vnet = builder.AddAzureVirtualNetwork("vnet");
+ var peSubnet = vnet.AddSubnet("pe-subnet", "10.0.1.0/24");
+
+ var storage = builder.AddAzureStorage("storage");
+ var blobs = storage.AddBlobs("blobs");
+
+ peSubnet.AddPrivateEndpoint(blobs);

Inspect generated Bicep:

- 1. Run your AppHost locally.
- 2. Open the `./infra` directory inside your AppHost project.
- 3. Review the generated `.bicep` files to verify your customizations.
+ 1. From the AppHost directory, run `aspire publish` (or `aspire deploy`).
+ 2. Open the `aspire-output` folder next to your AppHost project. To write somewhere else, pass `--output-path` to the publish or deploy command.
+ 3. Review the generated `.bicep` files to verify your customizations.

How I verified

1. Fast-forwarded microsoft/aspire.dev:main and microsoft/aspire:main, then rebased dapine/fix-customize-azure-resources-246 onto the new tip so the PR diff is exactly two files.
2. For each claim in the issue, located the implementing C# file in microsoft/aspire and the matching polyglot TypeScript usage in tests/PolyglotAppHosts/ to confirm the real API surface (signatures and call patterns).
3. Loaded https://aspire.dev/integrations/cloud/azure/customize-resources/ via Playwright and confirmed all three inaccuracies are still present today (DOM probe above).
4. Ran the repo's twoslash + lint validation against the change:
   • pnpm --dir src/frontend test:unit:twoslash-blocks — PASS (the two KNOWN_TYPE_BUGS entries cleanly cover the generator's collapsed-overload bug).
   • pnpm --dir src/frontend test:unit:llms-txt — PASS.
   • pnpm --dir src/frontend lint — PASS for the two changed files (pre-existing repo-wide warnings unrelated to this branch).

Twoslash note

The two new TypeScript twoslash blocks call withParameter(name, { value }) with a string and a ParameterResource. The polyglot test tests/PolyglotAppHosts/Aspire.Hosting.Azure/TypeScript/apphost.ts uses this exact pattern, so the runtime API supports it. However, the current aspire.d.ts generator only emits the last withParameter overload ({ value?: EndpointReference }), so twoslash reports ts(2769) — No overload matches this call. Added two KNOWN_TYPE_BUGS entries with a clear label so the regression gate stays precise; the entries fall out automatically once the generator emits all overloads (separate, pre-existing concern in scripts/generate-twoslash-types.ts).

Out of scope

• The deeper type-shape gap in the twoslash type generator — only the last overload of withParameter is emitted to aspire.d.ts. Worth a follow-up issue against scripts/generate-twoslash-types.ts, but outside the scope of this docs fix.
• A dedicated walkthrough of the existing Bicep keyword (one of the reporter's wishlist items) — the LearnMore here points readers at the playground/bicep sample, and a full guide can land as a follow-up.

[Copilot]

Pull request overview

Updates the “Customize Azure resources” documentation to correct several Aspire Azure API inaccuracies and improve guidance for custom Bicep workflows.

Changes:

• Corrects the custom Bicep template samples to use the public AddBicepTemplate API and demonstrates consuming Bicep outputs via GetOutput.
• Replaces the fabricated private endpoint example with Aspire’s AddPrivateEndpoint builder pattern and clarifies how to inspect generated Bicep via aspire publish/deploy.
• Adds TypeScript twoslash allowlist entries for a known withParameter overload-emission issue in the generated aspire.d.ts.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/frontend/src/content/docs/integrations/cloud/azure/customize-resources.mdx	Fixes incorrect APIs/examples and expands docs with output/parameter patterns and correct Bicep inspection steps.
src/frontend/tests/unit/twoslash-blocks-audit.ts	Adds allowlist entries for known twoslash type errors related to withParameter overload generation.

---

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

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #946. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.