BlockBlobClient
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 4,000 MB (100 MB for requests using REST
versions before 2019-12-12 and 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 approximately 190.73 TiB
(4,000 MB X 50,000 blocks). If you are writing a block blob that is
no more than 5,000 MB in size, you can upload it in its entirety with a
single write operation; see UploadAsync.
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, with a max total size
of appoximately 381.46 TiB (4,000 MB x 100,000 blocks)
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).
Gets the maximum number of blocks allowed in a block blob.
Gets the maximum number of bytes that can be sent in a call
to StageBlockAsync. Supported value is now larger
than MaxValue; please use
BlockBlobMaxStageBlockLongBytes.
Gets the maximum number of bytes that can be sent in a call
to StageBlockAsync.
Gets the maximum number of bytes that can be sent in a call
to UploadAsync. Supported value is now larger
than MaxValue; please use
BlockBlobMaxUploadBlobLongBytes.
Gets the maximum number of bytes that can be sent in a call
to UploadAsync.
protected BlockBlobClient()
Initializes a new instance of the BlockBlobClient
class for mocking.
Initializes a new instance of the BlockBlobClient
class.
public BlockBlobClient(string connectionString, string blobContainerName, string blobName, BlobClientOptions options)
Initializes a new instance of the BlockBlobClient
class.
Initializes a new instance of the BlockBlobClient
class.
public BlockBlobClient(Uri blobUri, StorageSharedKeyCredential credential, BlobClientOptions options = null)
Initializes a new instance of the BlockBlobClient
class.
public BlockBlobClient(Uri blobUri, AzureSasCredential credential, BlobClientOptions options = null)
Initializes a new instance of the BlockBlobClient
class.
Initializes a new instance of the BlockBlobClient
class.
protected static BlockBlobClient CreateClient(Uri blobUri, BlobClientOptions options, HttpPipeline pipeline)
Initializes a new instance of the BlockBlobClient
class.
public virtual Response<BlobContentInfo> CommitBlockList(IEnumerable<string> base64BlockIds, CommitBlockListOptions options, CancellationToken cancellationToken = default)
The CommitBlockList
operation writes a blob by specifying the list of block IDs that make up the blob. In order
to be written as part of a blob, a block must have been
successfully written to the server in a prior StageBlock
operation. You can call CommitBlockList
to update a blob by uploading only those blocks that have changed,
then committing the new and existing blocks together. You can do
this by specifying whether to commit a block from the committed
block list or from the uncommitted block list, or to commit the
most recently uploaded version of the block, whichever list it
may belong to. Any blocks not specified in the block list are
permanently deleted.
Note: Uncommitted blocks will expire and be permanently deleted after 7 days.
Blocks that are committed to a blob do not expire.
For more information, see
Put Block List.
public virtual Response<BlobContentInfo> CommitBlockList(IEnumerable<string> base64BlockIds, BlobHttpHeaders httpHeaders = null, IDictionary<string, string> metadata = null, BlobRequestConditions conditions = null, AccessTier? accessTier = default, CancellationToken cancellationToken = default)
The CommitBlockList
operation writes a blob by specifying the list of block IDs that make up the blob.
In order to be written as part of a blob, a block must have been
successfully written to the server in a prior StageBlock
operation. You can call CommitBlockList
to update a blob by uploading only those blocks that have changed,
then committing the new and existing blocks together. You can do
this by specifying whether to commit a block from the committed
block list or from the uncommitted block list, or to commit the
most recently uploaded version of the block, whichever list it
may belong to. Any blocks not specified in the block list are
permanently deleted.
Note: Uncommitted blocks will expire and be permanently deleted after 7 days.
Blocks that are committed to a blob do not expire.
For more information, see
Put Block List.
public virtual Task<Response<BlobContentInfo>> CommitBlockListAsync(IEnumerable<string> base64BlockIds, CommitBlockListOptions options, CancellationToken cancellationToken = default)
The CommitBlockListAsync
operation writes a blob by specifying the list of block IDs that make up the blob. In order
to be written as part of a blob, a block must have been
successfully written to the server in a prior StageBlock
operation. You can call CommitBlockListAsync
to update a blob by uploading only those blocks that have changed,
then committing the new and existing blocks together. You can do
this by specifying whether to commit a block from the committed
block list or from the uncommitted block list, or to commit the
most recently uploaded version of the block, whichever list it
may belong to. Any blocks not specified in the block list are
permanently deleted.
Note: Uncommitted blocks will expire and be permanently deleted after 7 days.
Blocks that are committed to a blob do not expire.
For more information, see
Put Block List.
public virtual Task<Response<BlobContentInfo>> CommitBlockListAsync(IEnumerable<string> base64BlockIds, BlobHttpHeaders httpHeaders = null, IDictionary<string, string> metadata = null, BlobRequestConditions conditions = null, AccessTier? accessTier = default, CancellationToken cancellationToken = default)
The CommitBlockListAsync
operation writes a blob bys pecifying the list of block IDs that make up the blob.
In order to be written as part of a blob, a block must have been
successfully written to the server in a prior StageBlockAsync
operation. You can call CommitBlockListAsync
to update a blob by uploading only those blocks that have changed,
then committing the new and existing blocks together. You can do
this by specifying whether to commit a block from the committed
block list or from the uncommitted block list, or to commit the
most recently uploaded version of the block, whichever list it
may belong to. Any blocks not specified in the block list are
permanently deleted.
Note: Uncommitted blocks will expire and be permanently deleted after 7 days.
Blocks that are committed to a blob do not expire.
For more information, see
Put Block List.
public virtual Response<BlockList> GetBlockList(BlockListTypes blockListTypes = 3, string snapshot = null, BlobRequestConditions conditions = null, CancellationToken cancellationToken = default)
The GetBlockList 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.
The Uncommitted Block list has blocks that have been uploaded for a
blob using StageBlock, 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.
public virtual Task<Response<BlockList>> GetBlockListAsync(BlockListTypes blockListTypes = 3, string snapshot = null, BlobRequestConditions conditions = null, CancellationToken cancellationToken = default)
The GetBlockListAsync 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.
The Uncommitted Block list has blocks that have been uploaded for a
blob using StageBlockAsync, 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.
public virtual Stream OpenWrite(bool overwrite, BlockBlobOpenWriteOptions options = null, CancellationToken cancellationToken = default)
Opens a stream for writing to the blob.
public virtual Task<Stream> OpenWriteAsync(bool overwrite, BlockBlobOpenWriteOptions options = null, CancellationToken cancellationToken = default)
Opens a stream for writing to the blob. If the blob exists,
it will be overwritten.
public virtual Response<BlobDownloadInfo> Query(string querySqlExpression, BlobQueryOptions options = null, CancellationToken cancellationToken = default)
The Query API returns the
result of a query against the blob.
For more information, see
Query Blob Contents.
public virtual Task<Response<BlobDownloadInfo>> QueryAsync(string querySqlExpression, BlobQueryOptions options = null, CancellationToken cancellationToken = default)
The QueryAsync API returns the
result of a query against the blob.
For more information, see
Query Blob Contents.
public virtual Response<BlockInfo> StageBlock(string base64BlockId, Stream content, byte[] transactionalContentHash, BlobRequestConditions conditions, IProgress<long> progressHandler, CancellationToken cancellationToken)
The StageBlock operation creates a new block as
part of a block blob's "staging area" to be eventually committed
via the CommitBlockList operation.
For more information, see
Put Block.
public virtual Response<BlockInfo> StageBlock(string base64BlockId, Stream content, BlockBlobStageBlockOptions options = null, CancellationToken cancellationToken = default)
The StageBlock operation creates a new block as
part of a block blob's "staging area" to be eventually committed
via the CommitBlockListAsync operation.
For more information, see
Put Block.
public virtual Task<Response<BlockInfo>> StageBlockAsync(string base64BlockId, Stream content, byte[] transactionalContentHash, BlobRequestConditions conditions, IProgress<long> progressHandler, CancellationToken cancellationToken)
The StageBlockAsync operation creates a new block as
part of a block blob's "staging area" to be eventually committed
via the CommitBlockListAsync operation.
For more information, see
Put Block.
public virtual Task<Response<BlockInfo>> StageBlockAsync(string base64BlockId, Stream content, BlockBlobStageBlockOptions options = null, CancellationToken cancellationToken = default)
The StageBlockAsync operation creates a new block as
part of a block blob's "staging area" to be eventually committed
via the CommitBlockListAsync operation.
For more information, see
Put Block.
public virtual Response<BlockInfo> StageBlockFromUri(Uri sourceUri, string base64BlockId, StageBlockFromUriOptions options = null, CancellationToken cancellationToken = default)
The StageBlockFromUri
operation creates a new block to be committed as part of a blob where the contents are
read from the sourceUri.
For more information, see
Put Block From URL.
public virtual Response<BlockInfo> StageBlockFromUri(Uri sourceUri, string base64BlockId, HttpRange sourceRange, byte[] sourceContentHash, RequestConditions sourceConditions, BlobRequestConditions conditions, CancellationToken cancellationToken)
The StageBlockFromUri
operation creates a new block to be committed as part of a blob where the contents are
read from the sourceUri.
For more information, see
Put Block From URL.
public virtual Task<Response<BlockInfo>> StageBlockFromUriAsync(Uri sourceUri, string base64BlockId, StageBlockFromUriOptions options = null, CancellationToken cancellationToken = default)
The StageBlockFromUriAsync
operation creates a new block to be committed as part of a blob where the contents are
read from the sourceUri.
For more information, see
Put Block From URL.
public virtual Task<Response<BlockInfo>> StageBlockFromUriAsync(Uri sourceUri, string base64BlockId, HttpRange sourceRange, byte[] sourceContentHash, RequestConditions sourceConditions, BlobRequestConditions conditions, CancellationToken cancellationToken)
The StageBlockFromUriAsync
operation creates a new block to be committed as part of a blob where the contents are
read from the sourceUri.
For more information, see
Put Block From URL.
public virtual Response<BlobContentInfo> SyncUploadFromUri(Uri copySource, bool overwrite = false, CancellationToken cancellationToken = default)
The Upload from Uri operation creates a new Block Blob where the contents of the
blob are read from a given URL. This API is supported beginning with the 2020-04-08 version.
Partial updates are not supported with Put Blob from URL; the content of an existing blob is
overwritten with the content of the new blob. To perform partial updates to a block blob’s
contents using a source URL, use the Put Block from URL API in conjunction with Put Block List.
public virtual Response<BlobContentInfo> SyncUploadFromUri(Uri copySource, BlobSyncUploadFromUriOptions options, CancellationToken cancellationToken = default)
The Upload from Uri operation creates a new Block Blob where the contents of the
blob are read from a given URL. This API is supported beginning with the 2020-04-08 version.
Partial updates are not supported with Put Blob from URL; the content of an existing blob is
overwritten with the content of the new blob. To perform partial updates to a block blob’s
contents using a source URL, use the Put Block from URL API in conjunction with Put Block List.
public virtual Task<Response<BlobContentInfo>> SyncUploadFromUriAsync(Uri copySource, bool overwrite = false, CancellationToken cancellationToken = default)
The Upload from Uri operation creates a new Block Blob where the contents of the
blob are read from a given URL. This API is supported beginning with the 2020-04-08 version.
Partial updates are not supported with Put Blob from URL; the content of an existing blob is
overwritten with the content of the new blob. To perform partial updates to a block blob’s
contents using a source URL, use the Put Block from URL API in conjunction with Put Block List.
public virtual Task<Response<BlobContentInfo>> SyncUploadFromUriAsync(Uri copySource, BlobSyncUploadFromUriOptions options, CancellationToken cancellationToken = default)
The Upload from Uri operation creates a new Block Blob where the contents of the
blob are read from a given URL. This API is supported beginning with the 2020-04-08 version.
Partial updates are not supported with Put Blob from URL; the content of an existing blob is
overwritten with the content of the new blob. To perform partial updates to a block blob’s
contents using a source URL, use the Put Block from URL API in conjunction with Put Block List.
public virtual Response<BlobContentInfo> Upload(Stream content, BlobUploadOptions options, CancellationToken cancellationToken = default)
The Upload
operation overwrites the contents of the blob, creating a new block
blob if none exists. Overwriting an existing block blob replaces
any existing metadata on the blob.
Set access conditions through Conditions
to avoid overwriting existing data.
Partial updates are not supported with Upload;
the content of the existing blob is overwritten with the content
of the new blob. To perform a partial update of the content of a
block blob, use the StageBlock and
CommitBlockList operations.
For more information, see
Put Blob.
public virtual Response<BlobContentInfo> Upload(Stream content, BlobHttpHeaders httpHeaders = null, IDictionary<string, string> metadata = null, BlobRequestConditions conditions = null, AccessTier? accessTier = default, IProgress<long> progressHandler = null, CancellationToken cancellationToken = default)
The Upload
operation overwrites the contents of the blob, creating a new block
blob if none exists. Overwriting an existing block blob replaces
any existing metadata on the blob.
Set access conditions through BlobRequestConditions
to avoid overwriting existing data.
Partial updates are not supported with Upload;
the content of the existing blob is overwritten with the content
of the new blob. To perform a partial update of the content of a
block blob, use the StageBlock and
CommitBlockList operations.
For more information, see
Put Blob.
public virtual Task<Response<BlobContentInfo>> UploadAsync(Stream content, BlobUploadOptions options, CancellationToken cancellationToken = default)
The UploadAsync
operation overwrites the contents of the blob, creating a new block
blob if none exists. Overwriting an existing block blob replaces
any existing metadata on the blob.
Set access conditions through Conditions
to avoid overwriting existing data.
Partial updates are not supported with UploadAsync;
the content of the existing blob is overwritten with the content
of the new blob. To perform a partial update of the content of a
block blob, use the StageBlock and
CommitBlockListAsync operations.
For more information, see
Put Blob.
public virtual Task<Response<BlobContentInfo>> UploadAsync(Stream content, BlobHttpHeaders httpHeaders = null, IDictionary<string, string> metadata = null, BlobRequestConditions conditions = null, AccessTier? accessTier = default, IProgress<long> progressHandler = null, CancellationToken cancellationToken = default)
The UploadAsync
operation overwrites the contents of the blob, creating a new block
blob if none exists. Overwriting an existing block blob replaces
any existing metadata on the blob.
Set access conditions through BlobRequestConditions
to avoid overwriting existing data.
Partial updates are not supported with UploadAsync;
the content of the existing blob is overwritten with the content
of the new blob. To perform a partial update of the content of a
block blob, use the StageBlockAsync and
CommitBlockListAsync operations.
For more information, see
Put Blob.
Initializes a new instance of the BlockBlobClient
class with an identical Uri source but the specified
customerProvidedKey.
Initializes a new instance of the BlockBlobClient
class with an identical Uri source but the specified
encryptionScope.
Initializes a new instance of the BlockBlobClient
class with an identical Uri source but the specified
snapshot timestamp.
For more information, see
Create a snapshot of a blob.
Initializes a new instance of the BlockBlobClient
class with an identical Uri source but the specified
versionId timestamp.