Creating new PR for Storage Blob migration guide by rishabpoh · Pull Request #15749 · Azure/azure-sdk-for-net

rishabpoh · 2020-10-06T21:00:10Z

I've addressed most of the comments from the old PR. Couldn't merge correctly because I deleted my forked copy of the repo. Requesting assistance on some TODO sections.

jaschrep-msft · 2020-10-06T21:49:49Z

+```
+
+v12
+```csharp


@amnguye can you add an additional sample to this document for when the new SAS APIs get released? Just like a note that 12.x and above users can use the following code, which may be more familiar to v11 users.

not for this PR, but just whenever the SAS API additions get merged in.

jaschrep-msft · 2020-10-06T21:52:48Z

+await service.GetPropertiesAsync();
+```
+
+Summary:


What is this meant to be?

It was meant to be a brief description of the underlying changes we made to give the developer a better idea of the differences they're looking at. But it could be unnecessary too. If the summaries don't add much value then it doesn't make sense to keep them. What do you think?

jaschrep-msft · 2020-10-06T22:01:37Z

+
+In the interest of simplifying the API surface we've made a three top level clients that can be used to interact with a majority of your resources: `BlobServiceClient`, `BlobContainerClient`, and `BlobClient`.
+
+[//]: # (Blob Metadata, properties, and attributes...)


What is this doing? I don't see anything rendering in the rich view.

It's how you leave a comment in Markdown apparently. I wanted to leave that comment as a reminder to add some migration info on that topic.

amnguye · 2020-10-06T22:17:10Z

Maybe for a different PR but we should try to have the guide take snippets from actual samples (for v12). That way we know when and if our snippets ever break.

jaschrep-msft · 2020-10-06T22:19:15Z

+```csharp
+// Create a BlobServiceClient object which will be used to create a container client
+BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString);
+// Create a unique name for the container
+string containerName = "yourcontainer";
+// Create the container and return a container client object
+BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);
+```


It suggestion syntax not happy with nested code blocks. Below is a suggested change where the side-by-side examples have the same code structure. Then a shortcut method is introduced.

// Create a BlobServiceClient object which will be used to create a container client BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString); BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient("yourcontainer"); await containerClient.CreateAsync()

Alternatively, you can skip a step in v12 by with BlobServiceClient.CreateBlobContainer():

// Create a BlobServiceClient object which will be used to create a container client BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString); BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync("yourcontainer");

jaschrep-msft · 2020-10-06T22:28:47Z

+BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);
+```
+
+Summary: In v11, a `CloudBlobClient` was required to get a reference to the desired blob container. In v12, the intermediate step `cloudBlobClient.GetContainerReference("yourcontainer")` was removed.


This wasn't removed. This should convey that the old methods have exact v12 counterparts.

jaschrep-msft · 2020-10-06T22:52:54Z

+uploadFileStream.Close();
+```
+
+Summary: In v11, a file path was used to upload a blob. In v12, `Stream` is used to upload a blob's content.


streams and file paths can be used in both

jaschrep-msft · 2020-10-06T22:56:25Z

+BlobDownloadInfo download = await blobClient.DownloadAsync();
+using (FileStream downloadFileStream = File.OpenWrite(downloadFilePath))
+{
+    await download.Content.CopyToAsync(downloadFileStream);
+    downloadFileStream.Close();
+}


We have download to file. use similar samples

jaschrep-msft · 2020-10-06T22:59:49Z

+}
+```
+
+### Listing Blobs in a Container


We didn't force people to manually iterate over pages in v11. We just had separate methods for a lazy enumerable vs getting each page on your own. I think it's actually important to highlight both mechanisms for this section, because manually handling individual pages is a bit complex in v12, and we'll want to give a direct migration for that as well.

amnguye · 2020-10-08T16:42:27Z

+
+### Authentication
+
+#### Managed Identity


I'm not sure there's a short sample we can provide for this since it's not specific to v11 to v12 and more in the identity libraries. I think a complex stand alone solution/tutorial using MSI might be more helpful (since it requires step by step instructions on how to set up managed identity which is outside the scope of storage.

Maybe we should provide a sample for authenticating with AAD (e.g. TokenCredential) instead

amnguye · 2020-10-08T17:43:53Z

+```
+
+v12
+```csharp


// Create BlobSasBuilder and specify parameters BlobSasBuilder sasBuilder = new BlobSasBuilder() { BlobContainerName = containerName, BlobName = blobName, ExpiresOn = new DateTimeOffset IPRange = new SasIPRange(System.Net.IPAddress.None, System.Net.IPAddress.None) }; // Set Permissions sasBuilder.SetPermissions(BlobSasPermissions.Read); // Create SasQueryParameters BlobSasQueryParameters parameters = sasBuilder.ToSasQueryParameters(sharedKeyCredential); // Create Uri with SasToken BlobUriBuilder uriBuilder = new BlobUriBuilder(blobUri) { Sas = sasBuilder.ToSasQueryParameters(constants.Sas.SharedKeyCredential) }; Uri sasUri = uriBuilder.ToUri()

This is to create a service SAS. Did we also want to add one for user delegation sas?
For UserDelegation Sas it is essentially the same snippet with the exception of this line
BlobSasQueryParameters parameters = sasBuilder.ToSasQueryParameters(sharedKeyCredential);
should be changed to
BlobSasQueryParameters parameters = sasBuilder.ToSasQueryParameters(userDelegationKey, accountName);

amnguye · 2020-10-08T17:52:12Z

+There are various SAS tokens that may be generated. Visit our documentation pages to learn how to [Create a User Delegation SAS](https://docs.microsoft.com/azure/storage/blobs/storage-blob-user-delegation-sas-create-dotnet), [Create a Service SAS](https://docs.microsoft.com/azure/storage/blobs/storage-blob-service-sas-create-dotnet), or [Create an Account SAS](https://docs.microsoft.com/azure/storage/common/storage-account-sas-create-dotnet?toc=/azure/storage/blobs/toc.json).
+
+v11
+```csharp


Service SAS:

string sasBlobToken; // Get a reference to a blob within the container. // Note that the blob may not exist yet, but a SAS can still be created for it. CloudBlockBlob blob = container.GetBlockBlobReference(blobName); if (policyName == null) { // Create a new access policy and define its constraints. // Note that the SharedAccessBlobPolicy class is used both to define the parameters of an ad hoc SAS, and // to construct a shared access policy that is saved to the container's shared access policies. SharedAccessBlobPolicy adHocSAS = new SharedAccessBlobPolicy() { // When the start time for the SAS is omitted, the start time is assumed to be the time when the storage service receives the request. // Omitting the start time for a SAS that is effective immediately helps to avoid clock skew. SharedAccessExpiryTime = DateTime.UtcNow.AddHours(24), Permissions = SharedAccessBlobPermissions.Read | SharedAccessBlobPermissions.Write | SharedAccessBlobPermissions.Create }; // Generate the shared access signature on the blob, setting the constraints directly on the signature. sasBlobToken = blob.GetSharedAccessSignature(adHocSAS); Console.WriteLine("SAS for blob (ad hoc): {0}", sasBlobToken); Console.WriteLine(); } else { // Generate the shared access signature on the blob. In this case, all of the constraints for the // shared access signature are specified on the container's stored access policy. sasBlobToken = blob.GetSharedAccessSignature(null, policyName); Console.WriteLine("SAS for blob (stored access policy): {0}", sasBlobToken); Console.WriteLine(); } // Return the URI string for the container, including the SAS token. return blob.Uri + sasBlobToken;

amnguye · 2020-10-08T18:06:20Z

+
+### Shared Access Policies
+
+TODO


We actually already have samples for this. This site has it https://docs.microsoft.com/en-us/azure/storage/common/storage-stored-access-policy-define-dotnet?tabs=dotnet

Co-authored-by: James <41338290+jaschrep-msft@users.noreply.github.com>

jaschrep-msft · 2020-10-23T19:10:51Z

Am personally tracking gaps in this PR, but we need to get this baseline in.

jaschrep-msft · 2020-10-23T19:12:27Z

/azp run net - storage - ci

azure-pipelines · 2020-10-23T19:12:38Z

Azure Pipelines successfully started running 1 pipeline(s).

* Adding migration guide addressing most comments from old PR * Minor mod * Adding migration guide addressing most comments from old PR * Minor mod * Fixing links * Update sdk/storage/Azure.Storage.Blobs/AzureStorageNetMigrationV12.md Co-authored-by: James <41338290+jaschrep-msft@users.noreply.github.com> * Update sdk/storage/Azure.Storage.Blobs/AzureStorageNetMigrationV12.md Co-authored-by: James <41338290+jaschrep-msft@users.noreply.github.com> * Applying additions and changes from PR comments * fixed hyperlinks Co-authored-by: Rishab Pohane <ripohane@microsoft.com> Co-authored-by: James <41338290+jaschrep-msft@users.noreply.github.com>

rpohane added 5 commits October 6, 2020 10:48

Adding migration guide addressing most comments from old PR

85d0fc4

Minor mod

6deb303

Adding migration guide addressing most comments from old PR

1d300b8

Minor mod

25c12ef

applying changes

aa4e933

rishabpoh requested review from amishra-dev, amnguye, kasobol-msft, seanmcc-msft and tg-msft as code owners October 6, 2020 21:00

ghost added the Storage Storage Service (Queues, Blobs, Files) label Oct 6, 2020

rishabpoh changed the title ~~Creating new PR for migration guide~~ Creating new PR for Storage Blob migration guide Oct 6, 2020

rishabpoh mentioned this pull request Oct 6, 2020

Uploading migration guide and updating README with blog post link #13159

Closed

Fixing links

1f04a7d

jaschrep-msft reviewed Oct 6, 2020

View reviewed changes

Comment thread sdk/storage/Azure.Storage.Blobs/AzureStorageNetMigrationV12.md

jaschrep-msft reviewed Oct 6, 2020

View reviewed changes

Comment thread sdk/storage/Azure.Storage.Blobs/AzureStorageNetMigrationV12.md

jaschrep-msft reviewed Oct 6, 2020

View reviewed changes

Comment thread sdk/storage/Azure.Storage.Blobs/AzureStorageNetMigrationV12.md Outdated

jaschrep-msft reviewed Oct 6, 2020

View reviewed changes

amnguye reviewed Oct 8, 2020

View reviewed changes

rishabpoh and others added 5 commits October 20, 2020 11:48

Update sdk/storage/Azure.Storage.Blobs/AzureStorageNetMigrationV12.md

af9eb68

Co-authored-by: James <41338290+jaschrep-msft@users.noreply.github.com>

Update sdk/storage/Azure.Storage.Blobs/AzureStorageNetMigrationV12.md

d5eda33

Co-authored-by: James <41338290+jaschrep-msft@users.noreply.github.com>

Applying additions and changes from PR comments

06c4bce

Pulling PR changes

28da1d1

fixed hyperlinks

4e72fc1

jaschrep-msft approved these changes Oct 23, 2020

View reviewed changes

jaschrep-msft merged commit 63f0ed1 into Azure:master Oct 23, 2020

amnguye mentioned this pull request Dec 7, 2020

[FEATURE REQ] Storage Migration Guide #12106

Closed


		In the interest of simplifying the API surface we've made a three top level clients that can be used to interact with a majority of your resources: `BlobServiceClient`, `BlobContainerClient`, and `BlobClient`.

		[//]: # (Blob Metadata, properties, and attributes...)

Conversation

rishabpoh commented Oct 6, 2020

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

amnguye commented Oct 6, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amnguye Oct 8, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaschrep-msft commented Oct 23, 2020

Uh oh!

jaschrep-msft commented Oct 23, 2020

Uh oh!

azure-pipelines Bot commented Oct 23, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

amnguye Oct 8, 2020 •

edited

Loading