docs: fix inaccurate Customize Azure resources page

[David Pine (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.

[Adam Ratzman (adamint)]

Two things need fixing before this merges: the existing TypeScript private-endpoint thread is still valid, and aspire deploy does not write Bicep to aspire-output — only the publish step does. I also left a smaller note on the undefined custom-sql.bicep sample.

I verified the generator is deterministic, the targeted twoslash tests pass, the two new snippets fail against the old declarations and compile against this head, and the built page renders without twoslash or browser errors.

[aspire-repo-bot]

Automated wording suggestions from the forbidden-words check. Apply the suggestions to resolve them.

[aspire-repo-bot]

Use "Aspire" instead of ".NET Aspire".

Suggested change

	// character, so longer tokens like `ASP.NET Aspire` or `.NET AspireX` stay intact
	// character, so longer tokens like `ASPAspire` or `AspireX` stay intact

[aspire-repo-bot]

Use "Aspire" instead of ".NET Aspire".

Suggested change

	// README content (e.g. `a **.NET Aspire**`, `a [.NET Aspire](url)`, or
	// README content (e.g. `a **Aspire**`, `a [Aspire](url)`, or

[aspire-repo-bot]

Use "Aspire" instead of ".NET Aspire".

Suggested change

	// `a _.NET Aspire_`), so the article corrector consumes them to stay grammatical
	// `a _Aspire_`), so the article corrector consumes them to stay grammatical

[aspire-repo-bot]

Use "Aspire" instead of "dotnet aspire".

Suggested change

	// commands like `dotnet aspire run` are never rewritten into an unrunnable
	// commands like `Aspire run` are never rewritten into an unrunnable

[aspire-repo-bot]

Use "Aspire" instead of ".NET Aspire".

Suggested change

	* token like `ASP.NET Aspire` or `.NET AspireX`.
	* token like `ASPAspire` or `AspireX`.

[aspire-repo-bot]

Use "Aspire" instead of ".NET Aspire".

Suggested change

	* is corrected (e.g. `a .NET Aspire` -> `an Aspire`).
	* is corrected (e.g. `a Aspire` -> `an Aspire`).

[aspire-repo-bot]

Use "Aspire" instead of "dotnet aspire".

Suggested change

	])('normalizes the "dotnet aspire" spelling (%s)', (_scenario, input, expected) => {
	])('normalizes the "Aspire" spelling (%s)', (_scenario, input, expected) => {

[aspire-repo-bot]

Use "Aspire" instead of "dotnet aspire".

Suggested change

	'Build an Aspire app, then run `dotnet aspire run`.'
	'Build an Aspire app, then run `Aspire run`.'