From 6c65d8401b81ddb178b0a01439197a290dda8dbf Mon Sep 17 00:00:00 2001 From: Gautam Sheth Date: Sat, 17 Jun 2023 23:24:00 +0300 Subject: [PATCH 1/2] Feature: added file and folder sharing invite cmdlets --- documentation/Add-PnPFileSharingInvite.md | 153 ++++++++++++++++++ .../Add-PnPFolderAnonymousSharingLink.md | 2 +- documentation/Add-PnPFolderSharingInvite.md | 153 ++++++++++++++++++ src/Commands/Security/AddFileSharingInvite.cs | 96 +++++++++++ .../Security/AddFolderSharingInvite.cs | 87 ++++++++++ 5 files changed, 490 insertions(+), 1 deletion(-) create mode 100644 documentation/Add-PnPFileSharingInvite.md create mode 100644 documentation/Add-PnPFolderSharingInvite.md create mode 100644 src/Commands/Security/AddFileSharingInvite.cs create mode 100644 src/Commands/Security/AddFolderSharingInvite.cs diff --git a/documentation/Add-PnPFileSharingInvite.md b/documentation/Add-PnPFileSharingInvite.md new file mode 100644 index 000000000..44cfc3048 --- /dev/null +++ b/documentation/Add-PnPFileSharingInvite.md @@ -0,0 +1,153 @@ +--- +Module Name: PnP.PowerShell +schema: 2.0.0 +applicable: SharePoint Online +online version: https://pnp.github.io/powershell/cmdlets/Add-PnPFileSharingInvite.html +external help file: PnP.PowerShell.dll-Help.xml +title: Add-PnPFileSharingInvite +--- + +# Add-PnPFileSharingInvite + +## SYNOPSIS +Creates an invitation for users to a file. + +## SYNTAX + +```powershell +Add-PnPFileSharingInvite -FileUrl -Users -Message -RequireSignIn -SendInvitation -Role -ExpirationDateTime [-Connection ] +``` + +## DESCRIPTION + +Creates an invitation for users to a file. + +## EXAMPLES + +### EXAMPLE 1 +```powershell +Add-PnPFileSharingInvite -FileUrl "/sites/demo/Shared Documents/Test.docx" -Users "john@contoso.onmicrosoft.com" -RequireSignIn +``` + +This will invite the user `John@contoso.onmicrosoft.com` to the `Test.docx` file with Read permissions and will require that user to sign in before accessing the file. + +### EXAMPLE 2 +```powershell +Add-PnPFileSharingInvite -FileUrl "/sites/demo/Shared Documents/Test.docx" -Users "john@contoso.onmicrosoft.com" -RequireSignIn -SendInvitation -Role Owner +``` + +This will invite the user `John@contoso.onmicrosoft.com` to the `Test.docx` file with Read permissions and will require that user to sign in before accessing the file. The invitation will be sent and the user will have `Owner` permissions + +### EXAMPLE 3 +```powershell +Add-PnPFileSharingInvite -FileUrl "/sites/demo/Shared Documents/Test.docx" -Users "john@contoso.onmicrosoft.com" -RequireSignIn -ExpirationDate (Get-Date).AddDays(15) +``` + +This will invite the user `John@contoso.onmicrosoft.com` to the `Test.docx` file with Read permissions and will require that user to sign in before accessing the file. The link will expire after 15 days. + +## PARAMETERS + +### -Connection +Optional connection to be used by the cmdlet. Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection. + +```yaml +Type: PnPConnection +Parameter Sets: (All) + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FileUrl +The FileUrl in the site + +```yaml +Type: String +Parameter Sets: (All) + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Users +A collection of recipients who will receive access and the sharing invitation. +**Currently, only one user at a time is supported**. We are planning to add support for multiple users a bit later. + +```yaml +Type: String[] +Parameter Sets: (All) + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RequireSignIn +Specifies where the recipient of the invitation is required to sign-in to view the shared item + +```yaml +Type: SwitchParamter +Parameter Sets: (All) + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SendInvitation +Specifies if an email or post is generated (false) or if the permission is just created (true). + +```yaml +Type: SwitchParamter +Parameter Sets: (All) + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Role +Specify the role that is to be granted to the recipients of the sharing invitation. + +Supported values are `Owner`, `Write` and `Read`. + +```yaml +Type: PnP.Core.Model.Security.PermissionRole +Parameter Sets: (All) + +Required: False +Position: Named +Default value: Read +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExpirationDateTime +The expiration date for the FileUrl after which the permission expires. + +```yaml +Type: String +Parameter Sets: (All) + +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) diff --git a/documentation/Add-PnPFolderAnonymousSharingLink.md b/documentation/Add-PnPFolderAnonymousSharingLink.md index a3865d5a7..067f70109 100644 --- a/documentation/Add-PnPFolderAnonymousSharingLink.md +++ b/documentation/Add-PnPFolderAnonymousSharingLink.md @@ -38,7 +38,7 @@ Add-PnPFolderAnonymousSharingLink -Folder "/sites/demo/Shared Documents/Test" -T This will create an anonymous sharing link for `Test` folder in the `Shared Documents` library which will be editable by anonymous users with the specified password. -### EXAMPLE 2 +### EXAMPLE 3 ```powershell Add-PnPFolderAnonymousSharingLink -Folder "/sites/demo/Shared Documents/Test" -Type Edit -Password "PnPRocks!" -ExpirationDateTime (Get-Date).AddDays(15) ``` diff --git a/documentation/Add-PnPFolderSharingInvite.md b/documentation/Add-PnPFolderSharingInvite.md new file mode 100644 index 000000000..503d9744e --- /dev/null +++ b/documentation/Add-PnPFolderSharingInvite.md @@ -0,0 +1,153 @@ +--- +Module Name: PnP.PowerShell +schema: 2.0.0 +applicable: SharePoint Online +online version: https://pnp.github.io/powershell/cmdlets/Add-PnPFolderSharingInvite.html +external help file: PnP.PowerShell.dll-Help.xml +title: Add-PnPFolderSharingInvite +--- + +# Add-PnPFolderSharingInvite + +## SYNOPSIS +Creates an invitation for users to a folder. + +## SYNTAX + +```powershell +Add-PnPFolderSharingInvite -Folder -Users -Message -RequireSignIn -SendInvitation -Role -ExpirationDateTime [-Connection ] +``` + +## DESCRIPTION + +Creates an invitation for user to a folder. + +## EXAMPLES + +### EXAMPLE 1 +```powershell +Add-PnPFolderSharingInvite -Folder "/sites/demo/Shared Documents/Test" -Users "john@contoso.onmicrosoft.com" -RequireSignIn +``` + +This will invite the user `John@contoso.onmicrosoft.com` to the `Test` folder with Read permissions and will require that user to sign in before accessing the folder. + +### EXAMPLE 2 +```powershell +Add-PnPFolderSharingInvite -Folder "/sites/demo/Shared Documents/Test" -Users "john@contoso.onmicrosoft.com" -RequireSignIn -SendInvitation -Role Owner +``` + +This will invite the user `John@contoso.onmicrosoft.com` to the `Test` folder with Read permissions and will require that user to sign in before accessing the folder. The invitation will be sent and the user will have `Owner` permissions + +### EXAMPLE 3 +```powershell +Add-PnPFolderSharingInvite -Folder "/sites/demo/Shared Documents/Test" -Users "john@contoso.onmicrosoft.com" -RequireSignIn -ExpirationDate (Get-Date).AddDays(15) +``` + +This will invite the user `John@contoso.onmicrosoft.com` to the `Test` folder with Read permissions and will require that user to sign in before accessing the folder. The link will expire after 15 days. + +## PARAMETERS + +### -Connection +Optional connection to be used by the cmdlet. Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection. + +```yaml +Type: PnPConnection +Parameter Sets: (All) + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Folder +The folder in the site + +```yaml +Type: FolderPipeBind +Parameter Sets: (All) + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Users +A collection of recipients who will receive access and the sharing invitation. +**Currently, only one user at a time is supported**. We are planning to add support for multiple users a bit later. + +```yaml +Type: String[] +Parameter Sets: (All) + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RequireSignIn +Specifies where the recipient of the invitation is required to sign-in to view the shared item + +```yaml +Type: SwitchParamter +Parameter Sets: (All) + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SendInvitation +Specifies if an email or post is generated (false) or if the permission is just created (true). + +```yaml +Type: SwitchParamter +Parameter Sets: (All) + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Role +Specify the role that is to be granted to the recipients of the sharing invitation. + +Supported values are `Owner`, `Write` and `Read`. + +```yaml +Type: PnP.Core.Model.Security.PermissionRole +Parameter Sets: (All) + +Required: False +Position: Named +Default value: Read +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExpirationDateTime +The expiration date for the folder after which the permission expires. + +```yaml +Type: String +Parameter Sets: (All) + +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) diff --git a/src/Commands/Security/AddFileSharingInvite.cs b/src/Commands/Security/AddFileSharingInvite.cs new file mode 100644 index 000000000..e87da7497 --- /dev/null +++ b/src/Commands/Security/AddFileSharingInvite.cs @@ -0,0 +1,96 @@ +using PnP.Core.Model.Security; +using PnP.Framework.Utilities; +using System; +using System.Collections.Generic; +using System.Management.Automation; + +namespace PnP.PowerShell.Commands.Security +{ + [Cmdlet(VerbsCommon.Add, "PnPFileSharingInvite")] + [OutputType(typeof(void))] + public class AddFileSharingInvite : PnPWebCmdlet + { + [Parameter(Mandatory = true)] + public string FileUrl; + + [Parameter(Mandatory = true)] + public string[] Users; + + [Parameter(Mandatory = false)] + public string Message = string.Empty; + + [Parameter(Mandatory = false)] + public SwitchParameter RequireSignIn; + + [Parameter(Mandatory = false)] + public SwitchParameter SendInvitation; + + [Parameter(Mandatory = false)] + public PermissionRole Role = PermissionRole.Read; + + [Parameter(Mandatory = false)] + public DateTime ExpirationDateTime; + + protected override void ExecuteCmdlet() + { + if (!RequireSignIn && !SendInvitation) + { + throw new ArgumentException("RequireSignIn and SendInvitation both cannot be false."); + } + + if (Users?.Length > 1) + { + throw new ArgumentException("You can only invite one user at a time."); + } + + var serverRelativeUrl = string.Empty; + var ctx = Connection.PnPContext; + + ctx.Web.EnsureProperties(w => w.ServerRelativeUrl); + + if (!FileUrl.ToLower().StartsWith(ctx.Web.ServerRelativeUrl.ToLower())) + { + serverRelativeUrl = UrlUtility.Combine(ctx.Web.ServerRelativeUrl, FileUrl); + } + else + { + serverRelativeUrl = FileUrl; + } + + var file = ctx.Web.GetFileByServerRelativeUrl(serverRelativeUrl); + + // List of users to share the file/folder with + var driveRecipients = new List(); + foreach (var user in Users) + { + var driveRecipient = InviteOptions.CreateDriveRecipient(user); + driveRecipients.Add(driveRecipient); + } + + if (ParameterSpecified(nameof(Message)) && !string.IsNullOrEmpty(Message)) + { + if (Message.Length > 2000) + { + WriteVerbose("Invitation message length cannot exceed 2000 characters, trimming the message"); + Message = Message.Substring(0, 2000); + } + } + + var shareRequestOptions = new InviteOptions() + { + Message = Message, + RequireSignIn = RequireSignIn, + SendInvitation = SendInvitation, + Recipients = driveRecipients, + Roles = new List { Role } + }; + + if (ParameterSpecified(nameof(ExpirationDateTime))) + { + shareRequestOptions.ExpirationDateTime = ExpirationDateTime; + } + + var share = file.CreateSharingInvite(shareRequestOptions); + } + } +} diff --git a/src/Commands/Security/AddFolderSharingInvite.cs b/src/Commands/Security/AddFolderSharingInvite.cs new file mode 100644 index 000000000..e4a838a04 --- /dev/null +++ b/src/Commands/Security/AddFolderSharingInvite.cs @@ -0,0 +1,87 @@ +using PnP.Core.Model.Security; +using PnP.PowerShell.Commands.Base.PipeBinds; +using System; +using System.Collections.Generic; +using System.Management.Automation; + +namespace PnP.PowerShell.Commands.Security +{ + [Cmdlet(VerbsCommon.Add, "PnPFolderSharingInvite")] + [OutputType(typeof(void))] + public class AddFolderSharingInvite : PnPWebCmdlet + { + [Parameter(Mandatory = true)] + public FolderPipeBind Folder; + + [Parameter(Mandatory = true)] + public string[] Users; + + [Parameter(Mandatory = false)] + public string Message = string.Empty; + + [Parameter(Mandatory = false)] + public SwitchParameter RequireSignIn; + + [Parameter(Mandatory = false)] + public SwitchParameter SendInvitation; + + [Parameter(Mandatory = false)] + public PermissionRole Role = PermissionRole.Read; + + [Parameter(Mandatory = false)] + public DateTime ExpirationDateTime; + + protected override void ExecuteCmdlet() + { + if (!RequireSignIn && !SendInvitation) + { + throw new ArgumentException("RequireSignIn and SendInvitation both cannot be false."); + } + + if (Users?.Length > 1) + { + throw new ArgumentException("You can only invite one user at a time."); + } + + var serverRelativeUrl = string.Empty; + var ctx = Connection.PnPContext; + + ctx.Web.EnsureProperties(w => w.ServerRelativeUrl); + + var folder = Folder.GetFolder(ctx); + + // List of users to share the file/folder with + var driveRecipients = new List(); + foreach (var user in Users) + { + var driveRecipient = InviteOptions.CreateDriveRecipient(user); + driveRecipients.Add(driveRecipient); + } + + if (ParameterSpecified(nameof(Message)) && !string.IsNullOrEmpty(Message)) + { + if (Message.Length > 2000) + { + WriteVerbose("Invitation message length cannot exceed 2000 characters, trimming the message"); + Message = Message.Substring(0, 2000); + } + } + + var shareRequestOptions = new InviteOptions() + { + Message = Message, + RequireSignIn = RequireSignIn, + SendInvitation = SendInvitation, + Recipients = driveRecipients, + Roles = new List { Role } + }; + + if (ParameterSpecified(nameof(ExpirationDateTime))) + { + shareRequestOptions.ExpirationDateTime = ExpirationDateTime; + } + + var share = folder.CreateSharingInvite(shareRequestOptions); + } + } +} From 957b5eafb038a55694c51ef67d0898068c722926 Mon Sep 17 00:00:00 2001 From: Gautam Sheth Date: Sat, 17 Jun 2023 23:35:00 +0300 Subject: [PATCH 2/2] Added missing message parameter --- documentation/Add-PnPFileSharingInvite.md | 14 ++++++++++++++ documentation/Add-PnPFolderSharingInvite.md | 14 ++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/documentation/Add-PnPFileSharingInvite.md b/documentation/Add-PnPFileSharingInvite.md index 44cfc3048..dca37f7f8 100644 --- a/documentation/Add-PnPFileSharingInvite.md +++ b/documentation/Add-PnPFileSharingInvite.md @@ -90,6 +90,20 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Message +A plain text formatted message that is included in the sharing invitation. Maximum length 2000 characters. + +```yaml +Type: String +Parameter Sets: (All) + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -RequireSignIn Specifies where the recipient of the invitation is required to sign-in to view the shared item diff --git a/documentation/Add-PnPFolderSharingInvite.md b/documentation/Add-PnPFolderSharingInvite.md index 503d9744e..e5a10de37 100644 --- a/documentation/Add-PnPFolderSharingInvite.md +++ b/documentation/Add-PnPFolderSharingInvite.md @@ -90,6 +90,20 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Message +A plain text formatted message that is included in the sharing invitation. Maximum length 2000 characters. + +```yaml +Type: String +Parameter Sets: (All) + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -RequireSignIn Specifies where the recipient of the invitation is required to sign-in to view the shared item