Class PageBlobClient

The PageBlobClient allows you to manipulate Azure Storage page blobs.

Page blobs are a collection of 512-byte pages optimized for random read and write operations. To create a page blob, you initialize the page blob and specify the maximum size the page blob will grow. To add or update the contents of a page blob, you write a page or pages by specifying an offset and a range that align to 512-byte page boundaries. A write to a page blob can overwrite just one page, some pages, or up to 4 MB of the page blob. Writes to page blobs happen in-place and are immediately committed to the blob. The maximum size for a page blob is 8 TB.

Inheritance
Object
BlobBaseClient
PageBlobClient
Inherited Members
Namespace: Azure.Storage.Blobs.Specialized
Assembly: Azure.Storage.Blobs.dll
Syntax
public class PageBlobClient : Azure.Storage.Blobs.Specialized.BlobBaseClient

Constructors

PageBlobClient()

Initializes a new instance of the PageBlobClient class for mocking.

Declaration
protected PageBlobClient ();

PageBlobClient(Uri, BlobClientOptions)

Initializes a new instance of the PageBlobClient class.

Declaration
public PageBlobClient (Uri blobUri, Azure.Storage.Blobs.BlobClientOptions options = null);
Parameters
Uri blobUri

A Uri referencing the page blob that includes the name of the account, the name of the blob container, and the name of the blob.
BlobClientOptions options

Optional client options that define the transport pipeline policies for authentication, retries, etc., that are applied to every request.

PageBlobClient(String, String, String)

Initializes a new instance of the PageBlobClient class.

Declaration
public PageBlobClient (string connectionString, string blobContainerName, string blobName);
Parameters
String connectionString

A connection string includes the authentication information required for your application to access data in an Azure Storage account at runtime.

For more information, .
String blobContainerName

The name of the container containing this page blob.
String blobName

The name of this page blob.

PageBlobClient(Uri, TokenCredential, BlobClientOptions)

Initializes a new instance of the PageBlobClient class.

Declaration
public PageBlobClient (Uri blobUri, Azure.Core.TokenCredential credential, Azure.Storage.Blobs.BlobClientOptions options = null);
Parameters
Uri blobUri

A Uri referencing the page blob that includes the name of the account, the name of the blob container, and the name of the blob.
TokenCredential credential

The token credential used to sign requests.
BlobClientOptions options

Optional client options that define the transport pipeline policies for authentication, retries, etc., that are applied to every request.

PageBlobClient(Uri, StorageSharedKeyCredential, BlobClientOptions)

Initializes a new instance of the PageBlobClient class.

Declaration
public PageBlobClient (Uri blobUri, Azure.Storage.StorageSharedKeyCredential credential, Azure.Storage.Blobs.BlobClientOptions options = null);
Parameters
Uri blobUri

A Uri referencing the page blob that includes the name of the account, the name of the blob container, and the name of the blob.
StorageSharedKeyCredential credential

The shared key credential used to sign requests.
BlobClientOptions options

Optional client options that define the transport pipeline policies for authentication, retries, etc., that are applied to every request.

PageBlobClient(String, String, String, BlobClientOptions)

Initializes a new instance of the PageBlobClient class.

Declaration
public PageBlobClient (string connectionString, string blobContainerName, string blobName, Azure.Storage.Blobs.BlobClientOptions options);
Parameters
String connectionString

A connection string includes the authentication information required for your application to access data in an Azure Storage account at runtime.

For more information, .
String blobContainerName

The name of the container containing this page blob.
String blobName

The name of this page blob.
BlobClientOptions options

Optional client options that define the transport pipeline policies for authentication, retries, etc., that are applied to every request.

Properties

PageBlobMaxUploadPagesBytes

Gets the maximum number of bytes that can be sent in a call to the UploadPagesAsync(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken) operation.

Declaration
public virtual int PageBlobMaxUploadPagesBytes { get; }
Property Value
Int32

PageBlobPageBytes

Gets the number of bytes in a page (512).

Declaration
public virtual int PageBlobPageBytes { get; }
Property Value
Int32

Methods

ClearPages(HttpRange, PageBlobRequestConditions, CancellationToken)

The ClearPages(HttpRange, PageBlobRequestConditions, CancellationToken) operation clears one or more pages from the page blob, as specificed by the range.

For more information, see .

Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.PageInfo> ClearPages (Azure.HttpRange range, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
HttpRange range

Specifies the range of bytes to be cleared. Both the start and end of the range must be specified. For a page clear operation, the page range can be up to the value of the blob's full size. Given that pages must be aligned with 512-byte boundaries, the start of the range must be a modulus of 512 and the end of the range must be a modulus of 512 – 1. Examples of valid byte ranges are 0-511, 512-1023, etc.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on clearing pages from this page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Response<PageInfo>

A Response<T> describing the state of the updated pages.
Remarks

A RequestFailedException will be thrown if a failure occurs.

ClearPagesAsync(HttpRange, PageBlobRequestConditions, CancellationToken)

The ClearPagesAsync(HttpRange, PageBlobRequestConditions, CancellationToken) operation clears one or more pages from the page blob, as specificed by the range.

For more information, see .

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.PageInfo>> ClearPagesAsync (Azure.HttpRange range, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
HttpRange range

Specifies the range of bytes to be cleared. Both the start and end of the range must be specified. For a page clear operation, the page range can be up to the value of the blob's full size. Given that pages must be aligned with 512-byte boundaries, the start of the range must be a modulus of 512 and the end of the range must be a modulus of 512 – 1. Examples of valid byte ranges are 0-511, 512-1023, etc.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on clearing pages from this page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Task<Response<PageInfo>>

A Response<T> describing the state of the updated pages.
Remarks

A RequestFailedException will be thrown if a failure occurs.

Create(Int64, Nullable<Int64>, BlobHttpHeaders, IDictionary<String,String>, PageBlobRequestConditions, CancellationToken)

The Create(Int64, Nullable<Int64>, BlobHttpHeaders, IDictionary<String,String>, PageBlobRequestConditions, CancellationToken) operation creates a new page blob of the specified size. The content of any existing blob is overwritten with the newly initialized page blob To add content to the page blob, call the UploadPages(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken) operation.

For more information, see https://docs.microsoft.com/rest/api/storageservices/put-blob.

Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.BlobContentInfo> Create (long size, Nullable<long> sequenceNumber = null, Azure.Storage.Blobs.Models.BlobHttpHeaders httpHeaders = null, System.Collections.Generic.IDictionary<string,string> metadata = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Int64 size

Specifies the maximum size for the page blob, up to 8 TB. The size must be aligned to a 512-byte boundary.
Nullable<Int64> sequenceNumber

Optional user-controlled value that you can use to track requests. The value of the sequenceNumber must be between 0 and 2^63 - 1. The default value is 0.
BlobHttpHeaders httpHeaders

Optional standard HTTP header properties that can be set for the new page blob.
IDictionary<String,String> metadata

Optional custom metadata to set for this page blob.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on the creation of this new page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Response<BlobContentInfo>

A Response<T> describing the newly created page blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

CreateAsync(Int64, Nullable<Int64>, BlobHttpHeaders, IDictionary<String,String>, PageBlobRequestConditions, CancellationToken)

The CreateAsync(Int64, Nullable<Int64>, BlobHttpHeaders, IDictionary<String,String>, PageBlobRequestConditions, CancellationToken) operation creates a new page blob of the specified size. The content of any existing blob is overwritten with the newly initialized page blob To add content to the page blob, call the UploadPagesAsync(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken) operation.

For more information, see https://docs.microsoft.com/rest/api/storageservices/put-blob.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.BlobContentInfo>> CreateAsync (long size, Nullable<long> sequenceNumber = null, Azure.Storage.Blobs.Models.BlobHttpHeaders httpHeaders = null, System.Collections.Generic.IDictionary<string,string> metadata = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Int64 size

Specifies the maximum size for the page blob, up to 8 TB. The size must be aligned to a 512-byte boundary.
Nullable<Int64> sequenceNumber

Optional user-controlled value that you can use to track requests. The value of the sequenceNumber must be between 0 and 2^63 - 1. The default value is 0.
BlobHttpHeaders httpHeaders

Optional standard HTTP header properties that can be set for the new page blob.
IDictionary<String,String> metadata

Optional custom metadata to set for this page blob.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on the creation of this new page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Task<Response<BlobContentInfo>>

A Response<T> describing the newly created page blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

CreateIfNotExists(Int64, Nullable<Int64>, BlobHttpHeaders, IDictionary<String,String>, CancellationToken)

The CreateIfNotExists(Int64, Nullable<Int64>, BlobHttpHeaders, IDictionary<String,String>, CancellationToken) operation creates a new page blob of the specified size. If the blob already exists, the content of the existing blob will remain unchanged. If the blob does not already exists, a new page blob with the specified size will be created. UploadPages(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken) operation.

For more information, see https://docs.microsoft.com/rest/api/storageservices/put-blob.

Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.BlobContentInfo> CreateIfNotExists (long size, Nullable<long> sequenceNumber = null, Azure.Storage.Blobs.Models.BlobHttpHeaders httpHeaders = null, System.Collections.Generic.IDictionary<string,string> metadata = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Int64 size

Specifies the maximum size for the page blob, up to 8 TB. The size must be aligned to a 512-byte boundary.
Nullable<Int64> sequenceNumber

Optional user-controlled value that you can use to track requests. The value of the sequenceNumber must be between 0 and 2^63 - 1. The default value is 0.
BlobHttpHeaders httpHeaders

Optional standard HTTP header properties that can be set for the new page blob.
IDictionary<String,String> metadata

Optional custom metadata to set for this page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Response<BlobContentInfo>

A Response<T> describing the newly created page blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

CreateIfNotExistsAsync(Int64, Nullable<Int64>, BlobHttpHeaders, IDictionary<String,String>, CancellationToken)

The CreateIfNotExistsAsync(Int64, Nullable<Int64>, BlobHttpHeaders, IDictionary<String,String>, CancellationToken) operation creates a new page blob of the specified size. If the blob already exists, the content of the existing blob will remain unchanged. If the blob does not already exists, a new page blob with the specified size will be created. UploadPagesAsync(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken) operation.

For more information, see https://docs.microsoft.com/rest/api/storageservices/put-blob.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.BlobContentInfo>> CreateIfNotExistsAsync (long size, Nullable<long> sequenceNumber = null, Azure.Storage.Blobs.Models.BlobHttpHeaders httpHeaders = null, System.Collections.Generic.IDictionary<string,string> metadata = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Int64 size

Specifies the maximum size for the page blob, up to 8 TB. The size must be aligned to a 512-byte boundary.
Nullable<Int64> sequenceNumber

Optional user-controlled value that you can use to track requests. The value of the sequenceNumber must be between 0 and 2^63 - 1. The default value is 0.
BlobHttpHeaders httpHeaders

Optional standard HTTP header properties that can be set for the new page blob.
IDictionary<String,String> metadata

Optional custom metadata to set for this page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Task<Response<BlobContentInfo>>

A Response<T> describing the newly created page blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

GetPageRanges(Nullable<HttpRange>, String, PageBlobRequestConditions, CancellationToken)

The GetPageRanges(Nullable<HttpRange>, String, PageBlobRequestConditions, CancellationToken) operation returns the list of valid page ranges for a page blob or snapshot of a page blob.

For more information, see .

Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.PageRangesInfo> GetPageRanges (Nullable<Azure.HttpRange> range = null, string snapshot = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Nullable<HttpRange> range

Optionally specifies the range of bytes over which to list ranges, inclusively. If omitted, then all ranges for the blob are returned.
String snapshot

Optionally specifies the blob snapshot to retrieve page ranges information from. For more information on working with blob snapshots, .
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on getting page ranges for the this blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Response<PageRangesInfo>

A Response<T> describing the valid page ranges for this blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

GetPageRangesAsync(Nullable<HttpRange>, String, PageBlobRequestConditions, CancellationToken)

The GetPageRangesAsync(Nullable<HttpRange>, String, PageBlobRequestConditions, CancellationToken) operation returns the list of valid page ranges for a page blob or snapshot of a page blob.

For more information, see .

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.PageRangesInfo>> GetPageRangesAsync (Nullable<Azure.HttpRange> range = null, string snapshot = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Nullable<HttpRange> range

Optionally specifies the range of bytes over which to list ranges, inclusively. If omitted, then all ranges for the blob are returned.
String snapshot

Optionally specifies the blob snapshot to retrieve page ranges information from. For more information on working with blob snapshots, .
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on getting page ranges for the this blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Task<Response<PageRangesInfo>>

A Response<T> describing the valid page ranges for this blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

GetPageRangesDiff(Nullable<HttpRange>, String, String, PageBlobRequestConditions, CancellationToken)

The GetPageRangesDiff(Nullable<HttpRange>, String, String, PageBlobRequestConditions, CancellationToken) operation returns the list of page ranges that differ between a previousSnapshot and this page blob. Changed pages include both updated and cleared pages.

For more information, see .

Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.PageRangesInfo> GetPageRangesDiff (Nullable<Azure.HttpRange> range = null, string snapshot = null, string previousSnapshot = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Nullable<HttpRange> range

Optionally specifies the range of bytes over which to list ranges, inclusively. If omitted, then all ranges for the blob are returned.
String snapshot

Optionally specifies the blob snapshot to retrieve page ranges information from. For more information on working with blob snapshots, .
String previousSnapshot

Specifies that the response will contain only pages that were changed between target blob and previous snapshot. Changed pages include both updated and cleared pages. The target blob may be a snapshot, as long as the snapshot specified by previousSnapshot is the older of the two.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on getting page ranges for the this blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Response<PageRangesInfo>

A Response<T> describing the valid page ranges for this blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

GetPageRangesDiffAsync(Nullable<HttpRange>, String, String, PageBlobRequestConditions, CancellationToken)

The GetPageRangesDiffAsync(Nullable<HttpRange>, String, String, PageBlobRequestConditions, CancellationToken) operation returns the list of page ranges that differ between a previousSnapshot and this page blob. Changed pages include both updated and cleared pages.

For more information, see .

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.PageRangesInfo>> GetPageRangesDiffAsync (Nullable<Azure.HttpRange> range = null, string snapshot = null, string previousSnapshot = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Nullable<HttpRange> range

Optionally specifies the range of bytes over which to list ranges, inclusively. If omitted, then all ranges for the blob are returned.
String snapshot

Optionally specifies the blob snapshot to retrieve page ranges information from. For more information on working with blob snapshots, .
String previousSnapshot

Specifies that the response will contain only pages that were changed between target blob and previous snapshot. Changed pages include both updated and cleared pages. The target blob may be a snapshot, as long as the snapshot specified by previousSnapshot is the older of the two.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on getting page ranges for the this blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Task<Response<PageRangesInfo>>

A Response<T> describing the valid page ranges for this blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

Resize(Int64, PageBlobRequestConditions, CancellationToken)

The Resize(Int64, PageBlobRequestConditions, CancellationToken) operation resizes the page blob to the specified size (which must be a multiple of 512). If the specified value is less than the current size of the blob, then all pages above the specified value are cleared.

For more information, see .

Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.PageBlobInfo> Resize (long size, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Int64 size

Specifies the maximum size for the page blob, up to 8 TB. The size must be aligned to a 512-byte boundary. If the specified value is less than the current size of the blob, then all pages above the specified value are cleared.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on the resize of this page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Response<PageBlobInfo>

A Response<T> describing the resized page blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

ResizeAsync(Int64, PageBlobRequestConditions, CancellationToken)

The ResizeAsync(Int64, PageBlobRequestConditions, CancellationToken) operation resizes the page blob to the specified size (which must be a multiple of 512). If the specified value is less than the current size of the blob, then all pages above the specified value are cleared.

For more information, see .

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.PageBlobInfo>> ResizeAsync (long size, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Int64 size

Specifies the maximum size for the page blob, up to 8 TB. The size must be aligned to a 512-byte boundary. If the specified value is less than the current size of the blob, then all pages above the specified value are cleared.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on the resize of this page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Task<Response<PageBlobInfo>>

A Response<T> describing the resized page blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

StartCopyIncremental(Uri, String, PageBlobRequestConditions, CancellationToken)

The StartCopyIncremental(Uri, String, PageBlobRequestConditions, CancellationToken) operation starts copying a snapshot of the sourceUri page blob to this page blob. The snapshot is copied such that only the differential changes between the previously copied snapshot are transferred to the destination. The copied snapshots are complete copies of the original snapshot and can be read or copied from as usual. You can check the CopyStatus returned from the GetProperties(BlobRequestConditions, CancellationToken) to determine if the copy has completed.

For more information, see and .

Declaration
public virtual Azure.Storage.Blobs.Models.CopyFromUriOperation StartCopyIncremental (Uri sourceUri, string snapshot, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Uri sourceUri

Specifies the to the source page blob as a Uri up to 2 KB in length. The source blob must either be public or must be authenticated via a shared access signature.
String snapshot

The name of a snapshot to start copying from sourceUri.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on the incremental copy into this page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
CopyFromUriOperation

A CopyFromUriOperation referencing the incremental copy operation.
Remarks

A RequestFailedException will be thrown if a failure occurs.

The destination of an incremental copy must either not exist, or must have been created with a previous incremental copy from the same source blob. Once created, the destination blob is permanently associated with the source and may only be used for incremental copies.

The GetProperties(BlobRequestConditions, CancellationToken), GetBlobs(BlobTraits, BlobStates, String, CancellationToken), and GetBlobsByHierarchy(BlobTraits, BlobStates, String, String, CancellationToken) operations indicate whether the blob is an incremental copy blob created in this way. Incremental copy blobs may not be downloaded directly. The only supported operations are GetProperties(BlobRequestConditions, CancellationToken), StartCopyIncremental(Uri, String, PageBlobRequestConditions, CancellationToken), and Delete(DeleteSnapshotsOption, BlobRequestConditions, CancellationToken). The copied snapshots may be read and deleted as usual.

An incremental copy is performed asynchronously on the service and must be polled for completion. You can poll GetProperties(BlobRequestConditions, CancellationToken) and check CopyStatus to determine when the copy has completed. When the copy completes, the destination blob will contain a new snapshot. The GetProperties(BlobRequestConditions, CancellationToken) operation returns the snapshot time of the newly created snapshot.

The first time an incremental copy is performed on a destination blob, a new blob is created with a snapshot that is fully copied from the source. Each subsequent call to StartCopyIncremental(Uri, String, PageBlobRequestConditions, CancellationToken) will create a new snapshot by copying only the differential changes from the previously copied snapshot. The differential changes are computed on the server by issuing a GetPageRanges(Nullable<HttpRange>, String, PageBlobRequestConditions, CancellationToken) call on the source blob snapshot with prevSnapshot set to the most recently copied snapshot. Therefore, the same restrictions on GetPageRanges(Nullable<HttpRange>, String, PageBlobRequestConditions, CancellationToken) apply to StartCopyIncremental(Uri, String, PageBlobRequestConditions, CancellationToken). Specifically, snapshots must be copied in ascending order and if the source blob is recreated using UploadPages(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken) or StartCopyFromUri(Uri, IDictionary<String,String>, Nullable<AccessTier>, BlobRequestConditions, BlobRequestConditions, Nullable<RehydratePriority>, CancellationToken) then StartCopyIncremental(Uri, String, PageBlobRequestConditions, CancellationToken) on new snapshots will fail.

The additional storage space consumed by the copied snapshot is the size of the differential data transferred during the copy. This can be determined by performing a GetPageRangesDiff(Nullable<HttpRange>, String, String, PageBlobRequestConditions, CancellationToken) call on the snapshot to compare it to the previous snapshot.

StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken)

The StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken) operation starts copying a snapshot of the sourceUri page blob to this page blob. The snapshot is copied such that only the differential changes between the previously copied snapshot are transferred to the destination. The copied snapshots are complete copies of the original snapshot and can be read or copied from as usual. You can check the CopyStatus returned from the GetPropertiesAsync(BlobRequestConditions, CancellationToken) to determine if thecopy has completed.

For more information, see and .

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Storage.Blobs.Models.CopyFromUriOperation> StartCopyIncrementalAsync (Uri sourceUri, string snapshot, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Uri sourceUri

Specifies the to the source page blob as a Uri up to 2 KB in length. The source blob must either be public or must be authenticated via a shared access signature.
String snapshot

The name of a snapshot to start copying from sourceUri.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on the incremental copy into this page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Task<CopyFromUriOperation>

A CopyFromUriOperation describing the state of the incremental copy operation.
Remarks

A RequestFailedException will be thrown if a failure occurs.

The destination of an incremental copy must either not exist, or must have been created with a previous incremental copy from the same source blob. Once created, the destination blob is permanently associated with the source and may only be used for incremental copies.

The GetPropertiesAsync(BlobRequestConditions, CancellationToken), GetBlobsAsync(BlobTraits, BlobStates, String, CancellationToken), and GetBlobsByHierarchyAsync(BlobTraits, BlobStates, String, String, CancellationToken) operations indicate whether the blob is an incremental copy blob created in this way. Incremental copy blobs may not be downloaded directly. The only supported operations are GetPropertiesAsync(BlobRequestConditions, CancellationToken), StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken), and DeleteAsync(DeleteSnapshotsOption, BlobRequestConditions, CancellationToken). The copied snapshots may be read and deleted as usual.

An incremental copy is performed asynchronously on the service and must be polled for completion. You can poll GetPropertiesAsync(BlobRequestConditions, CancellationToken) and check CopyStatus to determine when the copy has completed. When the copy completes, the destination blob will contain a new snapshot. The GetPropertiesAsync(BlobRequestConditions, CancellationToken) operation returns the snapshot time of the newly created snapshot.

The first time an incremental copy is performed on a destination blob, a new blob is created with a snapshot that is fully copied from the source. Each subsequent call to StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken) will create a new snapshot by copying only the differential changes from the previously copied snapshot. The differential changes are computed on the server by issuing a GetPageRangesAsync(Nullable<HttpRange>, String, PageBlobRequestConditions, CancellationToken) call on the source blob snapshot with prevSnapshot set to the most recently copied snapshot. Therefore, the same restrictions on GetPageRangesAsync(Nullable<HttpRange>, String, PageBlobRequestConditions, CancellationToken) apply to StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken). Specifically, snapshots must be copied in ascending order and if the source blob is recreated using UploadPagesAsync(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken) or StartCopyFromUriAsync(Uri, IDictionary<String,String>, Nullable<AccessTier>, BlobRequestConditions, BlobRequestConditions, Nullable<RehydratePriority>, CancellationToken) then StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken) on new snapshots will fail.

The additional storage space consumed by the copied snapshot is the size of the differential data transferred during the copy. This can be determined by performing a GetPageRangesDiffAsync(Nullable<HttpRange>, String, String, PageBlobRequestConditions, CancellationToken) call on the snapshot to compare it to the previous snapshot.

UpdateSequenceNumber(SequenceNumberAction, Nullable<Int64>, PageBlobRequestConditions, CancellationToken)

The UpdateSequenceNumber(SequenceNumberAction, Nullable<Int64>, PageBlobRequestConditions, CancellationToken) operation changes the sequence number action and sequenceNumber for this page blob.

For more information, see .

Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.PageBlobInfo> UpdateSequenceNumber (Azure.Storage.Blobs.Models.SequenceNumberAction action, Nullable<long> sequenceNumber = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
SequenceNumberAction action

Specifies how the service should modify the blob's sequence number. Max sets the sequence number to be the higher of the value included with the request and the value currently stored for the blob. Update sets the sequence number to the sequenceNumber value. Increment increments the value of the sequence number by 1. If specifying Increment, do not include the sequenceNumber because that will throw a RequestFailedException.
Nullable<Int64> sequenceNumber

An updated sequence number of your choosing, if action is Max or Update. The value should not be provided if action is Increment. The sequence number is a user-controlled property that you can use to track requests and manage concurrency issues via PageBlobRequestConditions.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on updating the sequence number of this page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Response<PageBlobInfo>

A Response<T> describing the updated page blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

UpdateSequenceNumberAsync(SequenceNumberAction, Nullable<Int64>, PageBlobRequestConditions, CancellationToken)

The UpdateSequenceNumberAsync(SequenceNumberAction, Nullable<Int64>, PageBlobRequestConditions, CancellationToken) operation changes the sequence number action and sequenceNumber for this page blob.

For more information, see .

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.PageBlobInfo>> UpdateSequenceNumberAsync (Azure.Storage.Blobs.Models.SequenceNumberAction action, Nullable<long> sequenceNumber = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
SequenceNumberAction action

Specifies how the service should modify the blob's sequence number. Max sets the sequence number to be the higher of the value included with the request and the value currently stored for the blob. Update sets the sequence number to the sequenceNumber value. Increment increments the value of the sequence number by 1. If specifying Increment, do not include the sequenceNumber because that will throw a RequestFailedException.
Nullable<Int64> sequenceNumber

An updated sequence number of your choosing, if action is Max or Update. The value should not be provided if action is Increment. The sequence number is a user-controlled property that you can use to track requests and manage concurrency issues via PageBlobRequestConditions.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on updating the sequence number of this page blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Task<Response<PageBlobInfo>>

A Response<T> describing the updated page blob.
Remarks

A RequestFailedException will be thrown if a failure occurs.

UploadPages(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken)

The UploadPages(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken) operation writes content to a range of pages in a page blob, starting at offset.

For more information, see .

Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.PageInfo> UploadPages (System.IO.Stream content, long offset, byte[] transactionalContentHash = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, IProgress<long> progressHandler = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Stream content

A Stream containing the content of the pages to upload. The content can be up to 4 MB in size.
Int64 offset

Specifies the starting offset for the content to be written as a page. Given that pages must be aligned with 512-byte boundaries, the start offset must be a modulus of 512.
Byte[] transactionalContentHash

Optional MD5 hash of the block content. This hash is used to verify the integrity of the block during transport. When this hash is specified, the storage service compares the hash of the content that has arrived with this value. Note that this MD5 hash is not stored with the blob. If the two hashes do not match, the operation will fail with a RequestFailedException.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on uploading pages to this page blob.
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
Response<PageInfo>

A Response<T> describing the state of the updated pages.
Remarks

A RequestFailedException will be thrown if a failure occurs.

UploadPagesAsync(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken)

The UploadPagesAsync(Stream, Int64, Byte[], PageBlobRequestConditions, IProgress<Int64>, CancellationToken) operation writes content to a range of pages in a page blob, starting at offset.

For more information, see .

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.PageInfo>> UploadPagesAsync (System.IO.Stream content, long offset, byte[] transactionalContentHash = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, IProgress<long> progressHandler = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Stream content

A Stream containing the content of the pages to upload. The content can be up to 4 MB in size.
Int64 offset

Specifies the starting offset for the content to be written as a page. Given that pages must be aligned with 512-byte boundaries, the start offset must be a modulus of 512.
Byte[] transactionalContentHash

Optional MD5 hash of the block content. This hash is used to verify the integrity of the block during transport. When this hash is specified, the storage service compares the hash of the content that has arrived with this value. Note that this MD5 hash is not stored with the blob. If the two hashes do not match, the operation will fail with a RequestFailedException.
PageBlobRequestConditions conditions

Optional PageBlobRequestConditions to add conditions on uploading pages to this page blob.
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
Task<Response<PageInfo>>

A Response<T> describing the state of the updated pages.
Remarks

A RequestFailedException will be thrown if a failure occurs.

UploadPagesFromUri(Uri, HttpRange, HttpRange, Byte[], PageBlobRequestConditions, PageBlobRequestConditions, CancellationToken)

The UploadPagesFromUri(Uri, HttpRange, HttpRange, Byte[], PageBlobRequestConditions, PageBlobRequestConditions, CancellationToken) operation writes a range of pages to a page blob where the contents are read from sourceUri.

For more information, see .

Declaration
public virtual Azure.Response<Azure.Storage.Blobs.Models.PageInfo> UploadPagesFromUri (Uri sourceUri, Azure.HttpRange sourceRange, Azure.HttpRange range, byte[] sourceContentHash = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions sourceConditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Uri sourceUri

Specifies the Uri of the source blob. The value may be a Uri 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.
HttpRange sourceRange

Optionally only upload the bytes of the blob in the sourceUri in the specified range.
HttpRange range

Specifies the range to be written as a page. Both the start and end of the range must be specified and can be up to 4MB in size. Given that pages must be aligned with 512-byte boundaries, the start of the range must be a modulus of 512 and the end of the range must be a modulus of 512 – 1. Examples of valid byte ranges are 0-511, 512-1023, etc.
Byte[] sourceContentHash

Optional MD5 hash of the page block content from the sourceUri. This hash is used to verify the integrity of the block during transport of the data from the Uri. When this hash is specified, the storage service compares the hash of the content that has arrived from the sourceUri with this value. Note that this md5 hash is not stored with the blob. If the two hashes do not match, the operation will fail with a RequestFailedException.
PageBlobRequestConditions conditions

Optional AppendBlobRequestConditions to add conditions on the copying of data to this page blob.
PageBlobRequestConditions sourceConditions

Optional AppendBlobRequestConditions to add conditions on the copying of data from this source blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Response<PageInfo>

A Response<T> describing the state of the updated pages.
Remarks

A RequestFailedException will be thrown if a failure occurs.

UploadPagesFromUriAsync(Uri, HttpRange, HttpRange, Byte[], PageBlobRequestConditions, PageBlobRequestConditions, CancellationToken)

The UploadPagesFromUriAsync(Uri, HttpRange, HttpRange, Byte[], PageBlobRequestConditions, PageBlobRequestConditions, CancellationToken) operation writes a range of pages to a page blob where the contents are read from sourceUri.

For more information, see .

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Storage.Blobs.Models.PageInfo>> UploadPagesFromUriAsync (Uri sourceUri, Azure.HttpRange sourceRange, Azure.HttpRange range, byte[] sourceContentHash = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = null, Azure.Storage.Blobs.Models.PageBlobRequestConditions sourceConditions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
Uri sourceUri

Specifies the Uri of the source blob. The value may be a Uri 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.
HttpRange sourceRange

Optionally only upload the bytes of the blob in the sourceUri in the specified range.
HttpRange range

Specifies the range to be written as a page. Both the start and end of the range must be specified and can be up to 4MB in size. Given that pages must be aligned with 512-byte boundaries, the start of the range must be a modulus of 512 and the end of the range must be a modulus of 512 – 1. Examples of valid byte ranges are 0-511, 512-1023, etc.
Byte[] sourceContentHash

Optional MD5 hash of the page block content from the sourceUri. This hash is used to verify the integrity of the block during transport of the data from the Uri. When this hash is specified, the storage service compares the hash of the content that has arrived from the sourceUri with this value. Note that this md5 hash is not stored with the blob. If the two hashes do not match, the operation will fail with a RequestFailedException.
PageBlobRequestConditions conditions

Optional AppendBlobRequestConditions to add conditions on the copying of data to this page blob.
PageBlobRequestConditions sourceConditions

Optional AppendBlobRequestConditions to add conditions on the copying of data from this source blob.
CancellationToken cancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.
Returns
Task<Response<PageInfo>>

A Response<T> describing the state of the updated pages.
Remarks

A RequestFailedException will be thrown if a failure occurs.

WithSnapshot(String)

Initializes a new instance of the PageBlobClient class with an identical Uri source but the specified snapshot timestamp.

For more information, see .

Declaration
public Azure.Storage.Blobs.Specialized.PageBlobClient WithSnapshot (string snapshot);
Parameters
String snapshot

The snapshot identifier.
Returns
PageBlobClient

A new PageBlobClient instance.
Remarks

Pass null or empty string to remove the snapshot returning a URL

to the base blob.

WithSnapshotCore(String)

Creates a new instance of the PageBlobClient class with an identical Uri source but the specified snapshot timestamp.

Declaration
protected override sealed Azure.Storage.Blobs.Specialized.BlobBaseClient WithSnapshotCore (string snapshot);
Parameters
String snapshot

The snapshot identifier.
Returns
BlobBaseClient

A new PageBlobClient instance.

Extension Methods