Copy a blob with asynchronous scheduling using .NET
This article shows how to copy a blob with asynchronous scheduling using the Azure Storage client library for .NET. You can copy a blob from a source within the same storage account, from a source in a different storage account, or from any accessible object retrieved via HTTP GET request on a given URL. You can also abort a pending copy operation.
The client library methods covered in this article use the Copy Blob REST API operation, and can be used when you want to perform a copy with asynchronous scheduling. For most copy scenarios where you want to move data into a storage account and have a URL for the source object, see Copy a blob from a source object URL with .NET.
Prerequisites
- Azure subscription - create one for free
- Azure storage account - create a storage account
- Latest .NET SDK for your operating system. Be sure to get the SDK and not the runtime.
Set up your environment
If you don't have an existing project, this section shows you how to set up a project to work with the Azure Blob Storage client library for .NET. The steps include package installation, adding using
directives, and creating an authorized client object. For details, see Get started with Azure Blob Storage and .NET.
Install packages
From your project directory, install packages for the Azure Blob Storage and Azure Identity client libraries using the dotnet add package
command. The Azure.Identity package is needed for passwordless connections to Azure services.
dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity
Add using
directives
Add these using
directives to the top of your code file:
using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;
Some code examples in this article might require additional using
directives.
Create a client object
To connect an app to Blob Storage, create an instance of BlobServiceClient. The following example shows how to create a client object using DefaultAzureCredential
for authorization:
public BlobServiceClient GetBlobServiceClient(string accountName)
{
BlobServiceClient client = new(
new Uri($"https://{accountName}.blob.core.windows.net"),
new DefaultAzureCredential());
return client;
}
You can register a service client for dependency injection in a .NET app.
You can also create client objects for specific containers or blobs. To learn more about creating and managing client objects, see Create and manage client objects that interact with data resources.
Authorization
The authorization mechanism must have the necessary permissions to perform a copy operation, or to abort a pending copy. For authorization with Microsoft Entra ID (recommended), the least privileged Azure RBAC built-in role varies based on several factors. To learn more, see the authorization guidance for Copy Blob (REST API) or Abort Copy Blob (REST API).
About copying blobs with asynchronous scheduling
The Copy Blob
operation can finish asynchronously and is performed on a best-effort basis, which means that the operation isn't guaranteed to start immediately or complete within a specified time frame. The copy operation is scheduled in the background and performed as the server has available resources. The operation can complete synchronously if the copy occurs within the same storage account.
A Copy Blob
operation can perform any of the following actions:
- Copy a source blob to a destination blob with a different name. The destination blob can be an existing blob of the same blob type (block, append, or page), or it can be a new blob created by the copy operation.
- Copy a source blob to a destination blob with the same name, which replaces the destination blob. This type of copy operation removes any uncommitted blocks and overwrites the destination blob's metadata.
- Copy a source file in the Azure File service to a destination blob. The destination blob can be an existing block blob, or can be a new block blob created by the copy operation. Copying from files to page blobs or append blobs isn't supported.
- Copy a snapshot over its base blob. By promoting a snapshot to the position of the base blob, you can restore an earlier version of a blob.
- Copy a snapshot to a destination blob with a different name. The resulting destination blob is a writeable blob and not a snapshot.
To learn more about the Copy Blob
operation, including information about properties, index tags, metadata, and billing, see Copy Blob remarks.
Copy a blob with asynchronous scheduling
This section gives an overview of methods provided by the Azure Storage client library for .NET to perform a copy operation with asynchronous scheduling.
The following methods wrap the Copy Blob REST API operation, and begin an asynchronous copy of data from the source blob:
The StartCopyFromUri
and StartCopyFromUriAsync
methods return a CopyFromUriOperation object containing information about the copy operation. These methods are used when you want asynchronous scheduling for a copy operation.
Copy a blob from a source within Azure
If you're copying a blob within the same storage account, the operation can complete synchronously. Access to the source blob can be authorized via Microsoft Entra ID, a shared access signature (SAS), or an account key. For an alterative synchronous copy operation, see Copy a blob from a source object URL with .NET.
If the copy source is a blob in a different storage account, the operation can complete asynchronously. The source blob must either be public or authorized via SAS token. The SAS token needs to include the Read ('r') permission. To learn more about SAS tokens, see Delegate access with shared access signatures.
The following example shows a scenario for copying a source blob from a different storage account with asynchronous scheduling. In this example, we create a source blob URL with an appended user delegation SAS token. The example shows how to generate the SAS token using the client library, but you can also provide your own. The example also shows how to lease the source blob during the copy operation to prevent changes to the blob from a different client. The Copy Blob
operation saves the ETag
value of the source blob when the copy operation starts. If the ETag
value is changed before the copy operation finishes, the operation fails.
//-------------------------------------------------
// Copy a blob from a different storage account
//-------------------------------------------------
public static async Task CopyAcrossStorageAccountsAsync(
BlobClient sourceBlob,
BlockBlobClient destinationBlob)
{
// Lease the source blob to prevent changes during the copy operation
BlobLeaseClient sourceBlobLease = new(sourceBlob);
// Create a Uri object with a SAS token appended - specify Read (r) permissions
Uri sourceBlobSASURI = await GenerateUserDelegationSAS(sourceBlob);
try
{
await sourceBlobLease.AcquireAsync(BlobLeaseClient.InfiniteLeaseDuration);
// Start the copy operation and wait for it to complete
CopyFromUriOperation copyOperation = await destinationBlob.StartCopyFromUriAsync(sourceBlobSASURI);
await copyOperation.WaitForCompletionAsync();
}
catch (RequestFailedException ex)
{
// Handle the exception
}
finally
{
// Release the lease once the copy operation completes
await sourceBlobLease.ReleaseAsync();
}
}
async static Task<Uri> GenerateUserDelegationSAS(BlobClient sourceBlob)
{
BlobServiceClient blobServiceClient =
sourceBlob.GetParentBlobContainerClient().GetParentBlobServiceClient();
// Get a user delegation key for the Blob service that's valid for 1 day
UserDelegationKey userDelegationKey =
await blobServiceClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
DateTimeOffset.UtcNow.AddDays(1));
// Create a SAS token that's also valid for 1 day
BlobSasBuilder sasBuilder = new BlobSasBuilder()
{
BlobContainerName = sourceBlob.BlobContainerName,
BlobName = sourceBlob.Name,
Resource = "b",
StartsOn = DateTimeOffset.UtcNow,
ExpiresOn = DateTimeOffset.UtcNow.AddDays(1)
};
// Specify read permissions for the SAS
sasBuilder.SetPermissions(BlobSasPermissions.Read);
// Add the SAS token to the blob URI
BlobUriBuilder blobUriBuilder = new BlobUriBuilder(sourceBlob.Uri)
{
// Specify the user delegation key
Sas = sasBuilder.ToSasQueryParameters(userDelegationKey,
blobServiceClient.AccountName)
};
return blobUriBuilder.ToUri();
}
Note
User delegation SAS tokens offer greater security, as they're signed with Microsoft Entra credentials instead of an account key. To create a user delegation SAS token, the Microsoft Entra security principal needs appropriate permissions. For authorization requirements, see Get User Delegation Key.
Copy a blob from a source outside of Azure
You can perform a copy operation on any source object that can be retrieved via HTTP GET request on a given URL, including accessible objects outside of Azure. The following example shows a scenario for copying a blob from an accessible source object URL.
//-------------------------------------------------
// Copy a blob from an external source
//-------------------------------------------------
public static async Task CopyFromExternalSourceAsync(
string sourceLocation,
BlockBlobClient destinationBlob)
{
Uri sourceUri = new(sourceLocation);
// Start the copy operation and wait for it to complete
CopyFromUriOperation copyOperation = await destinationBlob.StartCopyFromUriAsync(sourceUri);
await copyOperation.WaitForCompletionAsync();
}
Check the status of a copy operation
To check the status of a Copy Blob
operation, you can call UpdateStatusAsync and parse the response to get the value for the x-ms-copy-status
header.
The following code example shows how to check the status of a copy operation:
public static async Task CheckCopyStatusAsync(CopyFromUriOperation copyOperation)
{
// Check for the latest status of the copy operation
Response response = await copyOperation.UpdateStatusAsync();
// Parse the response to find x-ms-copy-status header
if (response.Headers.TryGetValue("x-ms-copy-status", out string value))
Console.WriteLine($"Copy status: {value}");
}
Abort a copy operation
Aborting a pending Copy Blob
operation results in a destination blob of zero length. However, the metadata for the destination blob has the new values copied from the source blob or set explicitly during the copy operation. To keep the original metadata from before the copy, make a snapshot of the destination blob before calling one of the copy methods.
To abort a pending copy operation, call one of the following operations:
These methods wrap the Abort Copy Blob REST API operation, which cancels a pending Copy Blob
operation. The following code example shows how to abort a pending Copy Blob
operation:
public static async Task AbortBlobCopyAsync(
CopyFromUriOperation copyOperation,
BlobClient destinationBlob)
{
// Check for the latest status of the copy operation
Response response = await copyOperation.UpdateStatusAsync();
// Parse the response to find x-ms-copy-status header
if (response.Headers.TryGetValue("x-ms-copy-status", out string value))
{
if (value == "pending")
{
await destinationBlob.AbortCopyFromUriAsync(copyOperation.Id);
Console.WriteLine($"Copy operation {copyOperation.Id} aborted");
}
}
}
Resources
To learn more about copying blobs using the Azure Blob Storage client library for .NET, see the following resources.
Code samples
REST API operations
The Azure SDK for .NET contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar .NET paradigms. The client library methods covered in this article use the following REST API operations:
- Copy Blob (REST API)
- Abort Copy Blob (REST API)
Client library resources
Related content
- This article is part of the Blob Storage developer guide for .NET. To learn more, see the full list of developer guide articles at Build your .NET app.