Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve download docs #22418

Merged
merged 3 commits into from
Jul 2, 2021
Merged

Improve download docs #22418

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
319cada
deprecated api
kasobol-msft Jul 2, 2021
ee435ee
improve downloadcontent and download streaming
kasobol-msft Jul 2, 2021
b270468
wip
kasobol-msft Jul 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 212 additions & 0 deletions sdk/storage/Azure.Storage.Blobs/src/BlobBaseClient.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -608,6 +608,22 @@ private void SetNameFieldsIfNull()
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API has been deprecated. Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadContent</term>
/// <description>as a prefered way of downloading small blobs that can fit into memory</description>
/// </item>
/// <item>
/// <term>DownloadTo</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreaming</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual Response<BlobDownloadInfo> Download() =>
Expand All @@ -629,6 +645,22 @@ public virtual Response<BlobDownloadInfo> Download() =>
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API has been deprecated. Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadContentAsync</term>
/// <description>as a prefered way of downloading small blobs that can fit into memory</description>
/// </item>
/// <item>
/// <term>DownloadToAsync</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreamingAsync</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual async Task<Response<BlobDownloadInfo>> DownloadAsync() =>
Expand All @@ -654,6 +686,22 @@ public virtual async Task<Response<BlobDownloadInfo>> DownloadAsync() =>
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API has been deprecated. Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadContent</term>
/// <description>as a prefered way of downloading small blobs that can fit into memory</description>
/// </item>
/// <item>
/// <term>DownloadTo</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreaming</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual Response<BlobDownloadInfo> Download(
Expand Down Expand Up @@ -683,6 +731,22 @@ public virtual Response<BlobDownloadInfo> Download(
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API has been deprecated. Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadContentAsync</term>
/// <description>as a prefered way of downloading small blobs that can fit into memory</description>
/// </item>
/// <item>
/// <term>DownloadToAsync</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreamingAsync</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual async Task<Response<BlobDownloadInfo>> DownloadAsync(
Expand Down Expand Up @@ -729,6 +793,22 @@ await DownloadAsync(
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API has been deprecated. Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadContent</term>
/// <description>as a prefered way of downloading small blobs that can fit into memory</description>
/// </item>
/// <item>
/// <term>DownloadTo</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreaming</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual Response<BlobDownloadInfo> Download(
Expand Down Expand Up @@ -781,6 +861,22 @@ public virtual Response<BlobDownloadInfo> Download(
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API has been deprecated. Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadContentAsync</term>
/// <description>as a prefered way of downloading small blobs that can fit into memory</description>
/// </item>
/// <item>
/// <term>DownloadToAsync</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreamingAsync</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual async Task<Response<BlobDownloadInfo>> DownloadAsync(
Expand Down Expand Up @@ -903,6 +999,19 @@ private async Task<Response<BlobDownloadInfo>> DownloadInternal(
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API gives access directly to network stream that should be disposed after usage.
/// Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadContent</term>
/// <description>as a prefered way of downloading small blobs that can fit into memory</description>
/// </item>
/// <item>
/// <term>DownloadTo</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// </list>
/// </remarks>
public virtual Response<BlobDownloadStreamingResult> DownloadStreaming(
HttpRange range = default,
Expand Down Expand Up @@ -955,6 +1064,19 @@ public virtual Response<BlobDownloadStreamingResult> DownloadStreaming(
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API gives access directly to network stream that should be disposed after usage.
/// Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadContentAsync</term>
/// <description>as a prefered way of downloading small blobs that can fit into memory</description>
/// </item>
/// <item>
/// <term>DownloadToAsync</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// </list>
/// </remarks>
public virtual async Task<Response<BlobDownloadStreamingResult>> DownloadStreamingAsync(
HttpRange range = default,
Expand Down Expand Up @@ -1199,6 +1321,21 @@ private async Task<Response<BlobDownloadStreamingResult>> StartDownloadAsync(
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API is a prefered way to fetch blobs that can fit into memory.
/// The content is provided as <see cref="BinaryData"/> that provides a lightweight abstraction for a payload of bytes.
/// It provides convenient helper methods to get out commonly used primitives, such as streams, strings, or bytes.
/// Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadTo</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreaming</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
public virtual Response<BlobDownloadResult> DownloadContent() =>
DownloadContent(CancellationToken.None);
Expand All @@ -1219,6 +1356,21 @@ public virtual Response<BlobDownloadResult> DownloadContent() =>
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API is a prefered way to fetch blobs that can fit into memory.
/// The content is provided as <see cref="BinaryData"/> that provides a lightweight abstraction for a payload of bytes.
/// It provides convenient helper methods to get out commonly used primitives, such as streams, strings, or bytes.
/// Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadToAsync</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreamingAsync</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
public virtual async Task<Response<BlobDownloadResult>> DownloadContentAsync() =>
await DownloadContentAsync(CancellationToken.None).ConfigureAwait(false);
Expand All @@ -1243,6 +1395,21 @@ public virtual async Task<Response<BlobDownloadResult>> DownloadContentAsync() =
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API is a prefered way to fetch blobs that can fit into memory.
/// The content is provided as <see cref="BinaryData"/> that provides a lightweight abstraction for a payload of bytes.
/// It provides convenient helper methods to get out commonly used primitives, such as streams, strings, or bytes.
/// Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadTo</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreaming</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
public virtual Response<BlobDownloadResult> DownloadContent(
CancellationToken cancellationToken = default) =>
Expand Down Expand Up @@ -1271,6 +1438,21 @@ public virtual Response<BlobDownloadResult> DownloadContent(
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API is a prefered way to fetch blobs that can fit into memory.
/// The content is provided as <see cref="BinaryData"/> that provides a lightweight abstraction for a payload of bytes.
/// It provides convenient helper methods to get out commonly used primitives, such as streams, strings, or bytes.
/// Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadToAsync</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreamingAsync</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
public virtual async Task<Response<BlobDownloadResult>> DownloadContentAsync(
CancellationToken cancellationToken) =>
Expand Down Expand Up @@ -1304,6 +1486,21 @@ await DownloadContentAsync(
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API is a prefered way to fetch blobs that can fit into memory.
/// The content is provided as <see cref="BinaryData"/> that provides a lightweight abstraction for a payload of bytes.
/// It provides convenient helper methods to get out commonly used primitives, such as streams, strings, or bytes.
/// Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadTo</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreaming</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
public virtual Response<BlobDownloadResult> DownloadContent(
BlobRequestConditions conditions = default,
Expand Down Expand Up @@ -1339,6 +1536,21 @@ public virtual Response<BlobDownloadResult> DownloadContent(
/// <remarks>
/// A <see cref="RequestFailedException"/> will be thrown if
/// a failure occurs.
///
/// This API is a prefered way to fetch blobs that can fit into memory.
/// The content is provided as <see cref="BinaryData"/> that provides a lightweight abstraction for a payload of bytes.
/// It provides convenient helper methods to get out commonly used primitives, such as streams, strings, or bytes.
/// Consider the following alternatives:
/// <list type="bullet">
/// <item>
/// <term>DownloadToAsync</term>
/// <description>to stream blob content to a path or a <see cref="Stream"/></description>
/// </item>
/// <item>
/// <term>DownloadStreamingAsync</term>
/// <description>as a replacement to this API. Use it to access network stream directly for any advanced scenario.</description>
/// </item>
/// </list>
/// </remarks>
public virtual async Task<Response<BlobDownloadResult>> DownloadContentAsync(
BlobRequestConditions conditions = default,
Expand Down