CloudBlockBlob.BeginPutBlock Method (String, Stream, String, BlobRequestOptions, AsyncCallback, Object)

Storage Client Library NET API

[This topic is part of the Microsoft Azure Storage Client Library 1.7, which has been deprecated. See Storage Client Library for the latest version.]

Begins an asynchronous operation to upload a single block, using a conditional request based on the BlobRequestOptions specified.

Namespace: Microsoft.WindowsAzure.StorageClient
Assembly: Microsoft.WindowsAzure.StorageClient (in Microsoft.WindowsAzure.StorageClient.dll)

Usage

Visual Basic
Dim instance As CloudBlockBlob
Dim blockId As String
Dim blockData As Stream
Dim contentMD5 As String
Dim options As BlobRequestOptions
Dim callback As AsyncCallback
Dim state As Object
Dim returnValue As IAsyncResult

returnValue = instance.BeginPutBlock(blockId, blockData, contentMD5, options, callback, state)

Syntax

Visual Basic
Public Function BeginPutBlock ( _
	blockId As String, _
	blockData As Stream, _
	contentMD5 As String, _
	options As BlobRequestOptions, _
	callback As AsyncCallback, _
	state As Object _
) As IAsyncResult
C#
public IAsyncResult BeginPutBlock (
	string blockId,
	Stream blockData,
	string contentMD5,
	BlobRequestOptions options,
	AsyncCallback callback,
	Object state
)
C++
public:
IAsyncResult^ BeginPutBlock (
	String^ blockId, 
	Stream^ blockData, 
	String^ contentMD5, 
	BlobRequestOptions^ options, 
	AsyncCallback^ callback, 
	Object^ state
)
J#
JScript

Parameters

blockId

Type: System.String

A base64-encoded block ID that identifies the block.

blockData

Type: System.IO.Stream

A stream that provides the data for the block.

contentMD5

Type: System.String

A hash value used to verify the integrity of the block. May be null or an empty string.

options

Type: Microsoft.WindowsAzure.StorageClient.BlobRequestOptions

An object that specifies any additional options for the request.

callback

Type: System.AsyncCallback

The callback delegate that will receive notification when the asynchronous operation completes.

state

Type: System.Object

A user-defined object that will be passed to the callback delegate.

Return Value

Type: System.IAsyncResult

An IAsyncResult that references the asynchronous operation.

Remarks

The BeginPutBlock method begins an operation to upload a block for future inclusion in a block blob. A block may be up to 4 MB in size.

After you have uploaded a set of blocks, you can create or update the blob on the server from this set by calling the BeginPutBlockList method. Each block in the set is identified by a block ID that is unique within that blob. Block IDs are scoped to a particular blob, so different blobs can have blocks with same IDs.

If you call BeginPutBlock on a blob that does not yet exist, a new block blob is created with a content length of 0. This blob is enumerated by a blob listing operation if the UncommittedBlobs option is specified. The block or blocks that you uploaded are not committed until you commit the block list for the new blob. A blob created this way is maintained on the server for a week; if you have not added more blocks or committed blocks to the blob within that time period, then the blob is garbage collected.

The maximum block blob size currently supported is 200 GB, and up to 50,000 blocks. A blob can have a maximum of 100,000 uncommitted blocks at any given time, and the set of uncommitted blocks cannot exceed 400 GB in total size.

A block that has been successfully uploaded does not become part of a blob until it is committed with a call to BeginPutBlockList. Before the block list is committed to create a new blob or update an existing blob, an operation to return the blob's contents does not include the contents of the uncommitted block.

If you upload a block that has the same block ID as another block that has not yet been committed, the last uploaded block with that ID will be committed on the next successful call to BeginPutBlockList.

On calling BeginPutBlockList, all uncommitted blocks specified in the block list are committed as part of the new blob. Any uncommitted blocks that were not specified in the block list for the blob will be garbage collected and removed from the Blob service. Any uncommitted blocks will also be garbage collected if they are not committed within a week following the last successful block upload. If another write operation is performed on the blob, any uncommitted blocks will also be garbage collected.

For a given blob, all block IDs must be the same length, but the block contents can be of different size. If a block is uploaded with a block ID of a different length than the block IDs for any existing uncommitted blocks, an exception is thrown, with an error code of InvalidBlockId.

Calling BeginPutBlock does not update the last modified time of an existing blob.


Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Development Platforms

Windows Vista, Windows 7, Windows Server 2008, Windows 8.1, Windows Server 2012 R2, Windows 8 and Windows Server 2012

See Also