| name | migrating-azure-storage |
| description | Migrates the deprecated WindowsAzure.Storage to the modern Azure SDK storage libraries (Azure.Storage.Blobs, Azure.Storage.Queues, Azure.Storage.Files.Shares, Azure.Data.Tables). Use ONLY when WindowsAzure.Storage has been flagged as obsolete or deprecated and must be replaced — not for version-bump scenarios where WindowsAzure.Storage is still supported.
|
| metadata | {"discovery":"lazy","traits":".NET|CSharp|VisualBasic|DotNetCore"} |
Azure Storage Migration
Overview
Migrate from the monolithic WindowsAzure.Storage (or Microsoft.Azure.Storage.*) package to the modern Azure SDK storage libraries. The legacy SDK used CloudStorageAccount as a single entry point for all storage services. The new SDK splits into service-specific packages with dedicated client types. All new clients are thread-safe, reusable, and support both connection string and Azure.Identity-based authentication.
Package Reference Changes
Old References (Remove)
<PackageReference Include="WindowsAzure.Storage" Version="{old-version}" />
<PackageReference Include="Microsoft.Azure.Storage.Blob" Version="{old-version}" />
<PackageReference Include="Microsoft.Azure.Storage.Queue" Version="{old-version}" />
<PackageReference Include="Microsoft.Azure.Storage.File" Version="{old-version}" />
<PackageReference Include="Microsoft.Azure.Cosmos.Table" Version="{old-version}" />
New References (Add)
Add only the packages for storage services the project uses:
<PackageReference Include="Azure.Storage.Blobs" Version="{version}" />
<PackageReference Include="Azure.Storage.Queues" Version="{version}" />
<PackageReference Include="Azure.Storage.Files.Shares" Version="{version}" />
<PackageReference Include="Azure.Data.Tables" Version="{version}" />
Note: Table storage uses Azure.Data.Tables, a separate package from the Azure.Storage.* family. It supports both Azure Table Storage and Azure Cosmos DB Table API.
Optionally add Azure.Identity for Azure AD–based authentication.
Workflow
Migration Progress:
- [ ] Step 1: Detect legacy Azure Storage usage
- [ ] Step 2: Update project file references
- [ ] Step 3: Replace storage account initialization
- [ ] Step 4: Migrate blob operations
- [ ] Step 5: Migrate queue operations
- [ ] Step 6: Migrate table operations
- [ ] Step 7: Migrate file share operations
- [ ] Step 8: Build and verify
Step 1: Detect Legacy Azure Storage Usage
Scan the project for:
using Microsoft.WindowsAzure.Storage; or using Microsoft.Azure.Storage; statementsCloudStorageAccount.Parse(...) or CloudStorageAccount.TryParse(...) calls- Client types:
CloudBlobClient, CloudBlobContainer, CloudBlockBlob, CloudQueue, CloudTable, CloudFileShare
- Determine which storage services are used to add only the needed new packages
Step 2: Update Project File References
Remove legacy packages and add the relevant new packages (see "Package Reference Changes" above). Only add packages for services the project actually uses.
Step 3: Replace Storage Account Initialization
The new SDK does not use CloudStorageAccount. Create service-specific clients directly:
var account = CloudStorageAccount.Parse(connectionString);
var blobClient = account.CreateCloudBlobClient();
var blobServiceClient = new BlobServiceClient(connectionString);
var blobServiceClient = new BlobServiceClient(
new Uri("https://myaccount.blob.core.windows.net"),
new DefaultAzureCredential());
Step 4: Migrate Blob Operations
| WindowsAzure.Storage (Old) | Azure.Storage.Blobs (New) |
|---|
CloudBlobClient | BlobServiceClient |
CloudBlobContainer | BlobContainerClient |
CloudBlockBlob | BlobClient |
CloudAppendBlob | AppendBlobClient |
CloudPageBlob | PageBlobClient |
container.CreateIfNotExistsAsync() | container.CreateIfNotExistsAsync() (same) |
blob.UploadFromStreamAsync(stream) | await blob.UploadAsync(stream) |
blob.DownloadToStreamAsync(stream) | await blob.DownloadToAsync(stream) |
blob.ExistsAsync() | await blob.ExistsAsync() (same) |
blob.DeleteIfExistsAsync() | await blob.DeleteIfExistsAsync() (same) |
container.ListBlobsSegmentedAsync(...) | container.GetBlobsAsync(...) (async enumerable) |
Paginated listing changes from segmented tokens to IAsyncEnumerable:
BlobContinuationToken token = null;
do {
var segment = await container.ListBlobsSegmentedAsync(token);
token = segment.ContinuationToken;
} while (token != null);
await foreach (var blobItem in container.GetBlobsAsync())
{
}
Step 5: Migrate Queue Operations
| WindowsAzure.Storage (Old) | Azure.Storage.Queues (New) |
|---|
CloudQueueClient | QueueServiceClient |
CloudQueue | QueueClient |
queue.AddMessageAsync(new CloudQueueMessage(text)) | await queue.SendMessageAsync(text) |
queue.GetMessageAsync() | await queue.ReceiveMessageAsync() |
queue.DeleteMessageAsync(message) | await queue.DeleteMessageAsync(message.MessageId, message.PopReceipt) |
Note: The new SDK base64-encodes message content by default. To disable: new QueueClientOptions { MessageEncoding = QueueMessageEncoding.None }.
Step 6: Migrate Table Operations
Table storage moved to a separate package (Azure.Data.Tables):
| Old (CloudTable) | New (Azure.Data.Tables) |
|---|
CloudTableClient | TableServiceClient |
CloudTable | TableClient |
TableOperation.Insert(entity) | await tableClient.AddEntityAsync(entity) |
TableOperation.InsertOrReplace(entity) | await tableClient.UpsertEntityAsync(entity) |
TableOperation.Retrieve(pk, rk) | await tableClient.GetEntityAsync<T>(pk, rk) |
table.ExecuteQuerySegmentedAsync(query, token) | tableClient.QueryAsync<T>(filter) (async enumerable) |
DynamicTableEntity | TableEntity (dictionary-like access) |
Entities must implement ITableEntity (or use the built-in TableEntity class).
Step 7: Migrate File Share Operations
| WindowsAzure.Storage (Old) | Azure.Storage.Files.Shares (New) |
|---|
CloudFileClient | ShareServiceClient |
CloudFileShare | ShareClient |
CloudFileDirectory | ShareDirectoryClient |
CloudFile | ShareFileClient |
file.UploadFromStreamAsync(stream) | await file.UploadAsync(stream) |
file.DownloadToStreamAsync(stream) | await file.DownloadAsync() then read from stream |
Skip this step if the project does not use Azure File Shares.
Step 8: Build and Verify
- Build the project:
dotnet build
- Test each storage service used by the project (blob upload/download, queue send/receive, table CRUD, file operations)
- Verify authentication works with the chosen method (connection string or Azure AD)
- Confirm paginated listings work correctly with async enumerables
Troubleshooting
CloudStorageAccount Not Found
The new SDK does not include CloudStorageAccount. Replace with service-specific client constructors that accept a connection string directly (e.g., new BlobServiceClient(connectionString)).
Base64-Encoded Queue Messages
The new QueueClient base64-encodes messages by default. If interoperating with code using the old SDK, set MessageEncoding = QueueMessageEncoding.None in QueueClientOptions to maintain compatibility.
Table Entity Serialization Errors
Entities must implement ITableEntity with PartitionKey, RowKey, Timestamp, and ETag properties. If using DynamicTableEntity from the old SDK, switch to TableEntity which provides dictionary-style property access.
Mixed Old and New SDK References
Transitive dependencies may pull in both old and new packages, causing ambiguous type references. Use dotnet list package --include-transitive to identify conflicts and add explicit package references to force the new versions.
