Export (0) Print
Expand All
2 out of 12 rated this helpful - Rate this topic

What's New in Storage Client Library for .NET

Updated: April 24, 2013

The Windows Azure Storage Client Library for .NET (version 2.0) includes many new features, expanded platform support, extensibility points, and performance improvements. We also listened to customers and focused on fixing the biggest problems that affected the most users. This topic provides information about what has changed between versions 1.7 and 2.0 of the Storage Client Library (SCL), and migration tips to help you migrate existing applications to the version 2.0 release.

SCL version 1.7 and SCL version 2.0 are both included in the Windows Azure SDK 1.8, which can be downloaded from the .NET Developer Center. Both versions of the SCL are also available through NuGet. The WindowsAzure.Storage Nuget package for SCL version 2.0 has an updated major version number of 2.0. If you have an existing dependency on this Nuget package be sure to constrain the download to the last released version (1.7) if you do not want to use the SCL version 2.0 features. This will ensure that version 2.0 of the Nuget package does not automatically get pulled down and create breaking changes in your code. The source code for the SCL can also be downloaded from GitHub under the Apache 2.0 license.

We have put a lot of work into providing a first class development experience and you’ll also see your past feedback reflected in the new library. We really do appreciate the feedback we have gotten from the community, please try out the new SCL version 2.0 and let us know what you think on the forums.

ImportantImportant
The Windows Azure storage client library and storage services support both HTTP and HTTPS; however, using HTTPS is highly recommended.

What’s New

Here’s what’s new in the SCL:

  • The assembly has changed from Microsoft.WindowsAzure.StorageClient.dll to Microsoft.WindowsAzure.Storage.dll.

  • The core namespaces of the library have been reworked to provide a simpler, less cluttered Intellisense experience. See below for more information.

  • Added support for the .NET Framework 4 Client Profile, allowing for easier installation of your application on machines where the full .NET Framework has not been installed.

  • The ODataLib dependencies in the Storage Client Library for .NET are now resolved through the ODataLib (version 5.0.2) packages available through NuGet and not through WCF Data Services.  You can download the ODataLib libraries directly from CodePlex or reference them in your code project through NuGet. The specific ODataLib packages are:Microsoft.Data.Edm, Microsoft.Data.OData, and System.Spatial.

  • Over 450 new unit tests published to github.

  • All APIs that execute a request against the storage service are marked with the DoesServiceRequest attribute.

  • Support for custom user headers.

  • An OperationContext class, which provides you an optional source of diagnostic information about how an operation is executing. One common piece of feedback we received was that it’s too difficult to know what happened “under the covers” when making a call to the storage service. How many retries were there? What were the error codes? The OperationContext class provides rich debugging information, real-time status events for parallel and complex actions, and extension points, which gives you the ability to customize requests or enable end to end client tracing.

  • True synchronous method support. SCL version 1.7 implemented synchronous methods by simply wrapping a corresponding Asynchronous Programming Model (APM) method. Now, synchronous work is done on the calling thread with the exception of the stream implementations available through parallel uploads and OpenRead, OpenRead, OpenRead, OpenWrite.

  • Support for asynchronous cancellation through the ICancellableAsyncResult interface. Asynchronous cancellation can also be hooked up to .NET cancellation tokens via the Register method.

  • Timeouts. The SCL now allows two separate timeouts to be specified. You can specify these timeouts directly on the service client (e.g. the CloudBlobClient class) or override them through the BlobRequestOptions, QueueRequestOptions, or TableRequestOptions classes. These timeouts are null-able and therefore can be disabled.

    • The server timeout is the timeout given to the server for each request executed in a logical operation. An operation may make more than one request in the case of a retry or parallel upload and is sent for each of these requests. The server timeout is 90 seconds by default.

    • The maximum execution time provides a true end-to-end timeout. This timeout is a client side timeout that spans all requests (including any potential retries) that an operation may execute. This is disabled by default.

  • Full page blob support, implemented in the CloudPageBlob class, including read and write streams.

  • Download range support for the CloudBlockBlob and CloudPageBlob classes.

  • Blobs support download resume. In the event of an error, the subsequent request will be truncated to specify a range at the correct byte offset.

  • The default MD5 behavior has been updated to utilize a FISMA compliant implementation. To use the default .NET MD5 behavior, set the UseV1MD5 property to true.

Updated Namespaces

We’ve updated the core namespaces of the library to provide a simpler, less cluttered Intellisense experience and to more closely align with non-storage Windows Azure services. We’ve also changed the root namespace, as well as the assembly name itself, from Microsoft.WindowsAzure.StorageClient to Microsoft.WindowsAzure.Storage. Additionally, each service has been broken out into its own sub namespace. For example, the blob implementation is located in Microsoft.WindowsAzure.Storage.Blob, and all protocol relevant constructs are in Microsoft.WindowsAzure.Storage.Blob.Protocol. Note: Windows Runtime components will not expose Microsoft.WindowsAzure.Storage.Blob.Protocol, Microsoft.WindowsAzure.Storage.Table.Protocol, Microsoft.WindowsAzure.Storage.Queue.Protocol namespaces since they contain dependencies on .NET specific types and are therefore not projectable.

Here’s a list of client accessible namespaces in the assembly:

Changes from Storage Client Library 1.7

Here’s what changed from SCL version 1.7 to SCL version 2.0:

General

Blob

  • You need to access all blobs using the CloudBlockBlob or CloudPageBlob classes. The CloudBlob base class has been removed. To get a reference to the concrete blob class when the client does not know the type, use the GetBlobReferenceFromServer and GetBlobReferenceFromServer methods.

  • Parallelism is now set to 1 by default. You can configure parallelism using the ParallelOperationThreadCount property.

  • The SingleBlobUploadThresholdInBytes property can now be set as low as 1 MB.

  • The StreamWriteSizeInBytes method has been moved to the CloudBlockBlob class and can now be set as low as 16KB. Please note that the maximum number of blocks a blob can contain is 50,000 meaning that with a block size of 16kb, the maximum blob size that can be stored is 800,000KB or ~ 781 MB.

  • All upload and download methods are now stream based, the DownloadToFile, DownloadByteArray, DownloadText, UploadFromFile, UploadByteArray, and UploadText overloads have been removed.

  • The stream implementation available through the OpenWrite method will no longer encode MD5 into the block ID. Instead, a sequential block counter appended to a fixed random integer is used in the format of [Random:8]-[Seq:6].

  • For uploads if a given stream is not seek-able it will be uploaded via the stream implementation which will result in multiple operations regardless of length.

  • MD5 has been simplified, all methods will honor the three MD5 related flags exposed by the BlobRequestOptions class.

    • StoreBlobContentMD5 property– Stores the Content MD5 on the Blob on the server (default to true).

    • UseTransactionalMD5 property– Will ensure each upload and download provides transactional security via the HTTP Content-MD5 header. Note: when enabled, all DownloadRange requests must be 4MB or less. (default is disabled, however any time a Content-MD5 header is sent by the server the client will validate it unless the DisableContentMD5Validation property is set).

    • DisableContentMD5Validation – Disables any Content-MD5 validation on downloads. This is needed to download any blobs that may have had the Content-MD5 header set incorrectly.

  • The CloudBlockBlob and CloudPageBlob classes no longer expose BlobAttributes. Instead the blob properties, metadata, URI, and so on, are exposed on the CloudBlockBlob and CloudPageBlob classes.

  • The stream available through the OpenRead and OpenRead methods does not support multiple asynchronous reads prior to the first call completing. You must first call the EndRead method prior to a subsequent call to the BeginRead method.

  • Protocol

Queue

Table

Migration Guide

Here’s a simple migration guide to get you started migrating your existing applications.

Namespaces

Blobs

Tables

  • If you migrate an existing Table application you can choose to re-implement it using the new simplified Table service implementation. Otherwise, add a using statement for the Microsoft.WindowsAzure.Storage.Table.DataServices namespace.

  • Any code that may rely on concurrent requests against the same TableServiceContext object needs to be updated to execute serially, or use multiple contexts.

See Also

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.