Skip to content

[docs] Document AzureBicepResourceScope.CreateForSubscription/CreateForTenant #1451

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aspire-repo-bot wants to merge 3 commits into
base: release/13.5
Choose a base branch
from
+57 −0
Open

[docs] Document AzureBicepResourceScope.CreateForSubscription/CreateForTenant #1451

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
059f8f1
docs: document AzureBicepResourceScope.CreateForSubscription/CreateFo…
aspire-repo-bot[bot] Aug 7, 2026
9ec0e8c
docs: clarify TypeScript support for Azure Bicep deployment scope
Copilot Aug 7, 2026
2a00c63
Merge release/13.5 and address review feedback
IEvangelist Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions src/frontend/src/content/docs/integrations/cloud/azure/customize-resources.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -642,6 +642,63 @@ await builder.build().run();
For more end-to-end examples — including chaining outputs between Bicep resources and using the `existing` Bicep keyword to reference resources that Aspire didn't provision — see the [Aspire `playground/bicep` sample](https://github.com/dotnet/aspire/tree/main/playground/bicep).
</LearnMore>

### Set the deployment scope

By default, Aspire deploys Bicep resources at the resource group scope. Some Bicep templates require a different [deployment scope](https://learn.microsoft.com/azure/azure-resource-manager/bicep/deploy-to-subscription), such as the subscription or the tenant.

@adamint Adam Ratzman (adamint) Aug 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we call out the lifecycle and permission change here? These scopes can create resources outside the AppHost resource group and require broader RBAC. The normal destroy path deletes the tracked resource group, so subscription- or tenant-level resources may remain.


<Tabs syncKey="aspire-lang">
<TabItem id="csharp" label="C#">

Set the `Scope` property on the Bicep resource using `AzureBicepResourceScope.CreateForSubscription` or `AzureBicepResourceScope.CreateForTenant`:

```csharp title="AppHost.cs"
Comment thread
IEvangelist marked this conversation as resolved.
using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

var subscriptionId = builder.AddParameter("subscriptionId");

var subscriptionScoped = builder.AddBicepTemplateString(
"subscriptionScoped",
"""
targetScope = 'subscription'

param location string

output value string = 'subscription'
""");
subscriptionScoped.Resource.Scope = AzureBicepResourceScope.CreateForSubscription(subscriptionId.Resource);

@IEvangelist David Pine (IEvangelist) Aug 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This block is not compilable as shown. AzureBicepResourceScope is declared in Aspire.Hosting.Azure, while the AppHost SDK injects global usings only for Aspire.Hosting and Aspire.Hosting.ApplicationModel (source). A clean 13.5 staging AppHost fails here with CS0103. Please add using Aspire.Hosting.Azure; at the start of the block, or fully qualify the type.

@IEvangelist David Pine (IEvangelist) Aug 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 2a00c63 — added using Aspire.Hosting.Azure; at the top of the C# block so it compiles against a clean 13.5 AppHost, and the note now calls out the required directive explicitly.


var tenantScoped = builder.AddBicepTemplateString(
"tenantScoped",
"""
targetScope = 'tenant'

param location string

output value string = 'tenant'
""");
tenantScoped.Resource.Scope = AzureBicepResourceScope.CreateForTenant();

builder.Build().Run();
```

<Aside type="note">
`AzureBicepResourceScope.CreateForSubscription` and `AzureBicepResourceScope.CreateForTenant` are available in Aspire 13.5 and later, and require a `using Aspire.Hosting.Azure;` directive. `targetScope` in the Bicep template must match the scope you assign in C#. `CreateForSubscription` requires a subscription identifier; `CreateForTenant` targets the current tenant and takes no arguments.

Keep the `param location string` declaration in each template. `location` is a well-known Aspire parameter that the provisioner fills in automatically from the environment's location and passes to every Bicep deployment — including subscription- and tenant-scoped ones — so the template must declare it to accept the value.
</Aside>

</TabItem>
<TabItem id="typescript" label="TypeScript">

<Aside type="note">
`AzureBicepResourceScope` and `Resource.Scope` are not currently exposed in the TypeScript AppHost APIs, so subscription/tenant deployment scopes for Bicep resources are currently C# only.
</Aside>

</TabItem>
</Tabs>

### Inspect generated Bicep

To see the Bicep that Aspire emits after applying your `ConfigureInfrastructure` callbacks, publish the AppHost and read the files from the output folder:
Expand Down
Loading