Skip to content

Commit 93ff3d3

Browse files
IEvangelistIEvangelist
committed
Fixes #3930 
1 parent 33ca133 commit 93ff3d3

File tree

3 files changed

+118
-3
lines changed

3 files changed

+118
-3
lines changed

‎docs/compatibility/9.4/azure-storage-apis-renamed.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: "Breaking change - Azure Storage APIs renamed and refactored"
3+
description: "Learn about the breaking changes in .NET Aspire 9.4 where Azure Storage APIs were renamed and refactored for clarity and consistency."
4+
ms.date: 07/08/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs-aspire/issues/3930
7+
---
8+
9+
# Azure Storage APIs renamed and refactored
10+
11+
In .NET Aspire 9.4, several Azure Storage APIs were renamed and refactored for clarity and consistency. These changes affect how you add and configure Azure Blob, Queue, and Table storage resources and clients in your Aspire applications. The new API names better align with Azure resource naming and reduce confusion.
12+
13+
## Version introduced
14+
15+
.NET Aspire 9.4
16+
17+
## Previous behavior
18+
19+
Previously, you used methods like `AddBlobs`, `AddBlobContainer`, `AddQueues`, and `AddTables` to add Azure Storage resources.
20+
21+
**Hosting integration example:**
22+
23+
```csharp
24+
var builder = DistributedApplication.CreateBuilder(args);
25+
26+
var storage = builder.AddAzureStorage("storage");
27+
28+
var blobs = storage.AddBlobs("blobs");
29+
var blobContainer = blobs.AddBlobContainer("container");
30+
31+
var queues = storage.AddQueues("queues");
32+
var tables = storage.AddTables("tables");
33+
```
34+
35+
Client registration methods also used names like `AddAzureBlobClient`, `AddAzureQueueClient`, and `AddAzureTableClient`.
36+
37+
**Client integration example:**
38+
39+
```csharp
40+
var builder = WebApplication.CreateBuilder(args);
41+
42+
builder.AddAzureBlobClient("storage");
43+
builder.AddAzureQueueClient("storage");
44+
builder.AddAzureTableClient("storage");
45+
```
46+
47+
## New behavior
48+
49+
Now, the API uses more explicit names that match Azure resource types. For example, use `AddBlobService`, `AddBlobContainer`, `AddQueueService`, `AddQueue`, `AddTableService`, and `AddTable`.
50+
51+
**Hosting integration example:**
52+
53+
```csharp
54+
var builder = DistributedApplication.CreateBuilder(args);
55+
56+
var storage = builder.AddAzureStorage("storage");
57+
58+
var blobs = storage.AddBlobService("blobService");
59+
blobs.AddBlobContainer("container");
60+
61+
var queues = storage.AddQueueService("queueService");
62+
queues.AddQueue("queue");
63+
64+
var tables = storage.AddTableService("tableService");
65+
```
66+
67+
Client registration methods now use names like `AddAzureBlobServiceClient`, `AddAzureQueueServiceClient`, and `AddAzureTableServiceClient`.
68+
69+
**Client integration example:**
70+
71+
```csharp
72+
var builder = WebApplication.CreateBuilder(args);
73+
74+
builder.AddAzureBlobServiceClient("storage");
75+
builder.AddAzureQueueServiceClient("storage");
76+
builder.AddAzureTableServiceClient("storage");
77+
```
78+
79+
## Type of breaking change
80+
81+
This change is a [binary incompatible](../categories.md#binary-compatibility) and [source incompatible](../categories.md#source-compatibility) change.
82+
83+
## Reason for change
84+
85+
The new API names provide consistency with Azure client libraries and resource granularity. This reduces confusion and makes it easier to understand and maintain Aspire applications that use Azure Storage resources. For more information, see the [GitHub issue](https://github.com/dotnet/docs-aspire/issues/3930).
86+
87+
## Recommended action
88+
89+
1. Update your code to use the new method names for adding and configuring Azure Storage resources and clients.
90+
1. Replace any obsolete method calls with their new equivalents as shown in the examples above.
91+
1. Recompile your application to ensure compatibility with .NET Aspire 9.4.
92+
93+
## Affected APIs
94+
95+
- <xref:Aspire.Azure.Hosting.Storage.AzureStorageResourceBuilder.AddBlobs>
96+
- <xref:Aspire.Azure.Hosting.Storage.AzureBlobStorageResourceBuilder.AddBlobContainer>
97+
- <xref:Aspire.Azure.Hosting.Storage.AzureStorageResourceBuilder.AddQueues>
98+
- <xref:Aspire.Azure.Hosting.Storage.AzureStorageResourceBuilder.AddTables>
99+
- <xref:Aspire.Azure.Hosting.Storage.AzureStorageResourceBuilder.AddBlobService>
100+
- <xref:Aspire.Azure.Hosting.Storage.AzureStorageResourceBuilder.AddBlobContainer>
101+
- <xref:Aspire.Azure.Hosting.Storage.AzureStorageResourceBuilder.AddQueueService>
102+
- <xref:Aspire.Azure.Hosting.Storage.AzureStorageResourceBuilder.AddQueue>
103+
- <xref:Aspire.Azure.Hosting.Storage.AzureStorageResourceBuilder.AddTableService>
104+
- <xref:Aspire.Azure.Hosting.Storage.AzureStorageResourceBuilder.AddTable>
105+
- <xref:Aspire.Azure.Storage.Blobs.BlobServiceClientBuilderExtensions.AddAzureBlobClient>
106+
- <xref:Aspire.Azure.Storage.Blobs.BlobServiceClientBuilderExtensions.AddAzureBlobServiceClient>
107+
- <xref:Aspire.Azure.Storage.Queues.QueueServiceClientBuilderExtensions.AddAzureQueueClient>
108+
- <xref:Aspire.Azure.Storage.Queues.QueueServiceClientBuilderExtensions.AddAzureQueueServiceClient>
109+
- <xref:Aspire.Azure.Data.Tables.TableServiceClientBuilderExtensions.AddAzureTableClient>
110+
- <xref:Aspire.Azure.Data.Tables.TableServiceClientBuilderExtensions.AddAzureTableServiceClient>
111+
112+
For a complete list of changes, see the [pull request](https://github.com/dotnet/aspire/pull/10241).

‎docs/compatibility/9.4/index.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ If you're migrating an app to .NET Aspire 9.4, the breaking changes listed here
1818

1919
| Title | Type of change | Introduced version |
2020
|--|--|--|
21+
| [Azure Storage APIs renamed and refactored](azure-storage-apis-renamed.md) | Binary incompatible, source incompatible | 9.4 |
22+
| [BicepSecretOutputReference and GetSecretOutput are now obsolete](getsecretoutput-deprecated.md) | Binary incompatible, source incompatible | 9.4 |
2123
| [Deprecating various known parameters in AzureBicepResource](azure-bicep-parameters-deprecated.md) | Source incompatible, behavioral change | 9.4 |
2224
| [Local auth is disabled by default on Azure resources](local-auth-disabled-for-azure-resources.md) | Behavioral change | 9.4 |
23-
| [BicepSecretOutputReference and GetSecretOutput are now obsolete](getsecretoutput-deprecated.md) | Behavioral, binary incompatible, source incompatible | 9.4 |

‎docs/compatibility/toc.yml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,14 @@ items:
1313
- name: Breaking changes in 9.4
1414
expanded: true
1515
items:
16+
- name: Azure Storage APIs renamed and refactored
17+
href: 9.4/azure-storage-apis-renamed.md
18+
- name: BicepSecretOutputReference and GetSecretOutput are now obsolete
19+
href: 9.4/getsecretoutput-deprecated.md
1620
- name: Deprecating various known parameters in AzureBicepResource
1721
href: 9.4/azure-bicep-parameters-deprecated.md
1822
- name: Local auth disabled by default on Azure resources
1923
href: 9.4/local-auth-disabled-for-azure-resources.md
20-
- name: BicepSecretOutputReference and GetSecretOutput are now obsolete
21-
href: 9.4/getsecretoutput-deprecated.md
2224
- name: .NET Aspire 9.3
2325
expanded: true
2426
items:

0 commit comments

Comments
 (0)