[Storage] [DataMovement] NFS over REST Cleanup (Azure#50304)

* initial commit

* rerecorded tests

* more documentation updates

* tiny test enhancements

* Added additional tests for DestinationOptionsOverride

* tiny test change

Author: nickliu-msft

sdk/storage/Azure.Storage.DataMovement.Blobs.Files.Shares/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "net",
   "TagPrefix": "net/storage/Azure.Storage.DataMovement.Blobs.Files.Shares",
-  "Tag": "net/storage/Azure.Storage.DataMovement.Blobs.Files.Shares_9cbe89e314"
+  "Tag": "net/storage/Azure.Storage.DataMovement.Blobs.Files.Shares_3cdf992080"
 }

sdk/storage/Azure.Storage.DataMovement.Files.Shares/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "net",
   "TagPrefix": "net/storage/Azure.Storage.DataMovement.Files.Shares",
-  "Tag": "net/storage/Azure.Storage.DataMovement.Files.Shares_349100bbca"
+  "Tag": "net/storage/Azure.Storage.DataMovement.Files.Shares_f6f89a43f9"
 }

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

@@ -54,6 +54,15 @@ public static Metadata GetFileMetadata(
                         ? (Metadata)metadata
                         : default;
 
+        public static Metadata GetDirectoryMetadata(
+            this ShareFileStorageResourceOptions options,
+            IDictionary<string, object> properties)
+            => (options?._isDirectoryMetadataSet ?? false)
+                    ? options?.DirectoryMetadata
+                    : properties?.TryGetValue(DataMovementConstants.ResourceProperties.Metadata, out object metadata) == true
+                        ? (Metadata)metadata
+                        : default;
+
         public static string GetFilePermission(
             this ShareFileStorageResourceOptions options,
             StorageResourceItemProperties sourceProperties)

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

@@ -68,8 +68,9 @@ ShareDirectoryStorageResourceContainer destinationStorageResourceContainer
                     = destinationContainer as ShareDirectoryStorageResourceContainer;
                 ShareFileStorageResourceOptions destinationOptions = destinationStorageResourceContainer.ResourceOptions;
                 // both source and destination must be SMB
-                if (((ResourceOptions?.ShareProtocol ?? ShareProtocol.Smb) == ShareProtocol.Smb)
-                    && ((destinationOptions?.ShareProtocol ?? ShareProtocol.Smb) == ShareProtocol.Smb))
+                ShareProtocol sourceShareProtocol = ResourceOptions?.ShareProtocol ?? ShareProtocol.Smb;
+                ShareProtocol destinationShareProtocol = destinationOptions?.ShareProtocol ?? ShareProtocol.Smb;
+                if (sourceShareProtocol == ShareProtocol.Smb && destinationShareProtocol == ShareProtocol.Smb)
                 {
                     traits = ShareFileTraits.Attributes;
                     if (destinationOptions?.FilePermissions ?? false)
@@ -168,7 +169,7 @@ protected override async Task CreateIfNotExistsAsync(
             StorageResourceContainerProperties sourceProperties,
             CancellationToken cancellationToken = default)
         {
-            IDictionary<string, string> metadata = ResourceOptions?.GetFileMetadata(sourceProperties?.RawProperties);
+            IDictionary<string, string> metadata = ResourceOptions?.GetDirectoryMetadata(sourceProperties?.RawProperties);
             string filePermission = ResourceOptions?.GetFilePermission(sourceProperties);
             FileSmbProperties smbProperties = ResourceOptions?.GetFileSmbProperties(sourceProperties);
             FilePosixProperties filePosixProperties = ResourceOptions?.GetFilePosixProperties(sourceProperties);
@@ -196,9 +197,10 @@ protected override async Task ValidateTransferAsync(
             // ShareDirectory to ShareDirectory Copy transfer
             if (sourceResource is ShareDirectoryStorageResourceContainer sourceShareDirectoryResource)
             {
+                ShareProtocol sourceProtocol = sourceShareDirectoryResource.ResourceOptions?.ShareProtocol ?? ShareProtocol.Smb;
+                ShareProtocol destinationProtocol = ResourceOptions?.ShareProtocol ?? ShareProtocol.Smb;
                 // Ensure the transfer is supported (NFS -> NFS and SMB -> SMB)
-                if ((ResourceOptions?.ShareProtocol ?? ShareProtocol.Smb)
-                    != (sourceShareDirectoryResource.ResourceOptions?.ShareProtocol ?? ShareProtocol.Smb))
+                if (destinationProtocol != sourceProtocol)
                 {
                     throw Errors.ShareTransferNotSupported();
                 }

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

@@ -283,8 +283,9 @@ protected override async Task SetPermissionsAsync(
             {
                 ShareFileStorageResource sourceShareFile = (ShareFileStorageResource)sourceResource;
                 // both source and destination must be SMB and destination FilePermission option must be set.
-                if (((sourceShareFile._options?.ShareProtocol ?? ShareProtocol.Smb) == ShareProtocol.Smb)
-                    && ((_options?.ShareProtocol ?? ShareProtocol.Smb) == ShareProtocol.Smb)
+                ShareProtocol sourceShareProtocol = sourceShareFile._options?.ShareProtocol ?? ShareProtocol.Smb;
+                ShareProtocol destinationShareProtocol = _options?.ShareProtocol ?? ShareProtocol.Smb;
+                if (sourceShareProtocol == ShareProtocol.Smb && destinationShareProtocol == ShareProtocol.Smb
                     && (_options?.FilePermissions ?? false))
                 {
                     string permissionsValue = sourceProperties?.RawProperties?.GetPermission();
@@ -394,9 +395,10 @@ protected override async Task ValidateTransferAsync(
             // ShareFile to ShareFile Copy transfer
             if (sourceResource is ShareFileStorageResource sourceShareFileResource)
             {
+                ShareProtocol sourceProtocol = sourceShareFileResource._options?.ShareProtocol ?? ShareProtocol.Smb;
+                ShareProtocol destinationProtocol = _options?.ShareProtocol ?? ShareProtocol.Smb;
                 // Ensure the transfer is supported (NFS -> NFS and SMB -> SMB)
-                if ((_options?.ShareProtocol ?? ShareProtocol.Smb)
-                    != (sourceShareFileResource._options?.ShareProtocol ?? ShareProtocol.Smb))
+                if (destinationProtocol != sourceProtocol)
                 {
                     throw Errors.ShareTransferNotSupported();
                 }

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

@@ -48,7 +48,7 @@ public class ShareFileStorageResourceOptions
 
         /// <summary>
         /// Optional. Specifies whether protocol validation for the resource should be skipped before starting the transfer.
-        /// By default this value is set to false.
+        /// By default this value is set to false. This is intended to be set on the source and destination Share.
         /// Applies to only Share-to-Share copy transfers.
         /// Note: Protocol validation requires share-level read access.
         /// </summary>
@@ -57,11 +57,12 @@ public class ShareFileStorageResourceOptions
         /// <summary>
         /// Optional. Specifies whether the Share uses NFS or SMB protocol.
         /// By default this value is set to SMB.
-        /// Applies to copy, upload, and download transfers.
+        /// This is intended to be set on the source and destination Share.
+        /// Applies to copy, upload, and download transfers. Protocol validation only applies to Share-to-Share copy transfers.
         ///
         /// Note: Only NFS -> NFS and SMB -> SMB transfers are currently supported.
-        /// For NFS Share-to-Share Copy and Download transfers, Hardlinks will be copied as regular files and Symbolic links are skipped.
-        /// For NFS Upload transfers, Hardlinks will be copied as regular files and Symbolic links are not supported.
+        /// For NFS Share-to-Share Copy and Download transfers, Hard links will be copied as regular files and Symbolic links are skipped.
+        /// For NFS Upload transfers, Hard links will be copied as regular files and Symbolic links are not supported.
         /// </summary>
         public ShareProtocol ShareProtocol { get; set; } = ShareProtocol.Smb;
 
@@ -83,9 +84,9 @@ public class ShareFileStorageResourceOptions
 
         /// <summary>
         /// Optional. Sets the Cache Control header which
-        /// specifies directives for caching mechanisms.
+        /// specifies directives for caching mechanisms. This is intended to be set on the destination Share.
         ///
-        /// By default preserves the Cache Control from the source. If explicitly set to null, the Cache Control will not be preserved and set to null.
+        /// By default preserves the Cache Control from the source for copy transfers. If explicitly set, the Cache Control of the destination will be set to this value.
         ///
         /// Applies to upload and copy transfers.
         /// </summary>
@@ -105,9 +106,9 @@ public string CacheControl
         /// payload, and also can be used to attach additional metadata.  For
         /// example, if set to attachment, it indicates that the user-agent
         /// should not display the response, but instead show a Save As dialog
-        /// with a filename other than the blob name specified.
+        /// with a filename other than the blob name specified. This is intended to be set on the destination Share.
         ///
-        /// By default preserves the Content Disposition from the source. If explicitly set to null, the Content Disposition will not be preserved and set to null.
+        /// By default preserves the Content Disposition from the source for copy transfers. If explicitly set, the Content Disposition of the destination will be set to this value.
         ///
         /// Applies to upload and copy transfers.
         /// </summary>
@@ -126,9 +127,9 @@ public string ContentDisposition
         /// specifies which content encodings have been applied to the blob.
         /// This value is returned to the client when the Get Blob operation
         /// is performed on the blob resource. The client can use this value
-        /// when returned to decode the blob content.
+        /// when returned to decode the blob content. This is intended to be set on the destination Share.
         ///
-        /// By default preserves the Content Encoding from the source. If explicitly set to null, the Content Encoding will not be preserved and set to null.
+        /// By default preserves the Content Encoding from the source for copy transfers. If explicitly set, the Content Encoding of the destination will be set to this value.
         ///
         /// Applies to upload and copy transfers.
         /// </summary>
@@ -144,9 +145,9 @@ public string[] ContentEncoding
 
         /// <summary>
         /// Optional. Sets the Content Language header which
-        /// specifies the natural languages used by this resource.
+        /// specifies the natural languages used by this resource. This is intended to be set on the destination Share.
         ///
-        /// By default preserves the Content Language from the source. If explicitly set to null, the Content Language will not be preserved and set to null.
+        /// By default preserves the Content Language from the source for copy transfers. If explicitly set, the Content Language of the destination will be set to this value.
         ///
         /// Applies to upload and copy transfers.
         /// </summary>
@@ -162,9 +163,9 @@ public string[] ContentLanguage
 
         /// <summary>
         /// Optional. Sets the Content Type header which
-        /// specifies the MIME content type of the blob.
+        /// specifies the MIME content type of the file. This is intended to be set on the destination Share.
         ///
-        /// By default preserves the Content Type from the source. If explicitly set to null, the Content Type will not be preserved and set to null.
+        /// By default preserves the Content Type from the source for copy transfers. If explicitly set, the Content Type of the destination will be set to this value.
         ///
         /// Applies to upload and copy transfers.
         /// </summary>
@@ -179,9 +180,9 @@ public string ContentType
         }
 
         /// <summary>
-        /// The file system attributes for this file.
+        /// The file system attributes for this file/directory. This is intended to be set on the destination Share.
         ///
-        /// By default preserves the File Attributes from the source. If explicitly set to null, the File Attributes will not be preserved and set to null.
+        /// By default preserves the Attributes from the source for copy transfers. If explicitly set, the Attributes of the destination will be set to this value.
         /// </summary>
         public NtfsFileAttributes? FileAttributes
         {
@@ -194,20 +195,20 @@ public NtfsFileAttributes? FileAttributes
         }
 
         /// <summary>
-        /// To preserve the file permissions. This is intended to be set on the destination Share.
+        /// To preserve the file/directory permissions. This is intended to be set on the destination Share.
         /// If set to true, the permissions will be preserved from the source Share to the destination Share.
         /// For SMB, this requires a <see href="https://learn.microsoft.com/en-us/rest/api/storageservices/create-permission">Create Share Permissions</see> operation,
         /// which is a operation called on the Destination Share, which requires Share level permissions.
         ///
-        /// By default the file permissions will not be preserved from the source Share to the destination Share. If explicitly set to null, the File Permissions will not be preserved.
+        /// By default the permissions will not be preserved from the source Share to the destination Share. If explicitly set to null, the permissions will not be preserved.
         /// Applies only to copy transfers.
         /// </summary>
         public bool? FilePermissions { get; set; }
 
         /// <summary>
-        /// The creation time of the file.
+        /// The creation time of the file/directory. This is intended to be set on the destination Share.
         ///
-        /// By default preserves the File Created On Time from the source. If explicitly set to null, the File Created On Time will not be preserved and set to `now`.
+        /// By default preserves the Created On Time from the source for copy transfers. If explicitly set, the Created On Time of the destination will be set to this value.
         /// </summary>
         public DateTimeOffset? FileCreatedOn
         {
@@ -220,9 +221,10 @@ public DateTimeOffset? FileCreatedOn
         }
 
         /// <summary>
-        /// The last write time of the file.
+        /// The last write time of the file/directory. This is intended to be set on the destination Share.
         ///
-        /// By default preserves the File Last Written On Time from the source. If explicitly set to null, the File Last Written On Time will not be preserved and set to `now`.
+        /// By default preserves the Last Written On Time from the source for copy transfers. If explicitly set, the Last Written On Time of the destination will be set to this value.
+        /// Note: For share directories, the Last Written On Time may not be preserved.
         /// </summary>
         public DateTimeOffset? FileLastWrittenOn
         {
@@ -235,9 +237,9 @@ public DateTimeOffset? FileLastWrittenOn
         }
 
         /// <summary>
-        /// The change time of the file.
+        /// The change time of the file/directory. This is intended to be set on the destination Share.
         ///
-        /// By default preserves the File Changed On Time from the source. If explicitly set to null, the File Changed On Time will not be preserved and set to `now`.
+        /// By default preserves the Changed On Time from the source for copy transfers. If explicitly set, the Changed On Time of the destination will be set to this value.
         /// </summary>
         public DateTimeOffset? FileChangedOn
         {
@@ -250,11 +252,11 @@ public DateTimeOffset? FileChangedOn
         }
 
         /// <summary>
-        /// Optional. Defines custom metadata to set on the destination resource.
+        /// Optional. Defines custom metadata to set on the destination directory resource. This is intended to be set on the destination Share.
         ///
         /// Applies to upload and copy transfers.
         ///
-        /// Preserves Metadata from the source by default. If explicitly set to null, the Metadata will not be preserved and set to null.
+        /// By default preserves Metadata from the source for copy transfers. If explicitly set, the Metadata of the destination directory will be set to this value.
         /// </summary>
 #pragma warning disable CA2227 // Collection properties should be readonly
         public Metadata DirectoryMetadata
@@ -269,11 +271,11 @@ public Metadata DirectoryMetadata
 #pragma warning restore CA2227 // Collection properties should be readonly
 
         /// <summary>
-        /// Optional. Defines custom metadata to set on the destination resource.
+        /// Optional. Defines custom metadata to set on the destination file resource. This is intended to be set on the destination Share.
         ///
         /// Applies to upload and copy transfers.
         ///
-        /// Preserves Metadata from the source by default. If explicitly set to null, the Metadata will not be preserved and set to null.
+        /// By default preserves Metadata from the source for copy transfers. If explicitly set, the Metadata of the destination file will be set to this value.
         /// </summary>
 #pragma warning disable CA2227 // Collection properties should be readonly
         public Metadata FileMetadata