Add NewFileName parameter to Convert-PnPFile for choosing a custom output filename (#4878)

* Add NewFileName parameter to Convert-PnPFile for custom output filenames

* Update NewFileName parameter to be optional for UploadToSharePoint and improve extension validation

* Expand Warning about extension missmatch.

* Removed Typo

* Updated Parameter Description

* Overwrite Warning should contain the automatic or custom NewFileName

---------

Co-authored-by: Gautam Sheth <[email protected]>

Author: davidschenkUPG

documentation/Convert-PnPFile.md

@@ -77,6 +77,13 @@ Convert-PnPFile -Url "/sites/demo/Shared Documents/Test/Book.png" -ConvertToForm
 
 Retrieves the file and converts to JPG, and save it to the given Document library (Folder) in SharePoint Online (same site collection)
 
+### EXAMPLE 7
+```powershell
+Convert-PnPFile -Url "/sites/demo/Shared Documents/Test/Book.xlsx" -Folder "/sites/demo/Shared Documents/Archive" -NewFileName "differentname.pdf"
+```
+
+Retrieves the file and converts to PDF, and save it to the given Document library (Folder) in SharePoint Online (same site collection) giving it the filename differentname.pdf
+
 ## PARAMETERS
 
 ### -Url
@@ -177,6 +184,20 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -NewFileName
+Filename to give the file local or on SharePoint
+
+```yaml
+Type: String
+Parameter Sets: Save to local path, Upload to SharePoint
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ## RELATED LINKS
 
 [Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

src/Commands/Files/ConvertFile.cs

@@ -36,6 +36,10 @@ public class ConvertFile : PnPWebCmdlet
         [ValidateNotNullOrEmpty]
         public FolderPipeBind Folder;
 
+        [Parameter(Mandatory = false, ParameterSetName = URLTOPATH)]
+        [Parameter(Mandatory = false, ParameterSetName = UPLOADTOSHAREPOINT)]
+        public string NewFileName = string.Empty;
+
         [Parameter(Mandatory = false, ParameterSetName = URLASMEMORYSTREAM)]
         public SwitchParameter AsMemoryStream;
 
@@ -68,18 +72,30 @@ protected override void ExecuteCmdlet()
 
             LogDebug("Converting file to the specified format");
             var convertedFile = sourceFile.ConvertTo(new ConvertToOptions { Format = ConvertToFormat });
+            var newFileExtension = "." + ConvertToFormat.ToString();
 
-            var fileName = System.IO.Path.GetFileNameWithoutExtension(sourceFile.Name);
-            var newFileName = fileName + "." + ConvertToFormat.ToString();
-
+            if (string.IsNullOrEmpty(NewFileName))
+            {
+                // Use original filename with new extension
+                var fileName = System.IO.Path.GetFileNameWithoutExtension(sourceFile.Name);
+                NewFileName = fileName + newFileExtension;
+            }
+            else 
+            {
+                var extensionMatch = System.IO.Path.GetExtension(NewFileName).Equals(newFileExtension, System.StringComparison.OrdinalIgnoreCase);
+                if (!extensionMatch)
+                {
+                    LogWarning($"File extension of NewFileName '{NewFileName}' doesn't match ConvertToFormat '{newFileExtension}'. The new file might become unusable.");
+                }
+            }
             switch (ParameterSetName)
             {
                 case URLTOPATH:
 
-                    var fileOut = System.IO.Path.Combine(Path, newFileName);
+                    var fileOut = System.IO.Path.Combine(Path, NewFileName);
                     if (System.IO.File.Exists(fileOut) && !Force)
                     {
-                        LogWarning($"File '{sourceFile.Name}' exists already. Use the -Force parameter to overwrite the file.");
+                        LogWarning($"File '{NewFileName}' exists already. Use the -Force parameter to overwrite the file.");
                     }
                     else
                     {
@@ -101,7 +117,7 @@ protected override void ExecuteCmdlet()
 
                     LogDebug("Uploading file to the specified folder");
                     var folder = EnsureFolder();
-                    var uploadedFile = folder.UploadFile(newFileName, convertedFile, Force);
+                    var uploadedFile = folder.UploadFile(NewFileName, convertedFile, Force);
 
                     try
                     {