New cmdlet to update retention label on file

documentation/Get-PnPFileRetentionLabel.md

@@ -35,8 +35,6 @@ This example retrieves the retention label information for the file at the speci
 Get-PnPFileRetentionLabel -Url "/sites/Marketing/Shared Documents/Report.pptx"
 ```
 
-This example retrieves the retention label information for the file at the specified URL.
-
 ## PARAMETERS
 
 ### -Url

documentation/Set-PnPFileRetentionLabel.md

@@ -0,0 +1,87 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Set-PnPFileRetentionLabel.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Set-PnPFileRetentionLabel
+---
+
+# Set-PnPFileRetentionLabel
+
+## SYNOPSIS
+
+**Required Permissions**
+
+  * Microsoft Graph API : One of Files.Read.All, Sites.Read.All, Files.ReadWrite.All, Sites.ReadWrite.All
+
+Retrieves the retention label information for a file in SharePoint.
+
+## SYNTAX
+```powershell
+Set-PnPFileRetentionLabel -Url <String> [-RecordLocked <Boolean>] [-retentionLabel <String>] [-Connection <PnPConnection>]
+```
+
+## DESCRIPTION
+
+The Set-PnPFileRetentionLabel cmdlet updates the retention label information or locks/unlocks a file in SharePoint using Microsoft Graph. It takes a URL as input, decodes it, and specifically encodes the '+' character if it is part of the filename.
+
+## EXAMPLES
+
+### Example 1
+This example locks the file at the specified URL.
+
+```powershell
+Set-PnPFileRetentionLabel -Url "/sites/Marketing/Shared Documents/Report.pptx" -RecordLocked $true
+```
+
+### Example 2
+This example updates the retention label information for the file at the specified URL.
+
+```powershell
+Set-PnPFileRetentionLabel -Url "/sites/Marketing/Shared Documents/Report.pptx" -retentionLabel "Finance"
+```
+
+## PARAMETERS
+
+### -Url
+Specifies the URL of the file for which to retrieve the retention label information.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True
+Accept wildcard characters: False
+```
+
+### -RecordLocked
+Specifies whether to lock or unlock the file.
+```yaml
+Type: Boolean
+Parameter Sets: (All)
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: True
+Accept wildcard characters: False
+```
+
+### -retentionLabel
+Specifies the retention label to apply to the file.
+```yaml
+Type: String
+Parameter Sets: (All)
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: True
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

documentation/Unlock-PnPListItemRecord.md

@@ -0,0 +1,85 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Unlock-PnPListItemRecord.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Unlock-PnPListItemRecord
+---
+
+# Unlock-PnPListItemRecord
+
+## SYNOPSIS
+Unlocks the list item record
+
+
+## SYNTAX
+
+```powershell
+Unlock-PnPListItemRecord [-List] <ListPipeBind> -Identity <ListItemPipeBind> 
+ [-Connection <PnPConnection>] 
+```
+
+## DESCRIPTION
+
+Unlocks the list item record
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Unlock-PnPListItemRecord -List "Documents" -Identity 4
+```
+
+Unlocks the document in the documents library with id 4.
+
+## 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
+```
+
+### -Identity
+The ID of the listitem, or actual ListItem object to be unlocked
+
+```yaml
+Type: ListItemPipeBind
+Parameter Sets: (All)
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -List
+The ID, Title or Url of the list.
+
+```yaml
+Type: ListPipeBind
+Parameter Sets: (All)
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)
+
+

src/Commands/Files/SetFileRetentionLabel.cs

@@ -0,0 +1,96 @@
+using PnP.Framework.Utilities;
+using PnP.PowerShell.Commands.Attributes;
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Model.Graph.Purview;
+using System;
+using System.Management.Automation;
+using System.Net.Http;
+using System.Text;
+using System.Text.Json;
+
+namespace PnP.PowerShell.Commands.Files
+{
+    [Cmdlet(VerbsCommon.Set, "PnPFileRetentionLabel")]
+    [RequiredApiDelegatedOrApplicationPermissions("graph/Files.Read.All")]
+    [RequiredApiDelegatedOrApplicationPermissions("graph/Sites.Read.All")]
+    [RequiredApiDelegatedOrApplicationPermissions("graph/Files.ReadWrite.All")]
+    [RequiredApiDelegatedOrApplicationPermissions("graph/Sites.ReadWrite.All")]
+    [OutputType(typeof(FileRetentionLabel))]
+    public class SetFileRetentionLabel : PnPGraphCmdlet
+    {
+        [Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true)]
+        public string Url = string.Empty;
+
+        [Parameter(Mandatory = false)]
+        public string retentionLabel = string.Empty;
+
+        [Parameter(Mandatory = false)]
+        public bool? RecordLocked;
+
+        protected override void ExecuteCmdlet()
+        {
+            // Check if both parameters are provided
+            if (!string.IsNullOrEmpty(retentionLabel) && RecordLocked.HasValue)
+            {
+                throw new PSArgumentException("Only one of the parameters 'RecordLocked' or 'retentionLabel' can be provided.");
+            }
+
+            var serverRelativeUrl = string.Empty;
+
+            if (Uri.IsWellFormedUriString(Url, UriKind.Absolute))
+            {
+                // We can't deal with absolute URLs
+                Url = UrlUtility.MakeRelativeUrl(Url);
+            }
+
+            // Remove URL decoding from the Url as that will not work. We will encode the + character specifically, because if that is part of the filename, it needs to stay and not be decoded.
+            Url = Utilities.UrlUtilities.UrlDecode(Url.Replace("+", "%2B"));
+
+            Connection.PnPContext.Web.EnsureProperties(w => w.ServerRelativeUrl);
+
+            var webUrl = Connection.PnPContext.Web.ServerRelativeUrl;
+
+            if (!Url.ToLower().StartsWith(webUrl.ToLower()))
+            {
+                serverRelativeUrl = UrlUtility.Combine(webUrl, Url);
+            }
+            else
+            {
+                serverRelativeUrl = Url;
+            }
+
+            var file = Connection.PnPContext.Web.GetFileByServerRelativeUrl(Url);
+            file.EnsureProperties(f => f.VroomDriveID, f => f.VroomItemID);
+
+            var requestUrl = $"v1.0/drives/{file.VroomDriveID}/items/{file.VroomItemID}/retentionLabel";
+
+            object payload;
+
+            if (!string.IsNullOrEmpty(retentionLabel))
+            {
+                payload = new
+                {
+                    name = retentionLabel
+                };
+            }
+            else if (RecordLocked.HasValue)
+            {
+                payload = new
+                {
+                    retentionSettings = new
+                    {
+                        isRecordLocked = RecordLocked
+                    }
+                };
+            }
+            else
+            {
+                throw new PSArgumentException("Either retentionLabel or isRecordLocked must be provided");
+            }
+            var jsonPayload = JsonSerializer.Serialize(payload);
+            var httpContent = new StringContent(jsonPayload,Encoding.UTF8, "application/json");
+            var results = RequestHelper.Patch<FileRetentionLabel>(requestUrl, httpContent);
+            WriteObject(results, true);
+        }
+    }
+}