Class BlockBlobClient | Azure SDK for Net
Leah Mitchell
Published Feb 16, 2026
The BlockBlobClient allows you to manipulate Azure Storage block blobs.
Block blobs let you upload large blobs efficiently. Block blobs are comprised of blocks, each of which is identified by a block ID. You create or modify a block blob by writing a set of blocks and committing them by their block IDs. Each block can be a different size, up to a maximum of 100 MB (4 MB for requests using REST versions before 2016-05-31), and a block blob can include up to 50,000 blocks. The maximum size of a block blob is therefore slightly more than 4.75 TB (100 MB X 50,000 blocks). If you are writing a block blob that is no more than 256 MB in size, you can upload it in its entirety with a single write operation; see UploadAsync(Stream, BlobHttpHeaders, IDictionary<String,String>, BlobRequestConditions, Nullable<AccessTier>, IProgress<Int64>, CancellationToken).
When you upload a block to a blob in your storage account, it is associated with the specified block blob, but it does not become part of the blob until you commit a list of blocks that includes the new block's ID. New blocks remain in an uncommitted state until they are specifically committed or discarded. Writing a block does not update the last modified time of an existing blob.
Block blobs include features that help you manage large files over networks. With a block blob, you can upload multiple blocks in parallel to decrease upload time. Each block can include an MD5 hash to verify the transfer, so you can track upload progress and re-send blocks as needed.You can upload blocks in any order, and determine their sequence in the final block list commitment step. You can also upload a new block to replace an existing uncommitted block of the same block ID. You have one week to commit blocks to a blob before they are discarded. All uncommitted blocks are also discarded when a block list commitment operation occurs but does not include them.
You can modify an existing block blob by inserting, replacing, or deleting existing blocks. After uploading the block or blocks that have changed, you can commit a new version of the blob by committing the new blocks with the existing blocks you want to keep using a single commit operation. To insert the same range of bytes in two different locations of the committed blob, you can commit the same block in two places within the same commit operation.For any commit operation, if any block is not found, the entire commitment operation fails with an error, and the blob is not modified. Any block commitment overwrites the blob’s existing properties and metadata, and discards all uncommitted blocks.
Block IDs are strings of equal length within a blob. Block client code usually uses base-64 encoding to normalize strings into equal lengths. When using base-64 encoding, the pre-encoded string must be 64 bytes or less. Block ID values can be duplicated in different blobs. A blob can have up to 100,000 uncommitted blocks, but their total size cannot exceed 200,000 MB.
If you write a block for a blob that does not exist, a new block blob is created, with a length of zero bytes. This blob will appear in blob lists that include uncommitted blobs. If you don’t commit any block to this blob, it and its uncommitted blocks will be discarded one week after the last successful block upload. All uncommitted blocks are also discarded when a new blob of the same name is created using a single step(rather than the two-step block upload-then-commit process).
The GetBlockList(BlockListTypes, String, BlobRequestConditions, CancellationToken) operation operation retrieves the list of blocks that have been uploaded as part of a block blob. There are two block lists maintained for a blob. The Committed Block list has blocks that have been successfully committed to a given blob with CommitBlockList(IEnumerable<String>, BlobHttpHeaders, IDictionary<String,String>, BlobRequestConditions, Nullable<AccessTier>, CancellationToken). The Uncommitted Block list has blocks that have been uploaded for a blob using StageBlock(String, Stream, Byte[], BlobRequestConditions, IProgress<Int64>, CancellationToken), but that have not yet been committed. These blocks are stored in Azure in association with a blob, but do not yet form part of the blob.
Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.BlockList> GetBlockList (Azure.Storage.Blobs.Models.BlockListTypes blockListTypes = Azure.Storage.Blobs.Models.BlockListTypes.All, string snapshot = null, Azure.Storage.Blobs.Models.BlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);Parameters
| BlockListTypes blockListTypes Specifies whether to return the list of committed blocks, the list of uncommitted blocks, or both lists together. If you omit this parameter, Get Block List returns the list of committed blocks. |
| String snapshot Optionally specifies the blob snapshot to retrieve the block list from. For more information on working with blob snapshots, see . |
| BlobRequestConditions conditions Optional BlobRequestConditions to add conditions on retrieving the block list. |
| CancellationToken cancellationToken Optional CancellationToken to propagate notifications that the operation should be cancelled. |
Returns
The GetBlockListAsync(BlockListTypes, String, BlobRequestConditions, CancellationToken) operation operation retrieves the list of blocks that have been uploaded as part of a block blob. There are two block lists maintained for a blob. The Committed Block list has blocks that have been successfully committed to a given blob with CommitBlockListAsync(IEnumerable<String>, BlobHttpHeaders, IDictionary<String,String>, BlobRequestConditions, Nullable<AccessTier>, CancellationToken). The Uncommitted Block list has blocks that have been uploaded for a blob using StageBlockAsync(String, Stream, Byte[], BlobRequestConditions, IProgress<Int64>, CancellationToken), but that have not yet been committed. These blocks are stored in Azure in association with a blob, but do not yet form part of the blob.
Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.BlockList>> GetBlockListAsync (Azure.Storage.Blobs.Models.BlockListTypes blockListTypes = Azure.Storage.Blobs.Models.BlockListTypes.All, string snapshot = null, Azure.Storage.Blobs.Models.BlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);Parameters
| BlockListTypes blockListTypes Specifies whether to return the list of committed blocks, the list of uncommitted blocks, or both lists together. If you omit this parameter, Get Block List returns the list of committed blocks. |
| String snapshot Optionally specifies the blob snapshot to retrieve the block list from. For more information on working with blob snapshots, see . |
| BlobRequestConditions conditions Optional BlobRequestConditions to add conditions on retrieving the block list. |
| CancellationToken cancellationToken Optional CancellationToken to propagate notifications that the operation should be cancelled. |
Returns
The StageBlock(String, Stream, Byte[], BlobRequestConditions, IProgress<Int64>, CancellationToken) operation creates a new block as part of a block blob's "staging area" to be eventually committed via the CommitBlockList(IEnumerable<String>, BlobHttpHeaders, IDictionary<String,String>, BlobRequestConditions, Nullable<AccessTier>, CancellationToken) operation.
For more information, see .
Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.BlockInfo> StageBlock (string base64BlockId, System.IO.Stream content, byte[] transactionalContentHash = null, Azure.Storage.Blobs.Models.BlobRequestConditions conditions = null, IProgress<long> progressHandler = null, System.Threading.CancellationToken cancellationToken = null);Parameters
| String base64BlockId A valid Base64 string value that identifies the block. Prior to encoding, the string must be less than or equal to 64 bytes in size. For a given blob, the length of the value specified for the blockid parameter must be the same size for each block. Note that the Base64 string must be URL-encoded. |
| Stream content A Stream containing the content to upload. |
| Byte[] transactionalContentHash An optional MD5 hash of the block |
| BlobRequestConditions conditions Optional BlobRequestConditions to add conditions on the upload of this block. |
| IProgress<Int64> progressHandler Optional IProgress<T> to provide progress updates about data transfers. |
| CancellationToken cancellationToken Optional CancellationToken to propagate notifications that the operation should be cancelled. |
Returns
The StageBlockAsync(String, Stream, Byte[], BlobRequestConditions, IProgress<Int64>, CancellationToken) operation creates a new block as part of a block blob's "staging area" to be eventually committed via the CommitBlockListAsync(IEnumerable<String>, BlobHttpHeaders, IDictionary<String,String>, BlobRequestConditions, Nullable<AccessTier>, CancellationToken) operation.
For more information, see .
Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.BlockInfo>> StageBlockAsync (string base64BlockId, System.IO.Stream content, byte[] transactionalContentHash = null, Azure.Storage.Blobs.Models.BlobRequestConditions conditions = null, IProgress<long> progressHandler = null, System.Threading.CancellationToken cancellationToken = null);Parameters
| String base64BlockId A valid Base64 string value that identifies the block. Prior to encoding, the string must be less than or equal to 64 bytes in size. For a given blob, the length of the value specified for the blockid parameter must be the same size for each block. Note that the Base64 string must be URL-encoded. |
| Stream content A Stream containing the content to upload. |
| Byte[] transactionalContentHash An optional MD5 hash of the block |
| BlobRequestConditions conditions Optional BlobRequestConditions to add conditions on the upload of this block. |
| IProgress<Int64> progressHandler Optional IProgress<T> to provide progress updates about data transfers. |
| CancellationToken cancellationToken Optional CancellationToken to propagate notifications that the operation should be cancelled. |
Returns
Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.BlockInfo> StageBlockFromUri (Uri sourceUri, string base64BlockId, Azure.HttpRange sourceRange = null, byte[] sourceContentHash = null, Azure.RequestConditions sourceConditions = null, Azure.Storage.Blobs.Models.BlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);Parameters
| Uri sourceUri Specifies the Uri of the source blob. The value may be a URL of up to 2 KB in length that specifies a blob. The source blob must either be public or must be authenticated via a shared access signature. If the source blob is public, no authentication is required to perform the operation. |
| String base64BlockId A valid Base64 string value that identifies the block. Prior to
encoding, the string must be less than or equal to 64 bytes in
size. For a given blob, the length of the value specified for
the |
| HttpRange sourceRange Optionally uploads only the bytes of the blob in the |
| Byte[] sourceContentHash Optional MD5 hash of the block content from the |
| RequestConditions sourceConditions Optional RequestConditions to add conditions on the copying of data from this source blob. |
| BlobRequestConditions conditions Optional BlobRequestConditions to add conditions on the staging of this block. |
| CancellationToken cancellationToken Optional CancellationToken to propagate notifications that the operation should be cancelled. |
Returns
Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.BlockInfo>> StageBlockFromUriAsync (Uri sourceUri, string base64BlockId, Azure.HttpRange sourceRange = null, byte[] sourceContentHash = null, Azure.RequestConditions sourceConditions = null, Azure.Storage.Blobs.Models.BlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);Parameters
| Uri sourceUri Specifies the Uri of the source blob. The value may be a URL of up to 2 KB in length that specifies a blob. The source blob must either be public or must be authenticated via a shared access signature. If the source blob is public, no authentication is required to perform the operation. |
| String base64BlockId A valid Base64 string value that identifies the block. Prior to
encoding, the string must be less than or equal to 64 bytes in
size. For a given blob, the length of the value specified for
the |
| HttpRange sourceRange Optionally uploads only the bytes of the blob in the |
| Byte[] sourceContentHash Optional MD5 hash of the block content from the |
| RequestConditions sourceConditions Optional RequestConditions to add conditions on the copying of data from this source blob. |
| BlobRequestConditions conditions Optional BlobRequestConditions to add conditions on the staging of this block. |
| CancellationToken cancellationToken Optional CancellationToken to propagate notifications that the operation should be cancelled. |
