Skip to content

Commit 167fbd7

Browse files
huypubhuypub
authored
Merge pull request #92231 from MicrosoftDocs/release-blob-developer-guide
Release blob developer guide
2 parents 86d2bd5 + e883da3 commit 167fbd7

File tree

6 files changed

+557
-43
lines changed

6 files changed

+557
-43
lines changed

‎articles/storage/blobs/TOC.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,16 @@
248248
href: storage-blob-containers-list.md
249249
- name: Manage properties and metadata (.NET)
250250
href: storage-blob-container-properties-metadata.md
251+
- name: Create and manage blobs
252+
items:
253+
- name: List blobs (.NET)
254+
href: storage-blobs-list.md
255+
- name: Manage blob properties and metadata (.NET)
256+
href: storage-blob-properties-metadata.md
257+
- name: Copy a blob (.NET)
258+
href: storage-blob-copy.md
259+
- name: Create and manage blob snapshots (.NET)
260+
href: storage-blob-snapshots.md
251261
- name: Secure blob data
252262
items:
253263
- name: Authorize access to blob data

‎articles/storage/blobs/storage-blob-containers-list.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,9 @@ In your code, check the value of the continuation token to determine whether it
3636

3737
To filter the list of containers, specify a string for the `prefix` parameter. The prefix string can include one or more characters. Azure Storage then returns only the containers whose names start with that prefix.
3838

39-
### Return container metadata
39+
### Return metadata
4040

41-
To return container metadata with the results, specify the **Metadata** value for the [ContainerListDetails](/dotnet/api/microsoft.azure.storage.blob.containerlistingdetails) enumeration. Azure Storage includes metadata with each container returned, so you do not need to also call one of the **FetchAttributes** methods to retrieve the container metadata.
41+
To return container metadata with the results, specify the **Metadata** value for the [ContainerListingDetails](/dotnet/api/microsoft.azure.storage.blob.containerlistingdetails) enumeration. Azure Storage includes metadata with each container returned, so you do not need to also call one of the **FetchAttributes** methods to retrieve the container metadata.
4242

4343
## Example: List containers
4444

‎articles/storage/blobs/storage-blob-copy.md

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
title: Copy a blob with .NET - Azure Storage
3+
description: Learn how to copy a blob in your Azure Storage account using the .NET client library.
4+
services: storage
5+
author: mhopkins-msft
6+
7+
ms.author: mhopkins
8+
ms.date: 08/20/2019
9+
ms.service: storage
10+
ms.subservice: blobs
11+
ms.topic: conceptual
12+
---
13+
14+
# Copy a blob with .NET
15+
16+
This article demonstrates how to copy a blob with an Azure Storage account. It also shows how to abort an asynchronous copy operation. The example code uses the [Azure Storage client library for .NET](/dotnet/api/overview/azure/storage/client).
17+
18+
## About copying blobs
19+
20+
When you copy a blob within the same storage account, it is a synchronous operation. When you copy across accounts it is an asynchronous operation. The [StartCopy](/dotnet/api/microsoft.azure.storage.blob.cloudblob.startcopy?view=azure-dotnet) and [StartCopyAsync](/dotnet/api/microsoft.azure.storage.blob.cloudblob.startcopyasync?view=azure-dotnet) methods return a copy ID value that is used to check status or abort the copy operation.
21+
22+
The source blob for a copy operation may be a block blob, an append blob, a page blob, or a snapshot. If the destination blob already exists, it must be of the same blob type as the source blob. Any existing destination blob will be overwritten.
23+
24+
The destination blob can't be modified while a copy operation is in progress. A destination blob can only have one outstanding copy blob operation. In other words, a blob can't be the destination for multiple pending copy operations.
25+
26+
The entire source blob or file is always copied. Copying a range of bytes or set of blocks is not supported.
27+
28+
When a blob is copied, it's system properties are copied to the destination blob with the same values.
29+
30+
For all blob types, you can check the [CopyState.Status](/dotnet/api/microsoft.azure.storage.blob.copystate.status?view=azure-dotnet) property on the destination blob to get the status of the copy operation. The final blob will be committed when the copy completes.
31+
32+
A copy operation can take any of the following forms:
33+
34+
- You can 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 can be a new blob created by the copy operation.
35+
- You can copy a source blob to a destination blob with the same name, effectively replacing the destination blob. Such a copy operation removes any uncommitted blocks and overwrites the destination blob's metadata.
36+
- You can 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 is not supported.
37+
- You can 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.
38+
- You can copy a snapshot to a destination blob with a different name. The resulting destination blob is a writeable blob and not a snapshot.
39+
40+
## Copy a blob
41+
42+
To copy a blob, call one of the following methods:
43+
44+
- [StartCopy](/dotnet/api/microsoft.azure.storage.blob.cloudblob.startcopy?view=azure-dotnet)
45+
- [StartCopyAsync](/dotnet/api/microsoft.azure.storage.blob.cloudblob.startcopyasync?view=azure-dotnet)
46+
47+
The following code example gets a reference to a blob created previously and copies it to a new blob in the same container:
48+
49+
```csharp
50+
private static async Task CopyBlockBlobAsync(CloudBlobContainer container)
51+
{
52+
CloudBlockBlob sourceBlob = null;
53+
CloudBlockBlob destBlob = null;
54+
string leaseId = null;
55+
56+
try
57+
{
58+
// Get a block blob from the container to use as the source.
59+
sourceBlob = container.ListBlobs().OfType<CloudBlockBlob>().FirstOrDefault();
60+
61+
// Lease the source blob for the copy operation to prevent another client from modifying it.
62+
// Specifying null for the lease interval creates an infinite lease.
63+
leaseId = await sourceBlob.AcquireLeaseAsync(null);
64+
65+
// Get a reference to a destination blob (in this case, a new blob).
66+
destBlob = container.GetBlockBlobReference("copy of " + sourceBlob.Name);
67+
68+
// Ensure that the source blob exists.
69+
if (await sourceBlob.ExistsAsync())
70+
{
71+
// Get the ID of the copy operation.
72+
string copyId = await destBlob.StartCopyAsync(sourceBlob);
73+
74+
// Fetch the destination blob's properties before checking the copy state.
75+
await destBlob.FetchAttributesAsync();
76+
77+
Console.WriteLine("Status of copy operation: {0}", destBlob.CopyState.Status);
78+
Console.WriteLine("Completion time: {0}", destBlob.CopyState.CompletionTime);
79+
Console.WriteLine("Bytes copied: {0}", destBlob.CopyState.BytesCopied.ToString());
80+
Console.WriteLine("Total bytes: {0}", destBlob.CopyState.TotalBytes.ToString());
81+
Console.WriteLine();
82+
}
83+
}
84+
catch (StorageException e)
85+
{
86+
Console.WriteLine(e.Message);
87+
Console.ReadLine();
88+
throw;
89+
}
90+
finally
91+
{
92+
// Break the lease on the source blob.
93+
if (sourceBlob != null)
94+
{
95+
await sourceBlob.FetchAttributesAsync();
96+
97+
if (sourceBlob.Properties.LeaseState != LeaseState.Available)
98+
{
99+
await sourceBlob.BreakLeaseAsync(new TimeSpan(0));
100+
}
101+
}
102+
}
103+
}
104+
```
105+
106+
## Abort a blob copy operation
107+
108+
Aborting a copy operation results in a destination blob of zero length for block blobs, append blobs, and page blobs. However, the metadata for the destination blob will have the new values copied from the source blob or set explicitly in the [StartCopy](/dotnet/api/microsoft.azure.storage.blob.cloudblob.startcopy?view=azure-dotnet) or [StartCopyAsync](/dotnet/api/microsoft.azure.storage.blob.cloudblob.startcopyasync?view=azure-dotnet) call. To keep the original metadata from before the copy, make a snapshot of the destination blob before calling `StartCopy` or `StartCopyAsync`.
109+
110+
When you abort an ongoing blob copy operation, the destination blob’s [CopyState.Status](/dotnet/api/microsoft.azure.storage.blob.copystate.status?view=azure-dotnet#Microsoft_Azure_Storage_Blob_CopyState_Status) is set to [CopyStatus.Aborted](/dotnet/api/microsoft.azure.storage.blob.copystatus?view=azure-dotnet).
111+
112+
The [AbortCopy](/dotnet/api/microsoft.azure.storage.blob.cloudblob.abortcopy?view=azure-dotnet) and [AbortCopyAsync](/dotnet/api/microsoft.azure.storage.blob.cloudblob.abortcopyasync?view=azure-dotnet) methods cancel an ongoing blob copy operation, and leave a destination blob with zero length and full metadata.
113+
114+
```csharp
115+
// Fetch the destination blob's properties before checking the copy state.
116+
await destBlob.FetchAttributesAsync();
117+
118+
// Check the copy status. If it is still pending, abort the copy operation.
119+
if (destBlob.CopyState.Status == CopyStatus.Pending)
120+
{
121+
await destBlob.AbortCopyAsync(copyId);
122+
Console.WriteLine("Copy operation {0} has been aborted.", copyId);
123+
}
124+
```
125+
126+
[!INCLUDE [storage-blob-dotnet-resources-include](../../../includes/storage-blob-dotnet-resources-include.md)]
127+
128+
## Next steps
129+
130+
The following topics contain information about copying blobs and aborting ongoing copy operations by using the Azure REST APIs.
131+
132+
- [Copy Blob](/rest/api/storageservices/copy-blob)
133+
- [Abort Copy Blob](/rest/api/storageservices/abort-copy-blob)

‎articles/storage/blobs/storage-blob-properties-metadata.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: Manage properties and metadata for a blob with .NET - Azure Storage
3+
description: Learn how to set and retrieve system properties and store custom metadata on blobs in your Azure Storage account using the .NET client library.
4+
services: storage
5+
author: mhopkins-msft
6+
7+
ms.author: mhopkins
8+
ms.date: 08/09/2019
9+
ms.service: storage
10+
ms.subservice: blobs
11+
ms.topic: conceptual
12+
---
13+
14+
# Manage blob properties and metadata with .NET
15+
16+
In addition to the data they contain, blobs support system properties and user-defined metadata. This article shows how to manage system properties and user-defined metadata with the [Azure Storage client library for .NET](/dotnet/api/overview/azure/storage/client).
17+
18+
## About properties and metadata
19+
20+
- **System properties**: System properties exist on each Blob storage resource. Some of them can be read or set, while others are read-only. Under the covers, some system properties correspond to certain standard HTTP headers. The Azure Storage client library for .NET maintains these properties for you.
21+
22+
- **User-defined metadata**: User-defined metadata consists of one or more name-value pairs that you specify for a Blob storage resource. You can use metadata to store additional values with the resource. Metadata values are for your own purposes only, and don't affect how the resource behaves.
23+
24+
Retrieving metadata and property values for a Blob storage resource is a two-step process. Before you can read these values, you must explicitly fetch them by calling the `FetchAttributes` or `FetchAttributesAsync` method. The exception to this rule is that the `Exists` and `ExistsAsync` methods call the appropriate `FetchAttributes` method under the covers. When you call one of these methods, you don't need to also call `FetchAttributes`.
25+
26+
> [!IMPORTANT]
27+
> If you find that property or metadata values for a storage resource have not been populated, check that your code calls the `FetchAttributes` or `FetchAttributesAsync` method.
28+
29+
## Set and retrieve properties
30+
31+
The following code example sets the `ContentType` and `ContentLanguage` system properties on a blob.
32+
33+
```csharp
34+
public static async Task SetBlobPropertiesAsync(CloudBlob blob)
35+
{
36+
try
37+
{
38+
Console.WriteLine("Setting blob properties.");
39+
40+
// You must explicitly set the MIME ContentType every time
41+
// the properties are updated or the field will be cleared.
42+
blob.Properties.ContentType = "text/plain";
43+
blob.Properties.ContentLanguage = "en-us";
44+
45+
// Set the blob's properties.
46+
await blob.SetPropertiesAsync();
47+
}
48+
catch (StorageException e)
49+
{
50+
Console.WriteLine("HTTP error code {0}: {1}",
51+
e.RequestInformation.HttpStatusCode,
52+
e.RequestInformation.ErrorCode);
53+
Console.WriteLine(e.Message);
54+
Console.ReadLine();
55+
}
56+
}
57+
```
58+
59+
To retrieve blob properties, call the `FetchAttributes` or `FetchAttributesAsync` method on your blob to populate the `Properties` property. The following code example gets a blob's system properties and displays some of the values:
60+
61+
```csharp
62+
private static async Task GetBlobPropertiesAsync(CloudBlob blob)
63+
{
64+
try
65+
{
66+
// Fetch the blob properties.
67+
await blob.FetchAttributesAsync();
68+
69+
// Display some of the blob's property values.
70+
Console.WriteLine(" ContentLanguage: {0}", blob.Properties.ContentLanguage);
71+
Console.WriteLine(" ContentType: {0}", blob.Properties.ContentType);
72+
Console.WriteLine(" Created: {0}", blob.Properties.Created);
73+
Console.WriteLine(" LastModified: {0}", blob.Properties.LastModified);
74+
}
75+
catch (StorageException e)
76+
{
77+
Console.WriteLine("HTTP error code {0}: {1}",
78+
e.RequestInformation.HttpStatusCode,
79+
e.RequestInformation.ErrorCode);
80+
Console.WriteLine(e.Message);
81+
Console.ReadLine();
82+
}
83+
}
84+
```
85+
86+
## Set and retrieve metadata
87+
88+
You can specify metadata as one or more name-value pairs on a blob or container resource. To set metadata, add name-value pairs to the `Metadata` collection on the resource. Then, call one of the following methods to write the values:
89+
90+
- [SetMetadata](/dotnet/api/microsoft.azure.storage.blob.cloudblob.setmetadata)
91+
- [SetMetadataAsync](/dotnet/api/microsoft.azure.storage.blob.cloudblob.setmetadataasync)
92+
93+
Metadata name/value pairs are valid HTTP headers and should adhere to all restrictions governing HTTP headers. Metadata names must be valid HTTP header names and valid C# identifiers, may contain only ASCII characters, and should be treated as case-insensitive. [Base64-encode](https://docs.microsoft.com/dotnet/api/system.convert.tobase64string) or [URL-encode](https://docs.microsoft.com/dotnet/api/system.web.httputility.urlencode) metadata values containing non-ASCII characters.
94+
95+
The name of your metadata must conform to the naming conventions for C# identifiers. Metadata names maintain the case used when they were created, but are case-insensitive when set or read. If two or more metadata headers using the same name are submitted for a resource, Azure Blob storage returns HTTP error code 400 (Bad Request).
96+
97+
The following code example sets metadata on a blob. One value is set using the collection's `Add` method. The other value is set using implicit key/value syntax.
98+
99+
```csharp
100+
public static async Task AddBlobMetadataAsync(CloudBlob blob)
101+
{
102+
try
103+
{
104+
// Add metadata to the blob by calling the Add method.
105+
blob.Metadata.Add("docType", "textDocuments");
106+
107+
// Add metadata to the blob by using key/value syntax.
108+
blob.Metadata["category"] = "guidance";
109+
110+
// Set the blob's metadata.
111+
await blob.SetMetadataAsync();
112+
}
113+
catch (StorageException e)
114+
{
115+
Console.WriteLine("HTTP error code {0}: {1}",
116+
e.RequestInformation.HttpStatusCode,
117+
e.RequestInformation.ErrorCode);
118+
Console.WriteLine(e.Message);
119+
Console.ReadLine();
120+
}
121+
}
122+
```
123+
124+
To retrieve metadata, call the `FetchAttributes` or `FetchAttributesAsync` method on your blob or container to populate the `Metadata` collection, then read the values, as shown in the example below.
125+
126+
```csharp
127+
public static async Task ReadBlobMetadataAsync(CloudBlob blob)
128+
{
129+
try
130+
{
131+
// Fetch blob attributes in order to populate
132+
// the blob's properties and metadata.
133+
await blob.FetchAttributesAsync();
134+
135+
Console.WriteLine("Blob metadata:");
136+
137+
// Enumerate the blob's metadata.
138+
foreach (var metadataItem in blob.Metadata)
139+
{
140+
Console.WriteLine("\tKey: {0}", metadataItem.Key);
141+
Console.WriteLine("\tValue: {0}", metadataItem.Value);
142+
}
143+
}
144+
catch (StorageException e)
145+
{
146+
Console.WriteLine("HTTP error code {0}: {1}",
147+
e.RequestInformation.HttpStatusCode,
148+
e.RequestInformation.ErrorCode);
149+
Console.WriteLine(e.Message);
150+
Console.ReadLine();
151+
}
152+
}
153+
```
154+
155+
[!INCLUDE [storage-blob-dotnet-resources-include](../../../includes/storage-blob-dotnet-resources-include.md)]
156+
157+
## See also
158+
159+
- [Set Blob Properties operation](/rest/api/storageservices/set-blob-properties)
160+
- [Get Blob Properties operation](/rest/api/storageservices/get-blob-properties)
161+
- [Set Blob Metadata operation](/rest/api/storageservices/set-blob-metadata)
162+
- [Get Blob Metadata operation](/rest/api/storageservices/set-blob-metadata)

0 commit comments

Comments
 (0)