|
| 1 | +--- |
| 2 | +title: Copy a blob with asynchronous scheduling using .NET |
| 3 | +titleSuffix: Azure Storage |
| 4 | +description: Learn how to copy a blob with asynchronous scheduling in Azure Storage by using the .NET client library. |
| 5 | +author: pauljewellmsft |
| 6 | + |
| 7 | +ms.author: pauljewell |
| 8 | +ms.date: 04/11/2023 |
| 9 | +ms.service: storage |
| 10 | +ms.subservice: blobs |
| 11 | +ms.topic: how-to |
| 12 | +ms.devlang: csharp |
| 13 | +ms.custom: devx-track-csharp, devguide-csharp |
| 14 | +--- |
| 15 | + |
| 16 | +# Copy a blob with asynchronous scheduling using .NET |
| 17 | + |
| 18 | +This article shows how to copy a blob with asynchronous scheduling using the [Azure Storage client library for .NET](/dotnet/api/overview/azure/storage). 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. |
| 19 | + |
| 20 | +The client library methods covered in this article use the [Copy Blob](/rest/api/storageservices/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](storage-blob-copy-url-dotnet.md). |
| 21 | + |
| 22 | +## Prerequisites |
| 23 | + |
| 24 | +To work with the code examples in this article, make sure you have: |
| 25 | + |
| 26 | +- An authorized client object to connect to Blob Storage data resources. To learn more, see [Create and manage client objects that interact with data resources](storage-blob-client-management.md). |
| 27 | +- Permissions to perform a copy operation. To learn more, see the authorization guidance for the following REST API operations: |
| 28 | + - [Copy Blob](/rest/api/storageservices/copy-blob#authorization) |
| 29 | + - [Abort Copy Blob](/rest/api/storageservices/abort-copy-blob#authorization) |
| 30 | +- Packages installed to your project directory. These examples use **Azure.Storage.Blobs**. If you're using `DefaultAzureCredential` for authorization, you also need **Azure.Identity**. To learn more about setting up your project, see [Get Started with Azure Storage and .NET](storage-blob-dotnet-get-started.md#set-up-your-project). To see the necessary `using` directives, see [Code samples](#code-samples). |
| 31 | + |
| 32 | +## About copying blobs with asynchronous scheduling |
| 33 | + |
| 34 | +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. |
| 35 | + |
| 36 | +A `Copy Blob` operation can perform any of the following actions: |
| 37 | + |
| 38 | +- 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. |
| 39 | +- 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. |
| 40 | +- 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. |
| 41 | +- 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. |
| 42 | +- Copy a snapshot to a destination blob with a different name. The resulting destination blob is a writeable blob and not a snapshot. |
| 43 | + |
| 44 | +The source blob for a copy operation may be one of the following types: block blob, append blob, page blob, blob snapshot, or blob version. The copy operation always copies the entire source blob or file. Copying a range of bytes or set of blocks isn't supported. |
| 45 | + |
| 46 | +If the destination blob already exists, it must be of the same blob type as the source blob, and the existing destination blob is overwritten. The destination blob can't be modified while a copy operation is in progress, and a destination blob can only have one outstanding copy operation. |
| 47 | + |
| 48 | +To learn more about the `Copy Blob` operation, including information about properties, index tags, metadata, and billing, see [Copy Blob remarks](/rest/api/storageservices/copy-blob#remarks). |
| 49 | + |
| 50 | +## Copy a blob with asynchronous scheduling |
| 51 | + |
| 52 | +This section gives an overview of methods provided by the Azure Storage client library for .NET to perform a copy operation with asynchronous scheduling. |
| 53 | + |
| 54 | +The following methods wrap the [Copy Blob](/rest/api/storageservices/copy-blob) REST API operation, and begin an asynchronous copy of data from the source blob: |
| 55 | + |
| 56 | +- [StartCopyFromUri](/dotnet/api/azure.storage.blobs.specialized.blobbaseclient.startcopyfromuri) |
| 57 | +- [StartCopyFromUriAsync](/dotnet/api/azure.storage.blobs.specialized.blobbaseclient.startcopyfromuriasync) |
| 58 | + |
| 59 | +The `StartCopyFromUri` and `StartCopyFromUriAsync` methods return a [CopyFromUriOperation](/dotnet/api/azure.storage.blobs.models.copyfromurioperation) object containing information about the copy operation. These methods are used when you want asynchronous scheduling for a copy operation. |
| 60 | + |
| 61 | +## Copy a blob within the same storage account |
| 62 | + |
| 63 | +If you're copying a blob within the same storage account, access to the source blob can be authorized via Azure Active Directory (Azure AD), a shared access signature (SAS), or an account key. The operation can complete synchronously if the copy occurs within the same storage account. |
| 64 | + |
| 65 | +The following example shows a scenario for copying a source blob within the same storage account. This 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. |
| 66 | + |
| 67 | +:::code language="csharp" source="~/azure-storage-snippets/blobs/howto/dotnet/BlobDevGuideBlobs/CopyBlob.cs" id="Snippet_CopyWithinAccount_CopyBlob"::: |
| 68 | + |
| 69 | +## Copy a blob from another storage account |
| 70 | + |
| 71 | +If the source is a blob in another storage account, 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](../common/storage-sas-overview.md). |
| 72 | + |
| 73 | +The following example shows a scenario for copying a blob from another storage account. In this example, we create a source blob URI with an appended service SAS token by calling [GenerateSasUri](/dotnet/api/azure.storage.blobs.blobcontainerclient.generatesasuri) on the blob client. To use this method, the source blob client needs to be authorized via account key. |
| 74 | + |
| 75 | +:::code language="csharp" source="~/azure-storage-snippets/blobs/howto/dotnet/BlobDevGuideBlobs/CopyBlob.cs" id="Snippet_CopyAcrossAccounts_CopyBlob"::: |
| 76 | + |
| 77 | +If you already have a SAS token, you can construct the URI for the source blob as follows: |
| 78 | + |
| 79 | +```csharp |
| 80 | +// Append the SAS token to the URI - include ? before the SAS token |
| 81 | +var sourceBlobSASURI = new Uri( |
| 82 | + $"https://{srcAccountName}.blob.core.windows.net/{srcContainerName}/{srcBlobName}?{sasToken}"); |
| 83 | +``` |
| 84 | + |
| 85 | +You can also [create a user delegation SAS token with .NET](storage-blob-user-delegation-sas-create-dotnet.md). User delegation SAS tokens offer greater security, as they're signed with Azure AD credentials instead of an account key. |
| 86 | + |
| 87 | +## Copy a blob from a source outside of Azure |
| 88 | + |
| 89 | +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. |
| 90 | + |
| 91 | +:::code language="csharp" source="~/azure-storage-snippets/blobs/howto/dotnet/BlobDevGuideBlobs/CopyBlob.cs" id="Snippet_CopyFromExternalSource_CopyBlob"::: |
| 92 | + |
| 93 | +## Check the status of a copy operation |
| 94 | + |
| 95 | +To check the status of a `Copy Blob` operation, you can call [UpdateStatusAsync](/dotnet/api/azure.storage.blobs.models.copyfromurioperation.updatestatusasync#azure-storage-blobs-models-copyfromurioperation-updatestatusasync(system-threading-cancellationtoken)) and parse the response to get the value for the `x-ms-copy-status` header. |
| 96 | + |
| 97 | +The following code example shows how to check the status of a copy operation: |
| 98 | + |
| 99 | +:::code language="csharp" source="~/azure-storage-snippets/blobs/howto/dotnet/BlobDevGuideBlobs/CopyBlob.cs" id="Snippet_CheckStatusCopyBlob"::: |
| 100 | + |
| 101 | +## Abort a copy operation |
| 102 | + |
| 103 | +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. |
| 104 | + |
| 105 | +To abort a pending copy operation, call one of the following operations: |
| 106 | +- [AbortCopyFromUri](/dotnet/api/azure.storage.blobs.specialized.blobbaseclient.abortcopyfromuri) |
| 107 | +- [AbortCopyFromUriAsync](/dotnet/api/azure.storage.blobs.specialized.blobbaseclient.abortcopyfromuriasync) |
| 108 | + |
| 109 | +These methods wrap the [Abort Copy Blob](/rest/api/storageservices/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: |
| 110 | + |
| 111 | +:::code language="csharp" source="~/azure-storage-snippets/blobs/howto/dotnet/BlobDevGuideBlobs/CopyBlob.cs" id="Snippet_AbortBlobCopy"::: |
| 112 | + |
| 113 | +## Resources |
| 114 | + |
| 115 | +To learn more about copying blobs using the Azure Blob Storage client library for .NET, see the following resources. |
| 116 | + |
| 117 | +### REST API operations |
| 118 | + |
| 119 | +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: |
| 120 | + |
| 121 | +- [Copy Blob](/rest/api/storageservices/copy-blob) (REST API) |
| 122 | +- [Abort Copy Blob](/rest/api/storageservices/abort-copy-blob) (REST API) |
| 123 | + |
| 124 | +### Code samples |
| 125 | + |
| 126 | +- [View code samples from this article (GitHub)](https://github.com/Azure-Samples/AzureStorageSnippets/blob/master/blobs/howto/dotnet/BlobDevGuideBlobs/CopyBlob.cs) |
| 127 | + |
| 128 | +[!INCLUDE [storage-dev-guide-resources-dotnet](../../../includes/storage-dev-guides/storage-dev-guide-resources-dotnet.md)] |
0 commit comments