Skip to content

Commit badd130

Browse files
IEvangelistIEvangelist
committed
Breaking changes for .NET Aspire 9.2 (dotnet#2892)
* Added breaking changes for 9.2, fixes dotnet#2888 and fixes dotnet#2889 * Correct TOC * Add clarifying type name * Fixes dotnet#2899 * Added new breaking changes docs * Remove link * Correct MD lint error/warnings
1 parent 37772e8 commit badd130

File tree

10 files changed

+374
-1
lines changed

10 files changed

+374
-1
lines changed

‎docs/compatibility/9.2/generated-bicep-updates.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: "Breaking change - Role Assignments separated from Azure resource bicep"
3+
description: "Learn about the breaking change in .NET Aspire 9.2 where role assignments are moved to separate bicep modules."
4+
ms.date: 4/2/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs-aspire/issues/2911
7+
---
8+
9+
# Role Assignments separated from Azure resource bicep
10+
11+
In .NET Aspire 9.2, role assignments for Azure resources are no longer included in the same bicep file as the resource. Instead, they're moved to separate bicep modules. This change affects how role assignments are customized during infrastructure configuration.
12+
13+
## Version introduced
14+
15+
.NET Aspire 9.2
16+
17+
## Previous behavior
18+
19+
Previously, when an Azure resource's bicep file was generated, default role assignments were included in the same bicep module as the resource. This allowed customization of role assignments in the `ConfigureInfrastructure` callback. For example:
20+
21+
```csharp
22+
var storage = builder.AddAzureStorage("storage")
23+
.ConfigureInfrastructure(infra =>
24+
{
25+
var roles = infra.GetProvisionableResources().OfType<RoleAssignment>().ToList();
26+
27+
foreach (var role in roles)
28+
{
29+
infra.Remove(role);
30+
}
31+
32+
var storageAccount = infra.GetProvisionableResources().OfType<StorageAccount>().Single();
33+
infra.Add(storageAccount.CreateRoleAssignment(StorageBuiltInRole.StorageBlobDataContributor, ...));
34+
});
35+
```
36+
37+
## New behavior
38+
39+
Role assignments are now moved to their own bicep modules. The `ConfigureInfrastructure` callback no longer contains any `RoleAssignment` instances. Instead, role assignments are configured using the `WithRoleAssignments` API. For example:
40+
41+
```csharp
42+
var storage = builder.AddAzureStorage("storage");
43+
44+
builder.AddProject<Projects.AzureContainerApps_ApiService>("api")
45+
.WithRoleAssignments(storage, StorageBuiltInRole.StorageBlobDataContributor);
46+
```
47+
48+
## Type of breaking change
49+
50+
This is a [behavioral change](../categories.md#behavioral-change).
51+
52+
## Reason for change
53+
54+
This change was necessary to implement the `WithRoleAssignments` APIs, which provide a more structured and flexible way to configure role assignments per application.
55+
56+
## Recommended action
57+
58+
To customize role assignments in .NET Aspire 9.2, use the `WithRoleAssignments` API instead of relying on the `ConfigureInfrastructure` callback. Update your code as shown in the [preceding example](#new-behavior).
59+
60+
## Affected APIs
61+
62+
- <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.ConfigureInfrastructure``1(Aspire.Hosting.ApplicationModel.IResourceBuilder{``0},System.Action{Aspire.Hosting.Azure.AzureResourceInfrastructure})>

‎docs/compatibility/9.2/index.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: Breaking changes in .NET Aspire 9.2
3+
titleSuffix: ""
4+
description: Navigate to the breaking changes in .NET Aspire 9.2.
5+
ms.date: 04/02/2025
6+
---
7+
8+
# Breaking changes in .NET Aspire 9.2
9+
10+
If you're migrating an app to .NET Aspire 9.2, the breaking changes listed here might affect you.
11+
12+
[!INCLUDE [binary-source-behavioral](../includes/binary-source-behavioral.md)]
13+
14+
> [!NOTE]
15+
> This article is a work in progress. It's not a complete list of breaking changes in .NET Aspire 9.2.
16+
17+
## Breaking changes
18+
19+
| Title | Type of change | Introduced version |
20+
|--|--|--|
21+
| [AzureContainerApps infrastructure creates managed identity per container app](managed-identity-per-app.md) | Behavioral change | 9.2 |
22+
| [KeyVault default role assignment changing from KeyVaultAdministrator to KeyVaultSecretsUser](keyvault-role-assignment-changes.md) | Behavioral change | 9.2 |
23+
| [Role Assignments separated from Azure resource bicep](generated-bicep-updates.md) | Behavioral change | 9.2 |
24+
| [With authentication API creates keyvault resource in the app model](withauthentication-changes.md) | Behavioral change | 9.2 |
25+
| [WithCommand obsolete and new overload with CommandOptions](withcommand-obsolete.md) | Source incompatible | 9.2 |

‎docs/compatibility/9.2/keyvault-role-assignment-changes.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: "Breaking change - KeyVault default role assignment changing from KeyVaultAdministrator to KeyVaultSecretsUser"
3+
description: "Learn about the breaking change in .NET Aspire 9.2 where the default role for Azure KeyVault applications changes to KeyVaultSecretsUser."
4+
ms.date: 03/27/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs-aspire/issues/2899
7+
---
8+
9+
# KeyVault default role assignment changing from KeyVaultAdministrator to KeyVaultSecretsUser
10+
11+
In .NET Aspire 9.2, the default role assigned to applications referencing Azure KeyVault has changed from <xref:Azure.Provisioning.KeyVault.KeyVaultBuiltInRole.KeyVaultAdministrator> to <xref:Azure.Provisioning.KeyVault.KeyVaultBuiltInRole.KeyVaultSecretsUser>. This change enhances security by limiting default privileges to only reading secrets. Applications requiring higher privileges must explicitly configure them.
12+
13+
## Version introduced
14+
15+
.NET Aspire 9.2
16+
17+
## Previous behavior
18+
19+
Previously, applications referencing Azure KeyVault were automatically granted the `KeyVaultAdministrator` role, which allowed full management of KeyVault settings.
20+
21+
## New behavior
22+
23+
Applications referencing Azure KeyVault are now granted the `KeyVaultSecretsUser` role by default, which restricts access to reading secrets. If higher privileges are required, they can be configured using the `WithRoleAssignments` API.
24+
25+
Example:
26+
27+
```csharp
28+
using Azure.Provisioning.KeyVault;
29+
30+
var kv = builder.AddAzureKeyVault("kv");
31+
32+
builder.AddProject<Projects.ApiService>("api")
33+
.WithRoleAssignments(kv, KeyVaultBuiltInRole.KeyVaultContributor);
34+
```
35+
36+
## Type of breaking change
37+
38+
This is a [behavioral change](../categories.md#behavioral-change).
39+
40+
## Reason for change
41+
42+
The `KeyVaultAdministrator` role provides excessive privileges for most applications, as they typically only need to read secrets. Assigning the `KeyVaultSecretsUser` role by default improves security by adhering to the principle of least privilege.
43+
44+
## Recommended action
45+
46+
If your application requires higher privileges than the `KeyVaultSecretsUser` role, explicitly configure the necessary roles using the `WithRoleAssignments` API. For example:
47+
48+
```csharp
49+
using Azure.Provisioning.KeyVault;
50+
51+
var kv = builder.AddAzureKeyVault("kv");
52+
53+
builder.AddProject<Projects.ApiService>("api")
54+
.WithRoleAssignments(kv, KeyVaultBuiltInRole.KeyVaultContributor);
55+
```
56+
57+
## Affected APIs
58+
59+
- <xref:Aspire.Hosting.AzureKeyVaultResourceExtensions.AddAzureKeyVault*>

‎docs/compatibility/9.2/managed-identity-per-app.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: "Breaking change - AzureContainerApps infrastructure creates managed identity per container app"
3+
description: "Learn about the breaking change in .NET Aspire 9.2 where each ContainerApp now has its own managed identity."
4+
ms.date: 4/2/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs-aspire/issues/2914
7+
---
8+
9+
# Azure Container Apps managed identity changes
10+
11+
Starting with .NET Aspire 9.2, each Azure Container App created using [📦 Aspire.Hosting.Azure.AppContainers](https://www.nuget.org/packages/Aspire.Hosting.Azure.AppContainers) NuGet package now has its own Azure Managed Identity. This change enables more granular role assignments for Azure resources but might require updates to applications that rely on shared managed identities.
12+
13+
## Version introduced
14+
15+
.NET Aspire 9.2
16+
17+
## Previous behavior
18+
19+
All ContainerApps shared a single Azure Managed Identity. This allowed applications to interact with Azure resources using a common identity.
20+
21+
## New behavior
22+
23+
Each ContainerApp now has its own unique Azure Managed Identity. This enables applications to have distinct role assignments for different Azure resources.
24+
25+
## Type of breaking change
26+
27+
This is a [behavioral change](../categories.md#behavioral-change).
28+
29+
## Reason for change
30+
31+
This change was introduced to support scenarios where applications require different role assignments for different Azure resources. By assigning a unique managed identity to each ContainerApp, applications can now operate with more granular access control.
32+
33+
## Recommended action
34+
35+
The recommended action is to update your Azure resources to use the new managed identities. This may include:
36+
37+
### Azure SQL Server
38+
39+
Grant access to all Azure Managed Identities that need to interact with the database. Follow the guidance in [Configure and manage Azure AD authentication with Azure SQL](/azure/azure-sql/database/authentication-aad-configure).
40+
41+
### Azure PostgreSQL
42+
43+
Grant necessary privileges to all Azure Managed Identities that need to interact with the database. Use the PostgreSQL documentation on [granting privileges](https://www.postgresql.org/docs/current/ddl-priv.html) as a reference. For example:
44+
45+
```sql
46+
GRANT INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO <managed_identity_user>;
47+
```
48+
49+
## Affected APIs
50+
51+
- `Aspire.Hosting.AzureContainerAppExtensions.AddAzureContainerAppsInfrastructure`
52+
- `Aspire.Hosting.AzureContainerAppProjectExtensions.PublishAsAzureContainerApp`
53+
- `Aspire.Hosting.AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp`
54+
- `Aspire.Hosting.AzureContainerAppContainerExtensions.PublishAsAzureContainerApp`

‎docs/compatibility/9.2/withauthentication-changes.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: "Breaking change - WithAccessKeyAuthentication and WithPasswordAuthentication create a keyvault resource in the app model"
3+
description: "Learn about the breaking change in .NET Aspire 9.2 where key vault resources are now created or referenced directly in the app model."
4+
ms.date: 3/25/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs-aspire/issues/2889
7+
---
8+
9+
# With authentication API creates keyvault resource in the app model
10+
11+
Starting in .NET Aspire 9.2, calling any of the following methods:
12+
13+
- <xref:Aspire.Hosting.AzureRedisExtensions.WithAccessKeyAuthentication*?displayProperty=nameWithType>
14+
- <xref:Aspire.Hosting.AzureCosmosExtensions.WithAccessKeyAuthentication*?displayProperty=nameWithType>
15+
- <xref:Aspire.Hosting.AzurePostgresExtensions.WithPasswordAuthentication*?displayProperty=nameWithType>
16+
17+
Will now create (or add references to) a key vault resource directly in the app model. This change allows better customization and management of connection strings and secrets.
18+
19+
## Version introduced
20+
21+
.NET Aspire 9.2
22+
23+
## Previous behavior
24+
25+
Previously, calling `WithAccessKeyAuthentication` on CosmosDB or AzureRedis, or `WithPasswordAuthentication` on AzurePostgres, automatically created and managed Bicep resources. These resources were invisible to the app model and could not be managed or customized in C#.
26+
27+
## New behavior
28+
29+
In .NET Aspire 9.2, calling `WithAccessKeyAuthentication` or `WithPasswordAuthentication` adds an empty `keyVaultName` parameter as a known parameter in the Bicep file. The app model now directly creates the key vault resource or allows you to pass a reference to an existing AzureKeyVault resource where secrets will be stored. Key vault secret names for connection strings are now formatted as `connectionstrings--{resourcename}` to avoid conflicts with other connection strings.
30+
31+
## Type of breaking change
32+
33+
This is a [behavioral change](../categories.md#behavioral-change).
34+
35+
## Reason for change
36+
37+
This change moves resource management to the app host, making it easier to customize and manage resources. It allows sharing a key vault across multiple resources or using an existing key vault to manage connection strings and secrets.
38+
39+
## Recommended action
40+
41+
There is currently no workaround for this change. Ensure that your app model is updated to handle the new behavior for key vault resources and connection string management.
42+
43+
## Affected APIs
44+
45+
- <xref:Aspire.Hosting.AzureRedisExtensions.WithAccessKeyAuthentication*?displayProperty=nameWithType>
46+
- <xref:Aspire.Hosting.AzureCosmosExtensions.WithAccessKeyAuthentication*?displayProperty=nameWithType>
47+
- <xref:Aspire.Hosting.AzurePostgresExtensions.WithPasswordAuthentication*?displayProperty=nameWithType>

‎docs/compatibility/9.2/withcommand-obsolete.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: "Breaking change - WithCommand obsolete and new overload with CommandOptions"
3+
description: "Learn about the breaking change in .NET Aspire 9.2 where the WithCommand method overload with optional parameters is marked obsolete."
4+
ms.date: 3/25/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs-aspire/issues/2888
7+
---
8+
9+
# WithCommand obsolete and new overload with CommandOptions
10+
11+
The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithCommand*> method overload that accepted multiple optional parameters is now marked obsolete. A new overload that accepts an instance of `CommandOptions` has been introduced. This change requires updates to existing code to use the new overload.
12+
13+
## Version introduced
14+
15+
.NET Aspire 9.2
16+
17+
## Previous behavior
18+
19+
The `WithCommand` method overload that accepted multiple optional parameters was available and not marked as obsolete.
20+
21+
```csharp
22+
var builder = DistributedApplication.CreateBuilder(args);
23+
24+
builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
25+
.WithCommand(
26+
name: "command-name",
27+
displayName: "Command display name",
28+
executeCommand: async (ExecuteCommandContext context) =>
29+
{
30+
// Command execution logic here
31+
await Task.CompletedTask;
32+
return CommandResults.Success();
33+
},
34+
updateState: (UpdateCommandStateContext context) =>
35+
{
36+
// State update logic here
37+
return ResourceCommandState.Enabled;
38+
},
39+
displayDescription: "Command Description",
40+
parameter: new[] { "", "" },
41+
confirmationMessage: "Are you sure?",
42+
iconName: "Icons",
43+
iconVariant: "Red",
44+
isHighlighted: false);
45+
```
46+
47+
## New behavior
48+
49+
The existing <xref:Aspire.Hosting.ResourceBuilderExtensions.WithCommand*> method overload is now marked obsolete. A new overload that accepts an instance of `CommandOptions` should be used instead.
50+
51+
```csharp
52+
var builder = DistributedApplication.CreateBuilder(args);
53+
54+
builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
55+
.WithCommand(
56+
name: "command-name",
57+
displayName: "Command display name",
58+
executeCommand: async (ExecuteCommandContext context) =>
59+
{
60+
// Command execution logic here
61+
await Task.CompletedTask;
62+
return CommandResults.Success();
63+
},
64+
commandOptions: new CommandOptions
65+
{
66+
UpdateState = (UpdateCommandStateContext context) =>
67+
{
68+
// State update logic here
69+
return ResourceCommandState.Enabled;
70+
},
71+
Description = "Command Description",
72+
Parameter = new[] { "", "" },
73+
ConfirmationMessage = "Are you sure?",
74+
IconName = "Icons",
75+
IconVariant = "Red",
76+
IsHighlighted = false
77+
});
78+
```
79+
80+
The only required parameters are the `name`, `displayName`, and `executeCommand`. The rest of the parameters are now encapsulated within the `CommandOptions` object, which provides a cleaner and more maintainable API.
81+
82+
## Type of breaking change
83+
84+
This is a [source incompatible](../categories.md#source-compatibility) change.
85+
86+
## Reason for change
87+
88+
This change was made following an API review to improve clarity and maintainability by consolidating optional parameters into a single `CommandOptions` object.
89+
90+
## Recommended action
91+
92+
Update your code to use the new `WithCommand` overload that accepts an instance of `CommandOptions`. Replace calls to the obsolete overload with the new overload.
93+
94+
## Affected APIs
95+
96+
- <xref:Aspire.Hosting.ResourceBuilderExtensions.WithCommand*>

‎docs/compatibility/api-removal.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,7 @@ ms.date: 10/24/2024
1414
- By documenting it under [Breaking changes in .NET](breaking-changes.md).
1515

1616
In most cases, an API that shipped in a long-term support (LTS) release is obsoleted in the subsequent LTS release before it's removed. In rare cases, based on business needs, exceptions are made to obsolete an API before the subsequent LTS release. All obsoletions are documented and communicated to customers.
17+
18+
## See also
19+
20+
- [.NET Aspire Support Policy](https://dotnet.microsoft.com/platform/support/policy/aspire)

‎docs/compatibility/breaking-changes.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,5 @@ You can also view individual issues that detail the breaking changes introduced
2020
## See also
2121

2222
- [API removal in .NET](api-removal.md)
23+
- [.NET Aspire Support Policy](https://dotnet.microsoft.com/platform/support/policy/aspire)
2324
- [.NET runtime compatibility](/dotnet/core/versions/#net-runtime-compatibility)

‎docs/compatibility/categories.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,3 +56,7 @@ Forward compatibility refers to the ability of an existing consumer of an API to
5656
Maintaining forward compatibility virtually precludes any changes or additions from version to version, since those changes prevent a consumer that targets a later version from running under an earlier version. Developers expect that a consumer that relies on a newer API may not function correctly against the older API.
5757

5858
Maintaining forward compatibility is not a goal of .NET Aspire.
59+
60+
## See also
61+
62+
- [.NET Aspire Support Policy](https://dotnet.microsoft.com/platform/support/policy/aspire)

0 commit comments

Comments
 (0)