Feature #3195: Refactor FilePipeBind and MailUtility to improve file handling and update documentation for email attachments (#4570)

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

Author: gautamdsheth

CHANGELOG.md

@@ -37,6 +37,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `-CanSyncHubSitePermissions` parameter to `Set-PnPSite` cmdlet to set value of allowing syncing hub site permissions to this associated site.
 - Added `Get-PnPProfileCardProperty`, `New-PnPProfileCardProperty` and `Remove-PnPProfileCardProperty` cmdlets to manage showing additional properties on the Microsoft 365 user profile [#4548](https://github.com/pnp/powershell/pull/4548)
 - Added `-Contributors` and `-Managers` parameters to `New-PnPTermGroup` and `Set-PnPTermGroup` cmdlets.
+- Added `-Files` parameter for `Send-PnPMail` cmdlet to allow files to be downloaded from SharePoint and then sent as attachments.
 
 ### Changed
 

documentation/Send-PnPMail.md

@@ -14,10 +14,16 @@ Allows sending an e-mail
 
 ## SYNTAX
 
-### Send through Microsoft Graph
+### Send through Microsoft Graph with attachments from local file system
 
 ```powershell
-Send-PnPMail -From <String> -To <String[]> -Subject <String> -Body <String> [-Cc <String[]>] [-Bcc <String[]>] [-ReplyTo <String[]>] [-Importance <MessageImportanceType>] [-BodyContentType <MessageBodyContentType>] [-SaveToSentItems <bool>] [-Connection <PnPConnection>] [-Verbose]
+Send-PnPMail -From <String> -To <String[]> -Subject <String> -Body <String> [-Cc <String[]>] [-Bcc <String[]>] [-ReplyTo <String[]>] [-Importance <MessageImportanceType>] [-BodyContentType <MessageBodyContentType>] [-SaveToSentItems <bool>] [-Connection <PnPConnection>] [-Verbose] [-Attachments <String[]>]
+```
+
+### Send through Microsoft Graph with attachments from SPO
+
+```powershell
+Send-PnPMail -From <String> -To <String[]> -Subject <String> -Body <String> [-Cc <String[]>] [-Bcc <String[]>] [-ReplyTo <String[]>] [-Importance <MessageImportanceType>] [-BodyContentType <MessageBodyContentType>] [-SaveToSentItems <bool>] [-Connection <PnPConnection>] [-Verbose] [-Files <String[]>]
 ```
 
 ### Send through SharePoint Online (Default)
@@ -53,6 +59,20 @@ Send-PnPMail -To "[email protected]" -Subject "Test message" -B
 
 Sends an e-mail using the SharePoint Online SendEmail method using the current context. E-mail is sent from the SharePoint Online no-reply e-mail address and can only be sent to accounts in the same tenant. The from address will show the title of the site you are connected with along with the e-mail address [email protected].
 
+### EXAMPLE 4
+```powershell
+Send-PnPMail -From "[email protected]" -To "[email protected]" -Subject "Test message" -Body "This is a test message" -Attachments "C:\PnPCommunity\Test\test.docx"
+```
+
+Sends an e-mail using Microsoft Graph to one recipient. E-mail is sent from the user specified in the From parameter and can be sent to both internal and external addresses. A copy of the sent e-mail will be stored in the mailbox of the user specified in the From parameter. It will also upload the file from the local file system as attachment.
+
+### EXAMPLE 5
+```powershell
+Send-PnPMail -From "[email protected]" -To "[email protected]" -Subject "Test message" -Body "This is a test message" -Files "/sites/test/Shared Documents/Test.docx"
+```
+
+Sends an e-mail using Microsoft Graph to one recipient. E-mail is sent from the user specified in the From parameter and can be sent to both internal and external addresses. A copy of the sent e-mail will be stored in the mailbox of the user specified in the From parameter. It will also upload the file from the SharePoint site collection and send it as attachment.
+
 ## PARAMETERS
 
 ### -Body
@@ -102,7 +122,7 @@ Allows defining what type of content is in the Body parameter. Defaults to HTML.
 
 ```yaml
 Type: MessageBodyContentType
-Parameter Sets: Send through Microsoft Graph
+Parameter Sets: Send through Microsoft Graph with attachments from SPO, Send through Microsoft Graph with attachments from local file system
 Accepted values: Html, Text
 
 Required: False
@@ -131,7 +151,7 @@ The sender of the e-mail. When Microsoft Graph is used, this can be a user or a
 
 ```yaml
 Type: String
-Parameter Sets: Send through Microsoft Graph
+Parameter Sets: Send through Microsoft Graph with attachments from SPO, Send through Microsoft Graph with attachments from local file system
 
 Required: True
 Position: Named
@@ -145,7 +165,7 @@ Allows defining what the importance of the e-mail is. Defaults to Normal.
 
 ```yaml
 Type: MessageImportanceType
-Parameter Sets: Send through Microsoft Graph
+Parameter Sets: Send through Microsoft Graph with attachments from SPO, Send through Microsoft Graph with attachments from local file system
 Accepted values: Low, Normal, High
 
 Required: False
@@ -160,7 +180,7 @@ List of return addresses to use for the e-mail
 
 ```yaml
 Type: String[]
-Parameter Sets: Send through Microsoft Graph
+Parameter Sets: Send through Microsoft Graph with attachments from SPO, Send through Microsoft Graph with attachments from local file system
 
 Required: False
 Position: Named
@@ -174,7 +194,7 @@ Allows indicating if the sent e-mail should be stored in the Sent Items of the m
 
 ```yaml
 Type: String[]
-Parameter Sets: Send through Microsoft Graph
+Parameter Sets: Send through Microsoft Graph with attachments from SPO, Send through Microsoft Graph with attachments from local file system
 
 Required: False
 Position: Named
@@ -211,6 +231,34 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Attachments
+List of attachments from local file system to be uploaded and sent as attachments.
+
+```yaml
+Type: String[]
+Parameter Sets: Send through Microsoft Graph with attachments from local file system
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Files
+List of files from the SharePoint site collection to be sent as attachments.
+
+```yaml
+Type: String[]
+Parameter Sets: Send through Microsoft Graph with attachments from SPO
+
+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/Base/PipeBinds/FilePipeBind.cs

@@ -1,8 +1,8 @@
-using System;
-using Microsoft.SharePoint.Client;
-using System.Management.Automation;
+using Microsoft.SharePoint.Client;
 using PnP.Core.Model.SharePoint;
 using PnP.Core.Services;
+using System;
+using System.Management.Automation;
 
 namespace PnP.PowerShell.Commands.Base.PipeBinds
 {
@@ -62,7 +62,7 @@ public FilePipeBind(string id)
 
         internal IFile GetCoreFile(PnPContext context, Cmdlet cmdlet = null)
         {
-            if(CoreFile != null)
+            if (CoreFile != null)
             {
                 cmdlet?.WriteVerbose("File determined based on CoreFile instance");
                 return CoreFile;
@@ -128,7 +128,7 @@ internal File GetFile(ClientContext context, Cmdlet cmdlet = null)
             if (!string.IsNullOrEmpty(ServerRelativeUrl))
             {
                 cmdlet?.WriteVerbose("File will be retrieved based on server relative url");
-                return context.Web.GetFileByServerRelativeUrl(ServerRelativeUrl);
+                return context.Web.GetFileByServerRelativePath(ResourcePath.FromDecodedUrl(ServerRelativeUrl));
             }
 
             throw new PSInvalidOperationException("No information available to retrieve file");

src/Commands/Utilities/MailUtility.cs

@@ -1,19 +1,20 @@
-using PnP.PowerShell.Commands.Base;
-using PnP.PowerShell.Commands.Utilities.REST;
-using System.Net.Http;
-using System.Text.Json;
-using System.Text.Json.Serialization;
-using System.Threading.Tasks;
-using PnP.PowerShell.Commands.Model.Mail;
-using Microsoft.SharePoint.Client;
-using System.Collections.Generic;
+using Microsoft.SharePoint.Client;
 using Microsoft.SharePoint.Client.Utilities;
-using System.Net.Mail;
-using System.Net;
+using PnP.Core.Services;
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Base.PipeBinds;
 using PnP.PowerShell.Commands.Enums;
-using System.IO;
+using PnP.PowerShell.Commands.Model.Mail;
+using PnP.PowerShell.Commands.Utilities.REST;
 using System;
+using System.Collections.Generic;
+using System.IO;
 using System.Management.Automation;
+using System.Net;
+using System.Net.Http;
+using System.Net.Mail;
+using System.Text.Json;
+using System.Text.Json.Serialization;
 
 namespace PnP.PowerShell.Commands.Utilities
 {
@@ -192,5 +193,27 @@ public static List<MessageAttachmentOptions> GetListOfAttachments(string[] attac
 
             return messageAttachmentOptions;
         }
+
+        public static List<MessageAttachmentOptions> GetListOfFiles(FilePipeBind[] files, PnPContext context)
+        {
+            if (files == null || files?.Length == 0)
+            {
+                return null;
+            }
+            List<MessageAttachmentOptions> messageAttachmentOptions = new List<MessageAttachmentOptions>();
+            foreach (var file in files)
+            {
+                MessageAttachmentOptions item = new MessageAttachmentOptions();
+                var attachmentFile = file.GetCoreFile(context);
+                item.Type = "#microsoft.graph.fileAttachment";
+                item.Name = attachmentFile.Name;
+                var fileByteArray = attachmentFile.GetContentBytesAsync().GetAwaiter().GetResult();
+                item.ContentBytes = Convert.ToBase64String(fileByteArray);
+                MimeTypeMap.TryGetMimeType(attachmentFile.Name, out var mimeType);
+                item.ContentType = mimeType ?? "text/plain";
+                messageAttachmentOptions.Add(item);
+            }
+            return messageAttachmentOptions;
+        }
     }
 }

src/Commands/Utilities/SendMail.cs

@@ -1,5 +1,7 @@
-using PnP.PowerShell.Commands.Enums;
+using PnP.PowerShell.Commands.Base.PipeBinds;
+using PnP.PowerShell.Commands.Enums;
 using PnP.PowerShell.Commands.Model.Mail;
+using System.Collections.Generic;
 using System.Linq;
 using System.Management.Automation;
 
@@ -8,47 +10,61 @@ namespace PnP.PowerShell.Commands.Utilities
     [Cmdlet(VerbsCommunications.Send, "PnPMail", DefaultParameterSetName = ParameterSet_SENDTHROUGHSPO)]
     public class SendMail : PnPWebCmdlet
     {
-        private const string ParameterSet_SENDTHROUGHGRAPH = "Send through Microsoft Graph";
+        private const string ParameterSet_SENDTHROUGHGRAPH = "Send through Microsoft Graph with attachments from local file system";
         private const string ParameterSet_SENDTHROUGHSPO = "Send through SharePoint Online";
+        private const string ParameterSet_SENDTHROUGHGRAPHWITHFILES = "Send through Microsoft Graph with attachments from SPO";
 
         [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
+        [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
         public string From;
 
         [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
         [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHSPO)]
+        [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
         public string[] To;
 
         [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
         [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHSPO)]
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
         public string[] Cc;
 
         [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
         [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHSPO)]
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
         public string[] Bcc;
 
         [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
         [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHSPO)]
+        [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
         public string Subject;
 
         [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
         [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHSPO)]
+        [Parameter(Mandatory = true, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
         public string Body;
 
         [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
         public MessageImportanceType Importance;
 
         [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
         public string[] ReplyTo;
 
         [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
         public bool? SaveToSentItems;
 
         [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
         public MessageBodyContentType? BodyContentType;
 
         [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPH)]
         public string[] Attachments;
 
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSet_SENDTHROUGHGRAPHWITHFILES)]
+        public FilePipeBind[] Files;
+
         protected override void ExecuteCmdlet()
         {
             if (string.IsNullOrWhiteSpace(From))
@@ -60,6 +76,16 @@ protected override void ExecuteCmdlet()
             else
             {
                 WriteVerbose($"Sending e-mail using Microsoft Graph");
+                List<MessageAttachmentOptions> messageAttachmentOptions = null;
+                if (ParameterSpecified(nameof(Attachments)))
+                {
+                    messageAttachmentOptions = MailUtility.GetListOfAttachments(Attachments, SessionState.Path.CurrentFileSystemLocation.Path);
+                }
+                else if (ParameterSpecified(nameof(Files)))
+                {
+                    messageAttachmentOptions = MailUtility.GetListOfFiles(Files, Connection.PnPContext);
+                }
+
                 MailUtility.SendGraphMail(this, Connection, GraphAccessToken, new Message
                 {
                     Subject = Subject,
@@ -74,7 +100,7 @@ protected override void ExecuteCmdlet()
                     Sender = new Recipient { EmailAddress = new EmailAddress { Address = From } },
                     ReplyTo = ReplyTo?.Select(t => new Recipient { EmailAddress = new EmailAddress { Address = t } }).ToList(),
                     Importance = Importance,
-                    Attachments = MailUtility.GetListOfAttachments(Attachments, SessionState.Path.CurrentFileSystemLocation.Path)
+                    Attachments = messageAttachmentOptions
                 }, SaveToSentItems ?? true);
             }