Updated DataLakeFileClient.Upload docs to define overwrite expectations; Removed Magic string PathAlreadyExists (Azure#24984)

Author: amnguye

sdk/storage/Azure.Storage.Common/src/Shared/Constants.cs

@@ -334,6 +334,7 @@ internal static class DataLake
             public const string AlreadyExists = "ContainerAlreadyExists";
             public const string FilesystemNotFound = "FilesystemNotFound";
             public const string PathNotFound = "PathNotFound";
+            public const string PathAlreadyExists = "PathAlreadyExists";
 
             /// <summary>
             /// Default concurrent transfers count.

sdk/storage/Azure.Storage.Files.DataLake/src/DataLakeFileClient.cs

@@ -3287,6 +3287,11 @@ public virtual Response<PathInfo> Upload(
         /// The <see cref="Upload(Stream, bool, CancellationToken)"/>
         /// operation creates and uploads content to a file.
         ///
+        /// If the file already exists, then its content will not be overwritten.
+        /// The request will be sent with If-None-Match Header with the value of
+        /// the special wildcard. So if the file already exists a
+        /// <see cref="RequestFailedException"/> is expected to be thrown.
+        ///
         /// For more information, see
         /// <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update" >
         /// Update Path</see>.
@@ -3314,6 +3319,12 @@ public virtual Response<PathInfo> Upload(
         /// The <see cref="Upload(Stream, bool, CancellationToken)"/>
         /// operation creates and uploads content to a file.
         ///
+        /// If the overwrite parameter is not specified and
+        /// the file already exists, then its content will not be overwritten.
+        /// The request will be sent with If-None-Match Header with the value of
+        /// the special wildcard. So if the file already exists a
+        /// <see cref="RequestFailedException"/> is expected to be thrown.
+        ///
         /// For more information, see
         /// <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update" >
         /// Update Path</see>.
@@ -3349,7 +3360,7 @@ public virtual Response<PathInfo> Upload(
 
         /// <summary>
         /// The <see cref="UploadAsync(Stream, DataLakeFileUploadOptions, CancellationToken)"/>
-        /// operation creates and uploads content to a file.If the file already exists, its content will be overwritten,
+        /// operation creates and uploads content to a file. If the file already exists, its content will be overwritten,
         /// unless otherwise specified in the <see cref="DataLakeFileUploadOptions.Conditions"/> or alternatively use
         /// <see cref="UploadAsync(Stream)"/>, <see cref="UploadAsync(Stream, bool, CancellationToken)"/>.
         ///
@@ -3449,6 +3460,11 @@ public virtual Task<Response<PathInfo>> UploadAsync(
         /// The <see cref="UploadAsync(Stream, bool, CancellationToken)"/>
         /// operation creates and uploads content to a file.
         ///
+        /// If the file already exists, then its content will not be overwritten.
+        /// The request will be sent with If-None-Match Header with the value of
+        /// the special wildcard. So if the file already exists a
+        /// <see cref="RequestFailedException"/> is expected to be thrown.
+        ///
         /// For more information, see
         /// <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update" >
         /// Update Path</see>.
@@ -3477,6 +3493,12 @@ public virtual Task<Response<PathInfo>> UploadAsync(
         /// The <see cref="UploadAsync(Stream, bool, CancellationToken)"/>
         /// operation creates and uploads content to a file.
         ///
+        /// If the overwrite parameter is not specified and
+        /// the file already exists, then its content will not be overwritten.
+        /// The request will be sent with If-None-Match Header with the value of
+        /// the special wildcard. So if the file already exists a
+        /// <see cref="RequestFailedException"/> is expected to be thrown.
+        ///
         /// For more information, see
         /// <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update" >
         /// Update Path</see>.
@@ -3620,6 +3642,11 @@ public virtual Response<PathInfo> Upload(
         /// The <see cref="Upload(Stream, bool, CancellationToken)"/>
         /// operation creates and uploads content to a file.
         ///
+        /// If the file already exists, then its content will not be overwritten.
+        /// The request will be sent with If-None-Match Header with the value of
+        /// the special wildcard. So if the file already exists a
+        /// <see cref="RequestFailedException"/> is expected to be thrown.
+        ///
         /// For more information, see
         /// <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update" >
         /// Update Path</see>.
@@ -3648,6 +3675,12 @@ public virtual Response<PathInfo> Upload(
         /// The <see cref="Upload(Stream, bool, CancellationToken)"/>
         /// operation creates and uploads content to a file.
         ///
+        /// If the overwrite parameter is not specified and
+        /// the file already exists, then its content will not be overwritten.
+        /// The request will be sent with If-None-Match Header with the value of
+        /// the special wildcard. So if the file already exists a
+        /// <see cref="RequestFailedException"/> is expected to be thrown.
+        ///
         /// For more information, see
         /// <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update" >
         /// Update Path</see>.
@@ -3789,6 +3822,11 @@ public virtual async Task<Response<PathInfo>> UploadAsync(
         /// The <see cref="UploadAsync(Stream, bool, CancellationToken)"/>
         /// operation creates and uploads content to a file.
         ///
+        /// If the file already exists, then its content will not be overwritten.
+        /// The request will be sent with If-None-Match Header with the value of
+        /// the special wildcard. So if the file already exists a
+        /// <see cref="RequestFailedException"/> is expected to be thrown.
+        ///
         /// For more information, see
         /// <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update" >
         /// Update Path</see>.
@@ -3817,6 +3855,12 @@ await UploadAsync(
         /// The <see cref="UploadAsync(Stream, bool, CancellationToken)"/>
         /// operation creates and uploads content to a file.
         ///
+        /// If the overwrite parameter is not specified and
+        /// the file already exists, then its content will not be overwritten.
+        /// The request will be sent with If-None-Match Header with the value of
+        /// the special wildcard. So if the file already exists a
+        /// <see cref="RequestFailedException"/> is expected to be thrown.
+        ///
         /// For more information, see
         /// <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update" >
         /// Update Path</see>.

sdk/storage/Azure.Storage.Files.DataLake/src/DataLakePathClient.cs

@@ -1153,7 +1153,7 @@ private async Task<Response<PathInfo>> CreateIfNotExistsInternal(
                     cancellationToken).ConfigureAwait(false);
             }
             catch (RequestFailedException storageRequestFailedException)
-            when (storageRequestFailedException.ErrorCode == "PathAlreadyExists")
+            when (storageRequestFailedException.ErrorCode == Constants.DataLake.PathAlreadyExists)
             {
                 response = default;
             }