Rename and bugfixes in Get-PnPFolder, Get-PnPFolderFolder and `Ge…

…t-PnPFolderFile` cmdlets (#3421) * Bugfixes in Get-PnPFolder * Renaming Get-PnPFolderFile and Get-PnPFolderFolder as discussed * Updating documentation * Updated changelog to new cmdlet names * Added example on combinging Get-PnPFolder with Get-PnPFileInFolder * Updated example 7 to use the ExcludeSystemFolders parameter * Bugfix * Changing recursive parameter to recurse to align with get-pnpfileinfolder and get-childitem * Applying feedback to keep the cmdlet backwards compatible * Bugfix * Adding ignore for obsolete warning * Changing code to be backwards compatible --------- Co-authored-by: Gautam Sheth <[email protected]>
pnp · Nov 10, 2023 · 9822684 · 9822684
1 parent 375c404
commit 9822684
Show file tree

Hide file tree

Showing 7 changed files with 179 additions and 67 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,9 +15,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `-AllowCommentsTextOnEmailEnabled` parameter to `Set-PnPTenant` which allows including the surrounding document context in email notification when user is mentioned in document comments. [#3268](https://github.com/pnp/powershell/pull/3268)
 - Added `Export-PnPPowerApp` cmdlet which will export a specified PowerApp as zip package. [#2990](https://github.com/pnp/powershell/pull/2990)
 - Added `AzureADLoginEndPoint` and `MicrosoftGraphEndPoint` parameters to `Connect-PnPOnline` cmdlet for use in custom Azure environments. [#2925](https://github.com/pnp/powershell/pull/2925)
-- Added `Get-PnPFolder` cmdlet without any parameters to return all folders in the root of the current web [#3319](https://github.com/pnp/powershell/pull/3319)
-- Added `Get-PnPFolderFile` cmdlet which allows retrieval of all files in a folder or site and optionally request additional properties from them [#3319](https://github.com/pnp/powershell/pull/3319)
-- Added `Get-PnPFolderFolder` cmdlet which allows retrieval of all folders in a folder or site and optionally request additional properties from them [#3319](https://github.com/pnp/powershell/pull/3319)
+- Added `Get-PnPFolder` cmdlet without any parameters to return the folder representing the root of the current web [#3319](https://github.com/pnp/powershell/pull/3319)
+- Added `Get-PnPFileInFolder` cmdlet which allows retrieval of all files in a folder or site and optionally request additional properties from them [#3319](https://github.com/pnp/powershell/pull/3319)
+- Added `Get-PnPFolderInFolder` cmdlet which allows retrieval of all folders in a folder or site and optionally request additional properties from them [#3319](https://github.com/pnp/powershell/pull/3319)
 - Added `-SharingStatus` parameter to `Get-PnPFlow` which allows for filtering flows based on their sharing status. [#3287](https://github.com/pnp/powershell/pull/3287)
 - Added `-AzureADLoginEndPoint` and `-MicrosoftGraphEndPoint` parameters to `Connect-PnPOnline` cmdlet for use in custom Azure environments. [#2925](https://github.com/pnp/powershell/pull/2925)
 - Added `SiteOwnerManageLegacyServicePrincipalEnabled` parameter to `Set-PnPTenant` cmdlet. With this parameter site owners will not be able to register/update apps unless the tenant admin explicitly allows it. [#3318](https://github.com/pnp/powershell/pull/3318)

diff --git a/documentation/Get-PnPFolderFile.md → documentation/Get-PnPFileInFolder.md b/documentation/Get-PnPFolderFile.md → documentation/Get-PnPFileInFolder.md
@@ -2,12 +2,12 @@
 Module Name: PnP.PowerShell
 schema: 2.0.0
 applicable: SharePoint Online
-online version: https://pnp.github.io/powershell/cmdlets/Get-PnPFolderFile.html
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPFileInFolder.html
 external help file: PnP.PowerShell.dll-Help.xml
-title: Get-PnPFolderFile
+title: Get-PnPFileInFolder
 ---
 
-# Get-PnPFolderFile
+# Get-PnPFileInFolder
 
 ## SYNOPSIS
 List files in a folder
@@ -16,12 +16,12 @@ List files in a folder
 
 ### Folder via url
 ```powershell
-Get-PnPFolderFile [-FolderSiteRelativeUrl <String>] [-ItemName <String>] [-Recursive] [-Includes <String[]>] [-Verbose] [-Connection <PnPConnection>] 
+Get-PnPFileInFolder [-FolderSiteRelativeUrl <String>] [-ItemName <String>] [-Recurse] [-Includes <String[]>] [-Verbose] [-Connection <PnPConnection>] 
 ```
 
 ### Folder via pipebind
 ```powershell
-Get-PnPFolderFile [-Identity <FolderPipeBind>] [-ItemName <String>] [-Recursive] [-Includes <String[]>] [-Verbose] [-Connection <PnPConnection>] 
+Get-PnPFileInFolder [-Identity <FolderPipeBind>] [-ItemName <String>] [-Recurse] [-Includes <String[]>] [-Verbose] [-Connection <PnPConnection>] 
 ```
 
 ## DESCRIPTION
@@ -32,46 +32,53 @@ This cmdlet allows listing of all the files in a folder. It can optionally also
 
 ### EXAMPLE 1
 ```powershell
-Get-PnPFolderFile
+Get-PnPFileInFolder
 ```
 
 Returns all the files in the root of the current web
 
 ### EXAMPLE 2
 ```powershell
-Get-PnPFolderFile -Recurse
+Get-PnPFileInFolder -Recurse
 ```
 
 Returns all the files in the entire site. This will take a while to complete and will cause a lot of calls to be made towards SharePoint Online. Use it wisely.
 
 ### EXAMPLE 3
 ```powershell
-Get-PnPFolderFile -Identity "Shared Documents"
+Get-PnPFileInFolder -Identity "Shared Documents"
 ```
 
 Returns the files located in the 'Shared Documents' folder located in the root of the current web
 
 ### EXAMPLE 4
 ```powershell
-Get-PnPFolderFile -FolderSiteRelativeUrl "SitePages" -ItemName "Default.aspx"
+Get-PnPFileInFolder -FolderSiteRelativeUrl "SitePages" -ItemName "Default.aspx"
 ```
 
 Returns the file 'Default.aspx' which is located in the folder SitePages which is located in the root of the current web
 
 ### EXAMPLE 5
 ```powershell
-Get-PnPFolder -Identity "Shared Documents" | Get-PnPFolderFile
+Get-PnPFolder -Identity "Shared Documents" | Get-PnPFileInFolder
 ```
 
 Returns all files in the "Shared Documents" folder which is located in the root of the current web
 
 ### EXAMPLE 6
 ```powershell
-Get-PnPFolderFile -FolderSiteRelativeUrl "SitePages" -Recursive
+Get-PnPFileInFolder -FolderSiteRelativeUrl "SitePages" -Recurse
 ```
 
 Returns all files, including those located in any subfolders, in the folder SitePages which is located in the root of the current web
 
+### EXAMPLE 7
+```powershell
+Get-PnPFolder -List "Documents" | Get-PnPFileInFolder -Recurse -ExcludeSystemFolders
+```
+
+Returns all files, including those located in any subfolders, located in the Documents document library where the files in system folders are excluded
+
 ## PARAMETERS
 
 ### -Connection
@@ -158,7 +165,7 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Recursive
+### -Recurse
 A switch parameter to include files of all subfolders in the specified folder
 
 ```yaml

diff --git a/documentation/Get-PnPFolder.md b/documentation/Get-PnPFolder.md
@@ -10,27 +10,42 @@ title: Get-PnPFolder
 # Get-PnPFolder
 
 ## SYNOPSIS
-Returns one or more folder objects
+Returns a folder object
 
 ## SYNTAX
 
 ### Folders in current Web (Default)
 ```powershell
-Get-PnPFolder [-Includes <String[]>] [-Connection <PnPConnection>]
+Get-PnPFolder [-Includes <String[]>] [-Connection <PnPConnection>] [-Verbose]
 ```
 
-### Folder By Url
+### Root folder of the current Web
 ```powershell
-Get-PnPFolder -Url <String> [-Includes <String[]>] [-Connection <PnPConnection>] 
+Get-PnPFolder -CurrentWebRootFolder [-Includes <String[]>] [-Connection <PnPConnection>] [-Verbose]
+```
+
+### Folder by url
+```powershell
+Get-PnPFolder -Url <String> [-Includes <String[]>] [-Connection <PnPConnection>] [-Verbose]
+```
+
+### Root folder of a list
+```powershell
+Get-PnPFolder -ListRootFolder <ListPipeBind> [-Includes <String[]>] [-Connection <PnPConnection>] [-Verbose]
 ```
 
 ### Folders In List
 ```powershell
-Get-PnPFolder -List <ListPipeBind> [-Includes <String[]>] [-Connection <PnPConnection>]
+Get-PnPFolder -List <ListPipeBind> [-Includes <String[]>] [-Connection <PnPConnection>] [-Verbose]
 ```
 
 ## DESCRIPTION
-Retrieves one or more folders from the specified location. Use Resolve-PnPFolder to create the folder if it does not exist.
+Retrieves the folder instance of the specified location.
+
+Use [Resolve-PnPFolder](Resolve-PnPFolder.md) to create the folder if it does not exist.
+Use [Get-PnPFolderInFolder](Get-PnPFolderInFolder.md) to retrieve subfolders.
+Use [Get-PnPFileInFolder](Get-PnPFileInFolder.md) to retrieve files in a folder.
+Use [Get-PnPFolderItem](Get-PnPFolderItem.md) to retrieve files and subfolders.
 
 ## EXAMPLES
 
@@ -39,31 +54,59 @@ Retrieves one or more folders from the specified location. Use Resolve-PnPFolder
 Get-PnPFolder
 ```
 
-Returns all the folders in the root of the current web
+Returns all the folders located in the root of the current web
 
 ### EXAMPLE 2
 ```powershell
+Get-PnPFolder -CurrentWebRootFolder
+```
+
+Returns the folder instance representing the root of the current web
+
+### EXAMPLE 3
+```powershell
 Get-PnPFolder -Url "Shared Documents"
 ```
 
 Returns the folder called 'Shared Documents' which is located in the root of the current web
 
-### EXAMPLE 3
+### EXAMPLE 4
 ```powershell
 Get-PnPFolder -Url "/sites/demo/Shared Documents"
 ```
 
 Returns the folder called 'Shared Documents' which is located in the root of the site collection located at '/sites/demo'
 
-### EXAMPLE 4
+### EXAMPLE 5
+```powershell
+Get-PnPFolder -ListRootFolder "Shared Documents"
+```
+
+Returns the root folder of the list called 'Shared Documents'
+
+### EXAMPLE 6
 ```powershell
 Get-PnPFolder -List "Shared Documents"
 ```
 
-Returns the folders residing inside a folder called 'Shared Documents'
+Returns the folders inside the root folder of the list called 'Shared Documents'. Please use Get-PnPFolder -ListRootFolder <folder> | Get-PnPFolderInFolder instead.
 
 ## PARAMETERS
 
+### -CurrentWebRootFolder
+If provided, the folder representing the root of the current web will be returned
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: Root folder of the current Web
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -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.
 
@@ -79,7 +122,7 @@ Accept wildcard characters: False
 ```
 
 ### -List
-Name, ID or instance of a list or document library to retrieve the folders residing in it for.
+Name, ID or instance of a list or document library to retrieve the folders residing in it for. Please use Get-PnPFolder -ListRootFolder <folder> | Get-PnPFolderInFolder instead.
 
 ```yaml
 Type: ListPipeBind
@@ -92,6 +135,20 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ListRootFolder
+Name, ID or instance of a list or document library to retrieve the rootfolder of.
+
+```yaml
+Type: ListPipeBind
+Parameter Sets: Root folder of a list
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Url
 Site or server relative URL of the folder to retrieve. In the case of a server relative url, make sure that the url starts with the managed path as the current web.
 
@@ -107,7 +164,20 @@ Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
+### -Verbose
+When provided, additional debug statements will be shown while executing the cmdlet.
+
+```yaml
+Type: SwitchParameter
+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)
-[Resolve-PnPFolder](https://github.com/MicrosoftDocs/office-docs-powershell/blob/master/sharepoint/sharepoint-ps/sharepoint-pnp/Resolve-PnPFolder.md)
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)
diff --git a/documentation/Get-PnPFolderFolder.md → documentation/Get-PnPFolderInFolder.md b/documentation/Get-PnPFolderFolder.md → documentation/Get-PnPFolderInFolder.md
@@ -2,12 +2,12 @@
 Module Name: PnP.PowerShell
 schema: 2.0.0
 applicable: SharePoint Online
-online version: https://pnp.github.io/powershell/cmdlets/Get-PnPFolderFolder.html
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPFolderInFolder.html
 external help file: PnP.PowerShell.dll-Help.xml
-title: Get-PnPFolderFolder
+title: Get-PnPFolderInFolder
 ---
 
-# Get-PnPFolderFolder
+# Get-PnPFolderInFolder
 
 ## SYNOPSIS
 List subfolders in a folder
@@ -16,12 +16,12 @@ List subfolders in a folder
 
 ### Folder via url
 ```powershell
-Get-PnPFolderFolder [-FolderSiteRelativeUrl <String>] [-ItemName <String>] [-ExcludeSystemFolders] [-Includes <String[]>] [-Recursive] [-Verbose] [-Connection <PnPConnection>] 
+Get-PnPFolderInFolder [-FolderSiteRelativeUrl <String>] [-ItemName <String>] [-ExcludeSystemFolders] [-Includes <String[]>] [-Recurse] [-Verbose] [-Connection <PnPConnection>] 
 ```
 
 ### Folder via pipebind
 ```powershell
-Get-PnPFolderFolder [-Identity <FolderPipeBind>] [-ItemName <String>] [-ExcludeSystemFolders] [-Includes <String[]>] [-Recursive] [-Verbose] [-Connection <PnPConnection>] 
+Get-PnPFolderInFolder [-Identity <FolderPipeBind>] [-ItemName <String>] [-ExcludeSystemFolders] [-Includes <String[]>] [-Recurse] [-Verbose] [-Connection <PnPConnection>] 
 ```
 
 ## DESCRIPTION
@@ -32,49 +32,49 @@ This cmdlet allows listing of all the subfolders of a folder. It can optionally
 
 ### EXAMPLE 1
 ```powershell
-Get-PnPFolderFolder
+Get-PnPFolderInFolder
 ```
 
 Returns all the folders in the root of the current web
 
 ### EXAMPLE 2
 ```powershell
-Get-PnPFolderFolder -Recurse
+Get-PnPFolderInFolder -Recurse
 ```
 
 Returns all the folders in the entire site. This will take a while to complete and will cause a lot of calls to be made towards SharePoint Online. Use it wisely.
 
 ### EXAMPLE 3
 ```powershell
-Get-PnPFolderFolder -Identity "Shared Documents"
+Get-PnPFolderInFolder -Identity "Shared Documents"
 ```
 
 Returns the folders located in the 'Shared Documents' folder located in the root of the current web
 
 ### EXAMPLE 4
 ```powershell
-Get-PnPFolderFolder -Identity "Shared Documents" -ExcludeSystemFolders
+Get-PnPFolderInFolder -Identity "Shared Documents" -ExcludeSystemFolders
 ```
 
 Returns the folders located in the 'Shared Documents' folder located in the root of the current web which are not hidden system folders
 
 ### EXAMPLE 5
 ```powershell
-Get-PnPFolderFolder -FolderSiteRelativeUrl "Shared Documents" -ItemName "Templates"
+Get-PnPFolderInFolder -FolderSiteRelativeUrl "Shared Documents" -ItemName "Templates"
 ```
 
 Returns the folder 'Template' which is located in the folder 'Shared Documents' which is located in the root of the current web
 
 ### EXAMPLE 6
 ```powershell
-Get-PnPFolder -Identity "Shared Documents" | Get-PnPFolderFolder
+Get-PnPFolder -Identity "Shared Documents" | Get-PnPFolderInFolder
 ```
 
 Returns all folders in the "Shared Documents" folder which is located in the root of the current web
 
 ### EXAMPLE 7
 ```powershell
-Get-PnPFolderFolder -FolderSiteRelativeUrl "SitePages" -Recursive
+Get-PnPFolderInFolder -FolderSiteRelativeUrl "SitePages" -Recurse
 ```
 
 Returns all folders, including those located in any subfolders, in the folder SitePages which is located in the root of the current web
@@ -165,7 +165,7 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Recursive
+### -Recurse
 A switch parameter to include folders of all subfolders in the specified folder
 
 ```yaml