Azure Storage client libraries for .NET
The Azure Storage client libraries for .NET offer a convenient interface for making calls to Azure Storage. For more information about Azure Storage, see Introduction to Azure Storage.
Libraries for data access
The latest version of the Azure Storage client library for data access is version 12.x.x. Microsoft recommends using version 12.x.x for new applications.
If you cannot update existing applications to version 12.x.x, then Microsoft recommends using version 11.x.x.
Version 12.x.x
The version 12.x.x client libraries for .NET are part of the Azure SDK for .NET. The source code for the Azure Storage client libraries for .NET is available on GitHub.
Use the following version 12.x.x libraries to work with blobs, files, and queues:
| Library | Reference | Package | Source |
|---|---|---|---|
| Azure.Storage.Blobs.Batch | NuGet | GitHub | |
| Azure.Storage.Blobs | Reference | NuGet | GitHub |
| Azure.Storage.Common | NuGet | GitHub | |
| Azure.Storage.Files.DataLake | Reference | NuGet | GitHub |
| Azure.Storage.Files.Shares | Reference | NuGet | GitHub |
| Azure.Storage.Queues | Reference | NuGet | GitHub |
Version 11.x.x
The source code for the Azure Storage client libraries for .NET is available on GitHub.
Use the following version 11.x.x libraries to work with blobs, files, and queues:
| Library | Reference | Package | Source |
|---|---|---|---|
| Microsoft.Azure.Storage.Blob | Reference | NuGet | GitHub |
| Microsoft.Azure.Storage.Common | NuGet | GitHub | |
| Microsoft.Azure.Storage.File | Reference | NuGet | GitHub |
| Microsoft.Azure.Storage.Queue | Reference | NuGet | GitHub |
Libraries for resource management
The latest version of the Azure Storage client library for resource management is version 1.x.x. Microsoft recommends using version 1.x.x for new applications.
If you cannot update existing applications to version 1.x.x, then Microsoft recommends using version 25.x.x.
Version 1.x.x
Use the following version 1.x.x library to work with the Azure Storage resource provider:
| Library | Reference | Package | Source |
|---|---|---|---|
| Azure.ResourceManager.Storage | Reference | NuGet | GitHub |
Version 25.x.x
Use the following version 25.x.x library to work with the Azure Storage resource provider:
| Library | Reference | Package | Source |
|---|---|---|---|
| Microsoft.Azure.Management.Storage | Reference | NuGet | GitHub |
Known issues
This section details known issues for the Azure Storage client libraries for .NET.
Client-side encryption bug when using BlobClient.UpdateClientSideEncryptionKey with an unauthenticated symmetric encryption algorithm
Issue description
A bug was found in BlobClient.UpdateClientSideEncryptionKey that might affect customers who are using an unauthenticated symmetric encryption algorithm for key wrapping. If a customer using an impacted version of Azure.Storage.Blobs attempts to rotate an unauthenticated symmetric encryption key using BlobClient.UpdateClientSideEncryptionKey, the key might silently rotate incorrectly, and decryption with the SDK might not be possible without additional steps. Only a small subset of key wrapping algorithms can cause this situation. Most key wrapping algorithms safely throw an exception during key rotation and don't actually rotate the key. For remediation guidance, see Recommended steps.
This bug does not affect customers who use an authenticated symmetric key wrapping algorithm, and does not affect customers who use asymmetric keys. Asymmetric keys are used by Azure Key Vault and are not affected by this bug. Also, the async API BlobClient.UpdateClientSideEncryptionKeyAsync is not affected by this bug.
Issue details
| Client library | Versions impacted | Minimum safe version | Recommended action |
|---|---|---|---|
| Azure Storage Blob | 12.11.0-beta.2 to 12.21.1 | 12.21.2 | Update to latest version or minimum 12.21.2 |
Recommended steps
- Update client library version according to the table above.
- If you rotated an unauthenticated symmetric encryption key with
BlobClient.UpdateClientSideKeyEncryptionKeyand an affected version of Azure.Storage.Blobs, it might be possible to restore your data by encrypting the affected key twice.
InvalidHeaderValue error message when using beta version of SDK
In rare scenarios, applications that have upgraded to the latest beta or generally available version of the SDK can receive an InvalidHeaderValue error message. This issue can occur when using any of the Storage libraries. The error message looks similar to the following sample:
HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error>
If you've upgraded to the latest beta or generally available version of the SDK and you experience this error, it's recommended that you downgrade to the previous generally available version of the SDK to see if the issue resolves. If the issue persists, or if the recommendation is not feasible, open a support ticket to explore further options.
