[Storage][DataMovement] Modify file-share client extensions to match …

…LRO pattern (Azure#47855)

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

@@ -5,6 +5,8 @@
 ### Features Added
 
 ### Breaking Changes
+- Changed `ShareDirectoryClient.StartUploadDirectoryAsync` to `ShareDirectoryClient.UploadDirectoryAsync` and added a required `waitUntil` parameter.
+- Changed `ShareDirectoryClient.StartDownloadToDirectoryAsync` to `ShareDirectoryClient.DownloadToDirectoryAsync` and added a required `waitUntil` parameter.
 
 ### Bugs Fixed
 

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

@@ -49,7 +49,7 @@ namespace Azure.Storage.Files.Shares
 {
     public static partial class ShareDirectoryClientExtensions
     {
-        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; }
-        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; }
+        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; }
+        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; }
     }
 }

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

@@ -49,7 +49,7 @@ namespace Azure.Storage.Files.Shares
 {
     public static partial class ShareDirectoryClientExtensions
     {
-        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; }
-        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; }
+        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; }
+        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; }
     }
 }

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

@@ -49,7 +49,7 @@ namespace Azure.Storage.Files.Shares
 {
     public static partial class ShareDirectoryClientExtensions
     {
-        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; }
-        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; }
+        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; }
+        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; }
     }
 }

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

@@ -2,6 +2,7 @@
 // Licensed under the MIT License.
 
 using System;
+using System.Threading;
 using System.Threading.Tasks;
 using Azure.Storage.DataMovement;
 using Azure.Storage.DataMovement.Files.Shares;
@@ -20,48 +21,91 @@ public static class ShareDirectoryClientExtensions
         /// <summary>
         /// Uploads the entire contents of local directory to the share directory.
         /// </summary>
-        /// <param name="client">
-        /// The <see cref="ShareDirectoryClient"/> used for service operations.
-        /// </param>
-        /// <param name="localDirectoryPath">
-        /// The full path to the local directory to be uploaded.
-        /// </param>
-        /// <param name="options">
-        /// Options which control the directory upload.
+        /// <param name="client">The <see cref="ShareDirectoryClient"/> used for service operations.</param>
+        /// <param name="waitUntil">Indicates whether this invocation should wait until the transfer is complete to return or return immediately.</param>
+        /// <param name="localDirectoryPath">The full path to the local directory to be uploaded.</param>
+        /// <param name="options">Options which control the directory upload.</param>
+        /// <param name="cancellationToken">
+        /// Cancels starting the operation or if <paramref name="waitUntil"/> is set to <see cref="WaitUntil.Completed"/>,
+        /// cancels waiting for the operation. Cancelling this token does not cancel the operation itself.
         /// </param>
         /// <returns>
-        /// A <see cref="TransferOperation"/> instance which can be used track progress and wait for
-        /// completion with <see cref="TransferOperation.WaitForCompletionAsync"/>.
+        /// A <see cref="TransferOperation"/> instance which contains information about the transfer and its status.
         /// </returns>
-        public static async Task<TransferOperation> StartUploadDirectoryAsync(
+        /// <remarks>
+        /// This is an async long-running operation which means the operation may not be complete when this methods returns. If <paramref name="waitUntil"/>
+        /// is set to <see cref="WaitUntil.Started"/>, the method will return as soon as a transfer is started and <see cref="TransferOperation.WaitForCompletionAsync"/>
+        /// 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
+        /// for the entire transfer to complete.
+        /// In either case, the caller must check the status of the transfer using the returned <see cref="TransferOperation"/> instance to determine if the transfer
+        /// 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.
+        /// </remarks>
+        public static async Task<TransferOperation> UploadDirectoryAsync(
             this ShareDirectoryClient client,
+            WaitUntil waitUntil,
             string localDirectoryPath,
-            ShareDirectoryClientTransferOptions options = default)
+            ShareDirectoryClientTransferOptions options = default,
+            CancellationToken cancellationToken = default)
         {
             StorageResource localDirectory = s_localFilesProvider.Value.FromDirectory(localDirectoryPath);
             StorageResource shareDirectory = s_shareFilesProvider.Value.FromClient(client, options?.ShareDirectoryOptions);
 
-            return await s_defaultTransferManager.Value.StartTransferAsync(
-                localDirectory, shareDirectory, options?.TransferOptions).ConfigureAwait(false);
+            TransferOperation trasnfer = await s_defaultTransferManager.Value.StartTransferAsync(
+                localDirectory,
+                shareDirectory,
+                options?.TransferOptions,
+                cancellationToken).ConfigureAwait(false);
+            if (waitUntil == WaitUntil.Completed)
+            {
+                await trasnfer.WaitForCompletionAsync(cancellationToken).ConfigureAwait(false);
+            }
+
+            return trasnfer;
         }
 
         /// <summary>
         /// Downloads the contents of a share directory.
         /// </summary>
         /// <param name="client">The <see cref="ShareDirectoryClient"/> used for service operations.</param>
+        /// <param name="waitUntil">Indicates whether this invocation should wait until the transfer is complete to return or return immediately.</param>
         /// <param name="localDirectoryPath">The full path to the local directory where files will be dowloaded.</param>
         /// <param name="options">Options which control the container download.</param>
-        /// <returns></returns>
-        public static async Task<TransferOperation> StartDownloadToDirectoryAsync(
+        /// <param name="cancellationToken">
+        /// Cancels starting the operation or if <paramref name="waitUntil"/> is set to <see cref="WaitUntil.Completed"/>,
+        /// cancels waiting for the operation. Cancelling this token does not cancel the operation itself.
+        /// </param>
+        /// <returns>
+        /// A <see cref="TransferOperation"/> instance which contains information about the transfer and its status.
+        /// </returns>
+        /// <remarks>
+        /// This is an async long-running operation which means the operation may not be complete when this methods returns. If <paramref name="waitUntil"/>
+        /// is set to <see cref="WaitUntil.Started"/>, the method will return as soon as a transfer is started and <see cref="TransferOperation.WaitForCompletionAsync"/>
+        /// 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
+        /// for the entire transfer to complete.
+        /// In either case, the caller must check the status of the transfer using the returned <see cref="TransferOperation"/> instance to determine if the transfer
+        /// 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.
+        /// </remarks>
+        public static async Task<TransferOperation> DownloadToDirectoryAsync(
             this ShareDirectoryClient client,
+            WaitUntil waitUntil,
             string localDirectoryPath,
-            ShareDirectoryClientTransferOptions options = default)
+            ShareDirectoryClientTransferOptions options = default,
+            CancellationToken cancellationToken = default)
         {
             StorageResource localDirectory = s_localFilesProvider.Value.FromDirectory(localDirectoryPath);
             StorageResource shareDirectory = s_shareFilesProvider.Value.FromClient(client, options?.ShareDirectoryOptions);
 
-            return await s_defaultTransferManager.Value.StartTransferAsync(
-                shareDirectory, localDirectory, options?.TransferOptions).ConfigureAwait(false);
+            TransferOperation trasnfer = await s_defaultTransferManager.Value.StartTransferAsync(
+                shareDirectory,
+                localDirectory,
+                options?.TransferOptions,
+                cancellationToken).ConfigureAwait(false);
+            if (waitUntil == WaitUntil.Completed)
+            {
+                await trasnfer.WaitForCompletionAsync(cancellationToken).ConfigureAwait(false);
+            }
+
+            return trasnfer;
         }
     }
 }

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

@@ -1,14 +1,15 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using System.Threading;
 using Azure.Storage.Files.Shares;
 
 namespace Azure.Storage.DataMovement.Files.Shares
 {
     /// <summary>
     /// Options applying to data transfer uploads and downloads using the <see cref="ShareDirectoryClient"/> extension methods
-    /// <see cref="ShareDirectoryClientExtensions.StartDownloadToDirectoryAsync(ShareDirectoryClient, string, ShareDirectoryClientTransferOptions)"/> and
-    /// <see cref="ShareDirectoryClientExtensions.StartUploadDirectoryAsync(ShareDirectoryClient, string, ShareDirectoryClientTransferOptions)"/>.
+    /// <see cref="ShareDirectoryClientExtensions.DownloadToDirectoryAsync(ShareDirectoryClient, WaitUntil, string, ShareDirectoryClientTransferOptions, CancellationToken)"/> and
+    /// <see cref="ShareDirectoryClientExtensions.UploadDirectoryAsync(ShareDirectoryClient, WaitUntil, string, ShareDirectoryClientTransferOptions, CancellationToken)"/>.
     /// </summary>
     public class ShareDirectoryClientTransferOptions
     {

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

@@ -59,7 +59,11 @@ public async Task StartUploadDirectory([Values(true, false)] bool useOptions)
             string localPath = Path.GetTempPath();
             Mock<ShareDirectoryClient> clientMock = new();
 
-            await Storage.Files.Shares.ShareDirectoryClientExtensions.StartUploadDirectoryAsync(clientMock.Object, localPath, useOptions ? clientTransferOptions : null);
+            await Storage.Files.Shares.ShareDirectoryClientExtensions.UploadDirectoryAsync(
+                clientMock.Object,
+                WaitUntil.Started,
+                localPath,
+                useOptions ? clientTransferOptions : null);
 
             ExtensionMockTransferManager.Verify(tm => tm.StartTransferAsync(
                 It.IsAny<StorageResource>(),
@@ -84,7 +88,11 @@ public async Task StartDownloadDirectory([Values(true, false)] bool useOptions)
             string localPath = Path.GetTempPath();
             Mock<ShareDirectoryClient> clientMock = new();
 
-            await Storage.Files.Shares.ShareDirectoryClientExtensions.StartDownloadToDirectoryAsync(clientMock.Object, localPath, useOptions ? clientTransferOptions : null);
+            await Storage.Files.Shares.ShareDirectoryClientExtensions.DownloadToDirectoryAsync(
+                clientMock.Object,
+                WaitUntil.Started,
+                localPath,
+                useOptions ? clientTransferOptions : null);
 
             ExtensionMockTransferManager.Verify(tm => tm.StartTransferAsync(
                 It.Is<StorageResource>(res => res is ShareDirectoryStorageResourceContainer &&