Share via

Azure Storage client libraries for .NET

  • Article

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
  • Update client library version according to the table above.
  • If you rotated an unauthenticated symmetric encryption key with BlobClient.UpdateClientSideKeyEncryptionKey and 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.