From baebc639c80b3f8a34b9688b60d34af0a62853f6 Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 14 May 2026 00:36:53 -0500 Subject: [PATCH] docs: fix inaccurate APIs and workflow in Customize Azure resources MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Customize Azure resources page had three concrete inaccuracies that broke copy-paste use of the snippets: - The custom Bicep example called `AddAzureBicepResource(name:..., bicepFilePath:...)`, which doesn't exist. Replace it with the real `AddBicepTemplate("storage", "./custom-storage.bicep")` API. - The `PrivateEndpoint` snippet used a fictional `SubnetReference` type and omitted the required `PrivateLinkServiceConnections`. Fix it to match the actual `Azure.Provisioning.Network` pattern used by `AddPrivateEndpoint`, and add an aside pointing readers at that first-class extension as the recommended path. - "Open the ./infra directory" is wrong — Bicep is emitted only at publish time. Replace the steps with `aspire publish -o ./publish` and accurately describe the emitted `main.bicep` and `.module.bicep` files. Also adds a "Bicep samples in the dotnet/aspire repo" link to the See also list (explicitly requested by the reporter). Verified: - pnpm build (Astro + Starlight) passes, starlight-links-validator reports all internal links valid. - pnpm test:unit: 163/163 pass, including twoslash-blocks tests. - Live preview confirms rendered HTML contains AddBicepTemplate, the AddPrivateEndpoint aside, `aspire publish -o ./publish`, and the Bicep samples link, with no remaining AddAzureBicepResource. Fixes #246 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../cloud/azure/customize-resources.mdx | 40 ++++++++++++------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/customize-resources.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/customize-resources.mdx index 8f408f284..c5041f85e 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/customize-resources.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/customize-resources.mdx @@ -388,22 +388,31 @@ servicebus.ConfigureInfrastructure(infra => ### Add Azure resources to the infrastructure -You can inject additional Azure constructs (for example, a private endpoint) into an integration's generated infrastructure: +You can inject additional Azure constructs into an integration's generated infrastructure when no first-class Aspire API exists for them. Call `infra.Add(...)` inside `ConfigureInfrastructure` with any strongly-typed [Azure.Provisioning](https://learn.microsoft.com/dotnet/api/overview/azure/provisioning) construct. + + + +The following example shows the lower-level pattern using `infra.Add(...)` with a strongly-typed [`PrivateEndpoint`](https://learn.microsoft.com/dotnet/api/azure.provisioning.network.privateendpoint) construct from `Azure.Provisioning.Network`: ```csharp title="C# — AppHost.cs" +using Azure.Provisioning.Network; + storage.ConfigureInfrastructure(infra => { - var privateEndpoint = new PrivateEndpoint("storagepe") - { - Location = "eastus", - Subnet = new SubnetReference + var privateEndpoint = new PrivateEndpoint("storagepe"); + privateEndpoint.Subnet.Id = "/subscriptions/.../subnets/mysubnet"; + privateEndpoint.PrivateLinkServiceConnections.Add( + new NetworkPrivateLinkServiceConnection { - Id = "/subscriptions/.../subnets/mysubnet" - } - }; + Name = "storage-connection", + PrivateLinkServiceId = "/subscriptions/.../storageAccounts/mystorage", + GroupIds = ["blob"] + }); infra.Add(privateEndpoint); }); @@ -520,9 +529,7 @@ Reference it from the AppHost: ```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var storage = builder.AddAzureBicepResource( - name: "storage", - bicepFilePath: "./custom-storage.bicep") +var storage = builder.AddBicepTemplate("storage", "./custom-storage.bicep") .WithParameter("storageAccountName", "mystorageaccount"); builder.AddProject("webapp") @@ -554,11 +561,13 @@ await builder.build().run(); ### Inspect generated Bicep -After customizing with `ConfigureInfrastructure`, inspect the Bicep that Aspire generates: +To inspect the Bicep that Aspire generates from your customizations, publish the AppHost to a directory and review the emitted files: + +```bash title="Terminal" +aspire publish -o ./publish +``` -1. Run your AppHost locally. -2. Open the `./infra` directory inside your AppHost project. -3. Review the generated `.bicep` files to verify your customizations. +Aspire writes a `main.bicep` for the deployment, plus a `.module.bicep` file per Azure resource, into the output directory you specify. Open each `.module.bicep` to verify that your `ConfigureInfrastructure` changes were applied.