Uploading migration guide and updating README with blog post link#13159
Closed
rishabpoh wants to merge 2 commits intoAzure:masterfrom
rishabpoh:master
Closed
Uploading migration guide and updating README with blog post link#13159rishabpoh wants to merge 2 commits intoAzure:masterfrom rishabpoh:master
rishabpoh wants to merge 2 commits intoAzure:masterfrom
rishabpoh:master
Conversation
rishabpoh
requested review from
amishra-dev,
amnguye,
kasobol-msft,
seanmcc-msft and
tg-msft
as code owners
amnguye
reviewed
Jul 1, 2020
| ``` | ||
|
|
||
| v12 | ||
| ```c |
Member
There was a problem hiding this comment.
In the future maybe we can try to use code snippets from the samples, that way the snippets are frequently ran and checked.
Contributor
Author
There was a problem hiding this comment.
I agree that we should in the future! I didn't do that this time because:
- It wouldn't have been consistent bc we don't have all the samples
- The snippets are rather large for some and as opposed to a whole test method I wanted to focus on just the lines that mattered. Maybe not a good approach though.
amnguye
reviewed
Jul 1, 2020
| dotnet add package Microsoft.Azure.Storage.Blob | ||
| ``` | ||
|
|
||
| ### Authentication |
Member
There was a problem hiding this comment.
This is fine here for now, I'm wondering if we should have a general migration guide for auth stuff since some of it applies to the other libaries
Contributor
Author
There was a problem hiding this comment.
That's a good point, we may need one specific to auth since it's a pretty important and large topic.
amnguye
reviewed
Jul 1, 2020
|
|
||
| #### Managed Identity | ||
|
|
||
| Legacy (v11) |
Member
There was a problem hiding this comment.
For all the spots that are empty, maybe add a TODO or coming soon, or leaving it out for now and making an issue to add it to the migration guide?
Contributor
Author
There was a problem hiding this comment.
Got it, added "TODO" text.
loic-sharma
reviewed
Jul 1, 2020
|
|
||
| // Open the file and upload its data | ||
| using FileStream uploadFileStream = File.OpenRead(localFilePath); | ||
| await blobClient.UploadAsync(uploadFileStream, true); |
Contributor
There was a problem hiding this comment.
What do you think of using a named parameter here to clarify the purpose of the true?
Suggested change
| await blobClient.UploadAsync(uploadFileStream, true); | |
| await blobClient.UploadAsync(uploadFileStream, overwrite: true); |
loic-sharma
reviewed
Jul 1, 2020
| { | ||
| Console.WriteLine("\t" + blobItem.Name); | ||
| } | ||
| ``` |
Contributor
There was a problem hiding this comment.
Do we have an example for .NET Framework applications that can't use await foreach?
Contributor
Author
There was a problem hiding this comment.
Do you mean that don't use it? Sorry I didn't quite understand the ask
Member
There was a problem hiding this comment.
I think the ask is to provide a sync snippet and async snippet. But we already have samples for that. I think customers can look to our samples if they want to see how to do use async or sync versions of our APIs. Up to you if you want to provide both in the migration guide, but we can always link to our samples as well.
amnguye
approved these changes
Jul 1, 2020
Member
|
/azp run net - storage - tests |
|
Azure Pipelines successfully started running 1 pipeline(s). |
SeanFeldman
suggested changes
Jul 3, 2020
Comment on lines
+26
to
+30
| To understand why we created our version 12 client libraries, you may refer to the Tech Community blog post, [Announcing the Azure Storage v12 Client Libraries](https://techcommunity.microsoft.com/t5/azure-storage/announcing-the-azure-storage-v12-client-libraries/ba-p/1482394). | ||
|
|
||
| In summary, the v12 client libraries for Azure Storage were created in order to address a number of areas of feedback. One of the most important being that Azure services have not been consistent in organization, naming, and API structure. Azure Storage has aligned with a set of common guidelines in order to focus on quick delivery of service features and to optimize the learning curve that comes with using the libraries. They are idiomatic, approachable, and consistent. The version 12 client libraries are also thread safe, offer both synchronous and asynchronous APIs, and have improved performance over previous versions. We have reached feature parity for major scenarios and have updated documentation featuring the v12 [Quickstart](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-dotnet), [Samples](https://docs.microsoft.com/en-us/azure/storage/common/storage-samples-dotnet?toc=/azure/storage/blobs/toc.json), and [Reference](https://docs.microsoft.com/en-us/dotnet/api/azure.storage.blobs?view=azure-dotnet) pages (for .NET Azure Storage Blob Library). | ||
|
|
||
| Note: The blog post linked above announces deprecation for previous versions of the library. |
Contributor
There was a problem hiding this comment.
Less is more. I would approach this section differently. Rather than writing an essay on the topic of benefits, would make is a list. E.g.
Suggested change
| To understand why we created our version 12 client libraries, you may refer to the Tech Community blog post, [Announcing the Azure Storage v12 Client Libraries](https://techcommunity.microsoft.com/t5/azure-storage/announcing-the-azure-storage-v12-client-libraries/ba-p/1482394). | |
| In summary, the v12 client libraries for Azure Storage were created in order to address a number of areas of feedback. One of the most important being that Azure services have not been consistent in organization, naming, and API structure. Azure Storage has aligned with a set of common guidelines in order to focus on quick delivery of service features and to optimize the learning curve that comes with using the libraries. They are idiomatic, approachable, and consistent. The version 12 client libraries are also thread safe, offer both synchronous and asynchronous APIs, and have improved performance over previous versions. We have reached feature parity for major scenarios and have updated documentation featuring the v12 [Quickstart](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-dotnet), [Samples](https://docs.microsoft.com/en-us/azure/storage/common/storage-samples-dotnet?toc=/azure/storage/blobs/toc.json), and [Reference](https://docs.microsoft.com/en-us/dotnet/api/azure.storage.blobs?view=azure-dotnet) pages (for .NET Azure Storage Blob Library). | |
| Note: The blog post linked above announces deprecation for previous versions of the library. | |
| The benefits of the v12 client library include the following: | |
| - Thread-safe synchronous and asynchronous APIs | |
| - Improved performance | |
| - Consistent and idiomatic code organization, naming, and API structure, aligned with a set of common guidelines | |
| - The learning curve associated with the libraries was reduced |
Comment on lines
+267
to
+272
| ### Other | ||
|
|
||
| ## Additional samples | ||
|
|
||
| More examples can be found at: | ||
| - [Azure Storage samples using v12 .NET Client Libraries](https://docs.microsoft.com/en-us/azure/storage/common/storage-samples-dotnet?toc=/azure/storage/blobs/toc.json) |
Contributor
There was a problem hiding this comment.
Suggested change
| ### Other | |
| ## Additional samples | |
| More examples can be found at: | |
| - [Azure Storage samples using v12 .NET Client Libraries](https://docs.microsoft.com/en-us/azure/storage/common/storage-samples-dotnet?toc=/azure/storage/blobs/toc.json) | |
| ### Other | |
| ## Additional information | |
| ### Samples | |
| More examples can be found at: | |
| - [Azure Storage samples using v12 .NET Client Libraries](https://docs.microsoft.com/en-us/azure/storage/common/storage-samples-dotnet?toc=/azure/storage/blobs/toc.json) | |
| ### Links and references | |
| - v12 [Quickstart](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-dotnet) | |
| - [Samples](https://docs.microsoft.com/en-us/azure/storage/common/storage-samples-dotnet?toc=/azure/storage/blobs/toc.json) | |
| - [.NET SDK reference](https://docs.microsoft.com/en-us/dotnet/api/azure.storage.blobs?view=azure-dotnet) | |
| - [Announcing the Azure Storage v12 Client Libraries](https://techcommunity.microsoft.com/t5/azure-storage/announcing-the-azure-storage-v12-client-libraries/ba-p/1482394) blog post |
|
|
||
| It is now the following for v12: | ||
| ``` | ||
| dotnet add package Microsoft.Azure.Storage.Blob |
Contributor
There was a problem hiding this comment.
Suggested change
| dotnet add package Microsoft.Azure.Storage.Blob | |
| dotnet add package Azure.Storage.Blobs |
Comment on lines
+38
to
+41
| In this case, to install the legacy v11 package with Nuget: | ||
| ``` | ||
| dotnet add package Azure.Storage.Blobs | ||
| ``` |
Contributor
There was a problem hiding this comment.
You've confused the two. Imagine how confused are customers with 11->12 on a different package name 😀
Suggested change
| In this case, to install the legacy v11 package with Nuget: | |
| ``` | |
| dotnet add package Azure.Storage.Blobs | |
| ``` | |
| In this case, to install the legacy v11 package with NuGet: |
dotnet add package Microsoft.Azure.Storage.Blob
|
|
||
| ### Authentication | ||
|
|
||
| #### Managed Identity |
Contributor
There was a problem hiding this comment.
This is such a critical area. When do you think TODO will be completed?
|
|
||
| ### Client constructors | ||
|
|
||
| | In v11 | In v12 | |
Contributor
There was a problem hiding this comment.
Suggested change
| | In v11 | In v12 | | |
| | v11 | v12 | |
|
|
||
| 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...) |
Contributor
There was a problem hiding this comment.
Is this going to pull in some external articles? Given that changes associated with metadata/properties/attributes are breaking changes, this is the meat of the upgrade document.
| BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName); | ||
| ``` | ||
|
|
||
| Summary: In version 11, you would have to use the storage account endpoint to create the `CloudBlobClient`. Then you can get the container reference by calling the `GetContainerReference` method and create it by calling `CreateAsync()` on it. In version 12, you will use the `BlobServiceClient` object to then create `BlobContainerClient`. |
Contributor
There was a problem hiding this comment.
I am not sure what value this summary adds other than describing in sentences what the code above just did.
If you feel the summary is necessary, please reduce it to the important information only. E.g.
Suggested change
| Summary: In version 11, you would have to use the storage account endpoint to create the `CloudBlobClient`. Then you can get the container reference by calling the `GetContainerReference` method and create it by calling `CreateAsync()` on it. In version 12, you will use the `BlobServiceClient` object to then create `BlobContainerClient`. | |
| 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. |
| uploadFileStream.Close(); | ||
| ``` | ||
|
|
||
| Summary: In v11, you would get the `CloudBlockBlob` reference by calling the `GetBlockBlobReference` method on the container name. Calling `UploadFromFileAsync` would then create the blob if it doesn't exist or overwrite the existing one. In v12, you will get the reference to the `BlobClient` object by calling the `GetBlobClient` method on the container and then upload the blob using the `UploadAsync` method. |
Contributor
There was a problem hiding this comment.
Same as above
Suggested change
| Summary: In v11, you would get the `CloudBlockBlob` reference by calling the `GetBlockBlobReference` method on the container name. Calling `UploadFromFileAsync` would then create the blob if it doesn't exist or overwrite the existing one. In v12, you will get the reference to the `BlobClient` object by calling the `GetBlobClient` method on the container and then upload the blob using the `UploadAsync` method. | |
| Summary: In v11 a file path was used to upload a blob. In v12 `Stream` is used to upload a blob's content. |
Comment on lines
+229
to
+233
| using (FileStream downloadFileStream = File.OpenWrite(downloadFilePath)) | ||
| { | ||
| await download.Content.CopyToAsync(downloadFileStream); | ||
| downloadFileStream.Close(); | ||
| } |
Contributor
There was a problem hiding this comment.
using will invoke IDispose that will call .Close()
Suggested change
| using (FileStream downloadFileStream = File.OpenWrite(downloadFilePath)) | |
| { | |
| await download.Content.CopyToAsync(downloadFileStream); | |
| downloadFileStream.Close(); | |
| } | |
| using (FileStream downloadFileStream = File.OpenWrite(downloadFilePath)) | |
| { | |
| await download.Content.CopyToAsync(downloadFileStream); | |
| } |
alternatively,
await using FileStream downloadFileStream = File.OpenWrite(downloadFilePath);
await download.Content.CopyToAsync(downloadFileStream);
Member
|
/azp run net - storage - tests |
|
Azure Pipelines successfully started running 1 pipeline(s). |
Member
|
Remember you need to merge master into your forked branch to get CI passing. There was a lot of fixes in master done last week. |
jongio
requested changes
Jul 9, 2020
| @@ -0,0 +1,272 @@ | |||
| # Guide for migrating to Azure.Storage.Blobs from Microsoft.Azure.Storage.Blob | |||
Member
There was a problem hiding this comment.
Suggested change
| # Guide for migrating to Azure.Storage.Blobs from Microsoft.Azure.Storage.Blob | |
| # Migration Guide: From Microsoft.Azure.Storage.Blob to Azure.Storage.Blobs |
| This guide intends to assist customers in migrating from version 11 of the Azure Storage .NET library for Blobs to version 12. | ||
| It will focus on side-by-side comparisons for similar operations between the v12 package, [`Azure.Storage.Blobs`](https://www.nuget.org/packages/Azure.Storage.Blobs) and v11 package, [`Microsoft.Azure.Storage.Blob`](https://www.nuget.org/packages/Microsoft.Azure.Storage.Blob/). | ||
|
|
||
| Familiarity with the v11 client library is assumed. For those new to the Azure Storage Blobs client library for .NET, please refer to the [Quickstart](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-dotnet) for the v12 library rather than this guide. |
|
|
||
| To understand why we created our version 12 client libraries, you may refer to the Tech Community blog post, [Announcing the Azure Storage v12 Client Libraries](https://techcommunity.microsoft.com/t5/azure-storage/announcing-the-azure-storage-v12-client-libraries/ba-p/1482394). | ||
|
|
||
| In summary, the v12 client libraries for Azure Storage were created in order to address a number of areas of feedback. One of the most important being that Azure services have not been consistent in organization, naming, and API structure. Azure Storage has aligned with a set of common guidelines in order to focus on quick delivery of service features and to optimize the learning curve that comes with using the libraries. They are idiomatic, approachable, and consistent. The version 12 client libraries are also thread safe, offer both synchronous and asynchronous APIs, and have improved performance over previous versions. We have reached feature parity for major scenarios and have updated documentation featuring the v12 [Quickstart](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-dotnet), [Samples](https://docs.microsoft.com/en-us/azure/storage/common/storage-samples-dotnet?toc=/azure/storage/blobs/toc.json), and [Reference](https://docs.microsoft.com/en-us/dotnet/api/azure.storage.blobs?view=azure-dotnet) pages (for .NET Azure Storage Blob Library). |
Member
There was a problem hiding this comment.
Consider linking to intro video "Introducing the new Azure SDKs" https://aka.ms/azsdk/intro
|
|
||
| TODO | ||
|
|
||
| v12 |
Member
There was a problem hiding this comment.
You could link to the docs for now.
Member
|
Hi @rishabpoh. There hasn't been recent engagement on this PR. Would you please be so kind as to let us know if this is still an active work stream or if this should be closed out? |
jsquire
added
Client
Contributor
Author
|
I have closed this one and created a new one here: #15749 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Needs completion but templated and contains core concepts/resources to help customers get started in migrating.