Skip to content

Commit 5eda9c7

Browse files
jalauzon-msftjalauzon-msft
authored
[Storage][DataMovement] Modify file-share client extensions to match LRO pattern (Azure#47855)
1 parent 3c2ffb1 commit 5eda9c7

7 files changed

+84
-29
lines changed

‎sdk/storage/Azure.Storage.DataMovement.Files.Shares/CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
### Features Added
66

77
### Breaking Changes
8+
- Changed `ShareDirectoryClient.StartUploadDirectoryAsync` to `ShareDirectoryClient.UploadDirectoryAsync` and added a required `waitUntil` parameter.
9+
- Changed `ShareDirectoryClient.StartDownloadToDirectoryAsync` to `ShareDirectoryClient.DownloadToDirectoryAsync` and added a required `waitUntil` parameter.
810

911
### Bugs Fixed
1012

‎sdk/storage/Azure.Storage.DataMovement.Files.Shares/api/Azure.Storage.DataMovement.Files.Shares.net6.0.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ namespace Azure.Storage.Files.Shares
4949
{
5050
public static partial class ShareDirectoryClientExtensions
5151
{
52-
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> StartDownloadToDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null) { throw null; }
53-
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> StartUploadDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null) { throw null; }
52+
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> DownloadToDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, Azure.WaitUntil waitUntil, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
53+
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> UploadDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, Azure.WaitUntil waitUntil, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
5454
}
5555
}

‎sdk/storage/Azure.Storage.DataMovement.Files.Shares/api/Azure.Storage.DataMovement.Files.Shares.net8.0.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ namespace Azure.Storage.Files.Shares
4949
{
5050
public static partial class ShareDirectoryClientExtensions
5151
{
52-
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> StartDownloadToDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null) { throw null; }
53-
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> StartUploadDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null) { throw null; }
52+
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> DownloadToDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, Azure.WaitUntil waitUntil, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
53+
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> UploadDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, Azure.WaitUntil waitUntil, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
5454
}
5555
}

‎sdk/storage/Azure.Storage.DataMovement.Files.Shares/api/Azure.Storage.DataMovement.Files.Shares.netstandard2.0.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ namespace Azure.Storage.Files.Shares
4949
{
5050
public static partial class ShareDirectoryClientExtensions
5151
{
52-
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> StartDownloadToDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null) { throw null; }
53-
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> StartUploadDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null) { throw null; }
52+
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> DownloadToDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, Azure.WaitUntil waitUntil, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
53+
public static System.Threading.Tasks.Task<Azure.Storage.DataMovement.TransferOperation> UploadDirectoryAsync(this Azure.Storage.Files.Shares.ShareDirectoryClient client, Azure.WaitUntil waitUntil, string localDirectoryPath, Azure.Storage.DataMovement.Files.Shares.ShareDirectoryClientTransferOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
5454
}
5555
}

‎sdk/storage/Azure.Storage.DataMovement.Files.Shares/src/ShareDirectoryClientExtensions.cs‎

Lines changed: 63 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
// Licensed under the MIT License.
33

44
using System;
5+
using System.Threading;
56
using System.Threading.Tasks;
67
using Azure.Storage.DataMovement;
78
using Azure.Storage.DataMovement.Files.Shares;
@@ -20,48 +21,91 @@ public static class ShareDirectoryClientExtensions
2021
/// <summary>
2122
/// Uploads the entire contents of local directory to the share directory.
2223
/// </summary>
23-
/// <param name="client">
24-
/// The <see cref="ShareDirectoryClient"/> used for service operations.
25-
/// </param>
26-
/// <param name="localDirectoryPath">
27-
/// The full path to the local directory to be uploaded.
28-
/// </param>
29-
/// <param name="options">
30-
/// Options which control the directory upload.
24+
/// <param name="client">The <see cref="ShareDirectoryClient"/> used for service operations.</param>
25+
/// <param name="waitUntil">Indicates whether this invocation should wait until the transfer is complete to return or return immediately.</param>
26+
/// <param name="localDirectoryPath">The full path to the local directory to be uploaded.</param>
27+
/// <param name="options">Options which control the directory upload.</param>
28+
/// <param name="cancellationToken">
29+
/// Cancels starting the operation or if <paramref name="waitUntil"/> is set to <see cref="WaitUntil.Completed"/>,
30+
/// cancels waiting for the operation. Cancelling this token does not cancel the operation itself.
3131
/// </param>
3232
/// <returns>
33-
/// A <see cref="TransferOperation"/> instance which can be used track progress and wait for
34-
/// completion with <see cref="TransferOperation.WaitForCompletionAsync"/>.
33+
/// A <see cref="TransferOperation"/> instance which contains information about the transfer and its status.
3534
/// </returns>
36-
public static async Task<TransferOperation> StartUploadDirectoryAsync(
35+
/// <remarks>
36+
/// This is an async long-running operation which means the operation may not be complete when this methods returns. If <paramref name="waitUntil"/>
37+
/// is set to <see cref="WaitUntil.Started"/>, the method will return as soon as a transfer is started and <see cref="TransferOperation.WaitForCompletionAsync"/>
38+
/// can be used to wait for the transfer to complete. If <paramref name="waitUntil"/> is set to <see cref="WaitUntil.Completed"/>, the method will wait
39+
/// for the entire transfer to complete.
40+
/// In either case, the caller must check the status of the transfer using the returned <see cref="TransferOperation"/> instance to determine if the transfer
41+
/// completed successfully or not. This method will not throw an exception if the transfer fails, but the <see cref="TransferOperation.Status"/> will indicate a failure.
42+
/// </remarks>
43+
public static async Task<TransferOperation> UploadDirectoryAsync(
3744
this ShareDirectoryClient client,
45+
WaitUntil waitUntil,
3846
string localDirectoryPath,
39-
ShareDirectoryClientTransferOptions options = default)
47+
ShareDirectoryClientTransferOptions options = default,
48+
CancellationToken cancellationToken = default)
4049
{
4150
StorageResource localDirectory = s_localFilesProvider.Value.FromDirectory(localDirectoryPath);
4251
StorageResource shareDirectory = s_shareFilesProvider.Value.FromClient(client, options?.ShareDirectoryOptions);
4352

44-
return await s_defaultTransferManager.Value.StartTransferAsync(
45-
localDirectory, shareDirectory, options?.TransferOptions).ConfigureAwait(false);
53+
TransferOperation trasnfer = await s_defaultTransferManager.Value.StartTransferAsync(
54+
localDirectory,
55+
shareDirectory,
56+
options?.TransferOptions,
57+
cancellationToken).ConfigureAwait(false);
58+
if (waitUntil == WaitUntil.Completed)
59+
{
60+
await trasnfer.WaitForCompletionAsync(cancellationToken).ConfigureAwait(false);
61+
}
62+
63+
return trasnfer;
4664
}
4765

4866
/// <summary>
4967
/// Downloads the contents of a share directory.
5068
/// </summary>
5169
/// <param name="client">The <see cref="ShareDirectoryClient"/> used for service operations.</param>
70+
/// <param name="waitUntil">Indicates whether this invocation should wait until the transfer is complete to return or return immediately.</param>
5271
/// <param name="localDirectoryPath">The full path to the local directory where files will be dowloaded.</param>
5372
/// <param name="options">Options which control the container download.</param>
54-
/// <returns></returns>
55-
public static async Task<TransferOperation> StartDownloadToDirectoryAsync(
73+
/// <param name="cancellationToken">
74+
/// Cancels starting the operation or if <paramref name="waitUntil"/> is set to <see cref="WaitUntil.Completed"/>,
75+
/// cancels waiting for the operation. Cancelling this token does not cancel the operation itself.
76+
/// </param>
77+
/// <returns>
78+
/// A <see cref="TransferOperation"/> instance which contains information about the transfer and its status.
79+
/// </returns>
80+
/// <remarks>
81+
/// This is an async long-running operation which means the operation may not be complete when this methods returns. If <paramref name="waitUntil"/>
82+
/// is set to <see cref="WaitUntil.Started"/>, the method will return as soon as a transfer is started and <see cref="TransferOperation.WaitForCompletionAsync"/>
83+
/// can be used to wait for the transfer to complete. If <paramref name="waitUntil"/> is set to <see cref="WaitUntil.Completed"/>, the method will wait
84+
/// for the entire transfer to complete.
85+
/// In either case, the caller must check the status of the transfer using the returned <see cref="TransferOperation"/> instance to determine if the transfer
86+
/// completed successfully or not. This method will not throw an exception if the transfer fails, but the <see cref="TransferOperation.Status"/> will indicate a failure.
87+
/// </remarks>
88+
public static async Task<TransferOperation> DownloadToDirectoryAsync(
5689
this ShareDirectoryClient client,
90+
WaitUntil waitUntil,
5791
string localDirectoryPath,
58-
ShareDirectoryClientTransferOptions options = default)
92+
ShareDirectoryClientTransferOptions options = default,
93+
CancellationToken cancellationToken = default)
5994
{
6095
StorageResource localDirectory = s_localFilesProvider.Value.FromDirectory(localDirectoryPath);
6196
StorageResource shareDirectory = s_shareFilesProvider.Value.FromClient(client, options?.ShareDirectoryOptions);
6297

63-
return await s_defaultTransferManager.Value.StartTransferAsync(
64-
shareDirectory, localDirectory, options?.TransferOptions).ConfigureAwait(false);
98+
TransferOperation trasnfer = await s_defaultTransferManager.Value.StartTransferAsync(
99+
shareDirectory,
100+
localDirectory,
101+
options?.TransferOptions,
102+
cancellationToken).ConfigureAwait(false);
103+
if (waitUntil == WaitUntil.Completed)
104+
{
105+
await trasnfer.WaitForCompletionAsync(cancellationToken).ConfigureAwait(false);
106+
}
107+
108+
return trasnfer;
65109
}
66110
}
67111
}

‎sdk/storage/Azure.Storage.DataMovement.Files.Shares/src/ShareDirectoryClientTransferOptions.cs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved.
22
// Licensed under the MIT License.
33

4+
using System.Threading;
45
using Azure.Storage.Files.Shares;
56

67
namespace Azure.Storage.DataMovement.Files.Shares
78
{
89
/// <summary>
910
/// Options applying to data transfer uploads and downloads using the <see cref="ShareDirectoryClient"/> extension methods
10-
/// <see cref="ShareDirectoryClientExtensions.StartDownloadToDirectoryAsync(ShareDirectoryClient, string, ShareDirectoryClientTransferOptions)"/> and
11-
/// <see cref="ShareDirectoryClientExtensions.StartUploadDirectoryAsync(ShareDirectoryClient, string, ShareDirectoryClientTransferOptions)"/>.
11+
/// <see cref="ShareDirectoryClientExtensions.DownloadToDirectoryAsync(ShareDirectoryClient, WaitUntil, string, ShareDirectoryClientTransferOptions, CancellationToken)"/> and
12+
/// <see cref="ShareDirectoryClientExtensions.UploadDirectoryAsync(ShareDirectoryClient, WaitUntil, string, ShareDirectoryClientTransferOptions, CancellationToken)"/>.
1213
/// </summary>
1314
public class ShareDirectoryClientTransferOptions
1415
{

‎sdk/storage/Azure.Storage.DataMovement.Files.Shares/tests/ShareDirectoryClientExtensionsTests.cs‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,11 @@ public async Task StartUploadDirectory([Values(true, false)] bool useOptions)
5959
string localPath = Path.GetTempPath();
6060
Mock<ShareDirectoryClient> clientMock = new();
6161

62-
await Storage.Files.Shares.ShareDirectoryClientExtensions.StartUploadDirectoryAsync(clientMock.Object, localPath, useOptions ? clientTransferOptions : null);
62+
await Storage.Files.Shares.ShareDirectoryClientExtensions.UploadDirectoryAsync(
63+
clientMock.Object,
64+
WaitUntil.Started,
65+
localPath,
66+
useOptions ? clientTransferOptions : null);
6367

6468
ExtensionMockTransferManager.Verify(tm => tm.StartTransferAsync(
6569
It.IsAny<StorageResource>(),
@@ -84,7 +88,11 @@ public async Task StartDownloadDirectory([Values(true, false)] bool useOptions)
8488
string localPath = Path.GetTempPath();
8589
Mock<ShareDirectoryClient> clientMock = new();
8690

87-
await Storage.Files.Shares.ShareDirectoryClientExtensions.StartDownloadToDirectoryAsync(clientMock.Object, localPath, useOptions ? clientTransferOptions : null);
91+
await Storage.Files.Shares.ShareDirectoryClientExtensions.DownloadToDirectoryAsync(
92+
clientMock.Object,
93+
WaitUntil.Started,
94+
localPath,
95+
useOptions ? clientTransferOptions : null);
8896

8997
ExtensionMockTransferManager.Verify(tm => tm.StartTransferAsync(
9098
It.Is<StorageResource>(res => res is ShareDirectoryStorageResourceContainer &&

0 commit comments

Comments
 (0)