Class BlobRequestOptions

Namespace

Microsoft.WindowsAzure.Storage.Blob

Assembly

Microsoft.WindowsAzure.Storage.dll

Represents a set of timeout and retry policy options that may be specified for a request against the Blob service.

public sealed class BlobRequestOptions : IRequestOptions

Inheritance

object

BlobRequestOptions

Implements

IRequestOptions

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

BlobRequestOptions()

Initializes a new instance of the BlobRequestOptions class.

public BlobRequestOptions()

Properties

AbsorbConditionalErrorsOnRetry

Gets or sets a value that indicates whether a conditional failure should be absorbed on a retry attempt for the request.

public bool? AbsorbConditionalErrorsOnRetry { get; set; }

Property Value

bool?

Remarks

This option is used only by the CloudAppendBlob object in the UploadFrom* methods, the AppendFrom* methods, and the BlobWriteStream class. By default, it is set to false. Set this option to true only for single-writer scenarios. Setting this option to true in a multi-writer scenario may lead to corrupted blob data.

When calling "UploadFrom*" on an append blob, the Storage Client breaks the input data up into a number of data blocks, and uploads each data block with an "append block" operation. Normally, an "IfAppendPositionEqual" access condition is added to the append block operation, so that the upload operation will fail if some other process somewhere has appended data in the middle of this data stream. However, this can result in a false failure in a very specific case. If an append operation fails with a timeout, there is a chance that the operation succeeded on the service, but the "success" response did not make it back to the client. In this case, the client will retry, and then get an "append position not met" failure.

Setting this value to true results in the upload operation continuing when it sees an "append position not met" failure on retry - accounting for the above possibility. However, this loses protection in the multi-writer scenario - if multiple threads are uploading to the blob at once, and this value is set to true, some data may be lost, because the client thinks the data was uploaded, when in fact it was the other process' data.

Examples

Warning

It looks like the sample you are looking for does not exist.

DisableContentMD5Validation

Gets or sets a value to indicate that MD5 validation will be disabled when downloading blobs.

public bool? DisableContentMD5Validation { get; set; }

Property Value

bool?

Use true to disable MD5 validation; false to enable MD5 validation. Default is false.

Remarks

When downloading a blob, if the value already exists on the blob, the Storage service will include the MD5 hash of the entire blob as a header. This option controls whether or not the Storage Client will validate that MD5 hash on download. See StoreBlobContentMD5 for more details.

Examples

Warning

It looks like the sample you are looking for does not exist.

EncryptionPolicy

Gets or sets the encryption policy for the request.

public BlobEncryptionPolicy EncryptionPolicy { get; set; }

Property Value

BlobEncryptionPolicy

An object of type EncryptionPolicy.

Remarks

Examples

Warning

It looks like the sample you are looking for does not exist.

LocationMode

Gets or sets the location mode of the request.

public LocationMode? LocationMode { get; set; }

Property Value

LocationMode?

A LocationMode enumeration value indicating the location mode of the request.

Remarks

The LocationMode specifies in which locations the Storage Client will attempt to make the request. This is only valid for RA-GRS accounts - accounts where data can be read from either the primary or the secondary endpoint. ## Examples [!code-csharpLocationMode_Sample]

MaximumExecutionTime

Gets or sets the maximum execution time across all potential retries for the request.

public TimeSpan? MaximumExecutionTime { get; set; }

Property Value

TimeSpan?

A TimeSpan representing the maximum execution time for retries for the request.

Remarks

The maximum execution time is the time allotted for a single API call. If the total amount of time spent in the API - across all REST requests, retries, etc - exceeds this value, the client will timeout. This value is only tracked on the client, it is not sent to the service.

Examples

Warning

It looks like the sample you are looking for does not exist.

ParallelOperationThreadCount

Gets or sets the number of blocks that may be simultaneously uploaded.

public int? ParallelOperationThreadCount { get; set; }

Property Value

int?

An integer value indicating the number of parallel blob upload operations that may proceed.

Remarks

When using the UploadFrom* methods on a blob, the blob will be broken up into blocks. Setting this value limits the number of outstanding I/O "put block" requests that the library will have in-flight at a given time. Default is 1 (no parallelism). Setting this value higher may result in faster blob uploads, depending on the network between the client and the Azure Storage service. If blobs are small (less than 256 MB), keeping this value equal to 1 is advised.

Examples

Warning

It looks like the sample you are looking for does not exist.

RequireEncryption

Gets or sets a value to indicate whether data written and read by the client library should be encrypted.

public bool? RequireEncryption { get; set; }

Property Value

bool?

Use true to specify that data should be encrypted/decrypted for all transactions; otherwise, false.

Remarks

RequireEncryption here refers to Client-Side Encryption. If this value is set to true, all calls will fail if the data is not encrypted/decrypted with an encryption policy. If this value is false (the default), any data being downloaded that is not encrypted will be returned as-is.

Examples

Warning

It looks like the sample you are looking for does not exist.

RetryPolicy

Gets or sets the retry policy for the request.

public IRetryPolicy RetryPolicy { get; set; }

Property Value

IRetryPolicy

An object of type IRetryPolicy.

Remarks

Retry policies instruct the Storage Client to retry failed requests. By default, only some failures are retried. For example, connection failures and throttling failures can be retried. Resource not found (404) or authentication failures are not retried, because these are not likely to succeed on retry. If not set, the Storage Client uses an exponential backoff retry policy, where the wait time gets exponentially longer between requests, up to a total of around 30 seconds. The default retry policy is recommended for most scenarios.

       ## Examples
         [!code-csharp[Retry_Policy_Sample](~/azure-storage-net/Test/ClassLibraryCommon/Blob/BlobUploadDownloadTest.cs#sample_RequestOptions_RetryPolicy "Retry Policy Sample")]

ServerTimeout

Gets or sets the server timeout interval for a single HTTP request.

public TimeSpan? ServerTimeout { get; set; }

Property Value

TimeSpan?

A TimeSpan containing the server timeout interval for each HTTP request.

Remarks

The server timeout is the timeout sent to the Azure Storage service for each REST request made. If the API called makes multiple REST calls (UploadFromStream, for example, or if the request retries), this timeout will be applied separately to each request. This value is not tracked or validated on the client, it is only passed to the Storage service.

Examples

Warning

It looks like the sample you are looking for does not exist.

SingleBlobUploadThresholdInBytes

Gets or sets the maximum size of a blob in bytes that may be uploaded as a single blob.

public long? SingleBlobUploadThresholdInBytes { get; set; }

Property Value

long?

A long indicating the maximum size of a blob, in bytes, that may be uploaded as a single blob, ranging from between 1 and 256 MB inclusive.

Remarks

This value will be ignored if the ParallelOperationThreadCount is set to a value greater than 1

StoreBlobContentMD5

Gets or sets a value to indicate that an MD5 hash will be calculated and stored when uploading a blob.

public bool? StoreBlobContentMD5 { get; set; }

Property Value

bool?

Use true to calculate and store an MD5 hash when uploading a blob; otherwise, false. Defaults to false.

Remarks

This property is not supported for the CloudAppendBlob Append* APIs. The StoreBlobContentMD5 request option instructs the Storage Client to calculate the MD5 hash of the blob content during an upload operation. This value is then stored on the blob object as the Content-MD5 header. This option applies only to upload operations. This is useful for validating the integrity of the blob upon later download, and compatible with the Content-MD5 header as defined in the HTTP spec. If using the Storage Client for later download, if the Content-MD5 header is present, the MD5 hash of the content will be validated, unless "DisableContentMD5Validation" is set. Note that this value is not validated on the Azure Storage service on either upload or download of data; it is merely stored and returned. ## Examples [!code-csharpStore_Blob_Content_MD5_Sample]

UseTransactionalMD5

Gets or sets a value to calculate and send/validate content MD5 for transactions.

public bool? UseTransactionalMD5 { get; set; }

Property Value

bool?

Use true to calculate and send/validate content MD5 for transactions; otherwise, false. Default is false.

Remarks

The UseTransactionalMD5 option instructs the Storage Client to calculate and validate the MD5 hash of individual Storage REST operations. For a given REST operation, if this value is set, both the Storage Client and the Storage service will calculate the MD5 hash of the transferred data, and will fail if the values do not match. This value is not persisted on the service or the client. This option applies to both upload and download operations. Note that HTTPS does a similar check during transit. If you are using HTTPS, we recommend this feature be off.

Examples

Warning

It looks like the sample you are looking for does not exist.