Merge pull request #4682 from KoenZomers/Get-PnPFileCheckedOut

Added `Get-PnPFileCheckedOut`

Author: KoenZomers

CHANGELOG.md

@@ -50,6 +50,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `Get-PnPFileRetentionLabel` cmdlet to fetch the file retention labels. [#4603](https://github.com/pnp/powershell/pull/4603)
 - Added `Get/Set/Remove-PnPUserProfilePhoto` cmdlets to download, upload or remove the profile photo of the specified user.
 - Added `New/Get/Remove/Update-PnPTodoList` cmdlets to manage Todo lists.
+- Added `Get-PnPFileCheckedOut` cmdlet to retrieve all files that are currently checked out in a library [#4682](https://github.com/pnp/powershell/pull/4682)
 - Added `Get-PnPTenantPronounsSetting` and `Set-PnPTenantPronounsSetting` cmdlets to manage the availability of using pronouns in the organization [#4660](https://github.com/pnp/powershell/pull/4660)
 - Added `HidePeopleWhoHaveListsOpen` parameter to `Set-PnPSite` cmdlet to hide people who simultaneously have lists open [#4699](https://github.com/pnp/powershell/pull/4699)
 

documentation/Get-PnPFileCheckedOut.md

@@ -0,0 +1,68 @@
+---
+Module Name: PnP.PowerShell
+title: Get-PnPFileCheckedOut
+schema: 2.0.0
+applicable: SharePoint Online
+external help file: PnP.PowerShell.dll-Help.xml
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPFileCheckedOut.html
+---
+ 
+# Get-PnPFileCheckedOut
+
+## SYNOPSIS
+Returns all files that are currently checked out in a library
+
+## SYNTAX
+
+```powershell
+Get-PnPFileCheckedOut -List <ListPipeBind> [-Connection <PnPConnection>] 
+```
+
+## DESCRIPTION
+
+This cmdlet allows to retrieve all files that are currently checked out in a library.
+
+Notice: if this cmdlet would return more then 5,000 results, so 5,000 or more checked out files, it will not work and will throw an error. This is unfortunately a limitation of SharePoint Online and not something that can be fixed in the cmdlet. As long as the number of checked out files is below 5,000, this cmdlet will work as expected, even on document libraries that contain more than 5,000 files.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPFileCheckedOut -List "Documents"
+```
+
+Returns all files that are currently checked out in the "Documents" library.
+
+## 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
+```
+
+### -List
+The list instance, list display name, list url or list id to query for checked out files
+
+```yaml
+Type: String
+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)

resources/PnP.PowerShell.Format.ps1xml

@@ -3127,6 +3127,36 @@
           </TableRowEntry>
         </TableRowEntries>
       </TableControl>
-    </View>   
+    </View>
+    <View>
+      <Name>CheckedOutFile</Name>
+      <ViewSelectedBy>
+        <TypeName>PnP.PowerShell.Commands.Model.SharePoint.CheckedOutFile</TypeName>
+      </ViewSelectedBy>
+      <TableControl>
+        <TableHeaders>
+          <TableColumnHeader>
+            <Label>ServerRelativeUrl</Label>
+            <Alignment>left</Alignment>
+          </TableColumnHeader>
+          <TableColumnHeader>
+            <Label>CheckedOutBy.Email</Label>
+            <Alignment>left</Alignment>
+          </TableColumnHeader>
+        </TableHeaders>
+        <TableRowEntries>
+          <TableRowEntry>
+            <TableColumnItems>
+              <TableColumnItem>
+                <PropertyName>ServerRelativeUrl</PropertyName>
+              </TableColumnItem>
+              <TableColumnItem>
+                <ScriptBlock>$_.CheckedOutBy.Email</ScriptBlock>
+              </TableColumnItem>
+            </TableColumnItems>
+          </TableRowEntry>
+        </TableRowEntries>
+      </TableControl>
+    </View>     
   </ViewDefinitions>
 </Configuration>

src/Commands/Files/GetFileCheckedOut.cs

@@ -0,0 +1,37 @@
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using Microsoft.SharePoint.Client;
+using PnP.PowerShell.Commands.Base.PipeBinds;
+
+namespace PnP.PowerShell.Commands.Files
+{
+    [Cmdlet(VerbsCommon.Get, "PnPFileCheckedOut")]
+    [OutputType(typeof(IEnumerable<Model.SharePoint.CheckedOutFile>))]
+    public class GetFileCheckedOut : PnPWebCmdlet
+    {
+        [Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true)]
+        public ListPipeBind List;
+
+        protected override void ExecuteCmdlet()
+        {
+            var list = List.GetList(CurrentWeb);
+            var checkedOutFiles = list.GetCheckedOutFiles();
+            
+            ClientContext.Load(checkedOutFiles, cof => cof.Include(c => c.CheckedOutBy, c => c.ServerRelativePath));
+            ClientContext.ExecuteQueryRetry();
+
+            checkedOutFiles.Select(c => new Model.SharePoint.CheckedOutFile
+            {
+                ServerRelativeUrl = c.ServerRelativePath.DecodedUrl,
+                CheckedOutBy = new Model.User
+                {
+                    DisplayName = c.CheckedOutBy.Title,
+                    Email = c.CheckedOutBy.Email,
+                    Id = c.CheckedOutBy.Id,
+                    LoginName = c.CheckedOutBy.LoginName
+                }
+            }).ToList().ForEach(WriteObject);
+        }
+    }
+}

src/Commands/Model/SharePoint/CheckedOutFile.cs

@@ -0,0 +1,18 @@
+namespace PnP.PowerShell.Commands.Model.SharePoint
+{
+    /// <summary>
+    /// Contains the properties of a checked out file
+    /// </summary>
+    public class CheckedOutFile
+    {
+        /// <summary>
+        /// Server relative url to the checked out
+        /// </summary>
+        public string ServerRelativeUrl { get; set; }
+
+        /// <summary>
+        /// The user who has the file checked out
+        /// </summary>
+        public User CheckedOutBy { get; set; }
+    }
+}

src/Commands/Model/User.cs

@@ -0,0 +1,28 @@
+namespace PnP.PowerShell.Commands.Model
+{
+    /// <summary>
+    /// Contains information about a user
+    /// </summary>
+    public class User
+    {
+        /// <summary>
+        /// Unique identifier of the user in the user information list of the site collection
+        /// </summary>
+        public int? Id { get; set; }
+
+        /// <summary>
+        /// Display name of the user (a.k.a. Title)
+        /// </summary>
+        public string DisplayName { get; set; }
+
+        /// <summary>
+        /// The login name of the user
+        /// </summary>
+        public string LoginName { get; set; }
+
+        /// <summary>
+        /// The email address of the user
+        /// </summary>
+        public string Email { get; set; }
+    }
+}