Changes to Get-PnPSiteCollectionAppCatalogs (#2044)

* Fixes #2041

* Added additional CurrentSite parameter

Co-authored-by: = <=>
Co-authored-by: Gautam Sheth <gautamdsheth@outlook.com>

Author: KoenZomers

CHANGELOG.md

@@ -63,6 +63,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `Get-Microsoft365GroupYammerCommunity` cmdlet to retrieve details on the Yammer Community connected to a Microsoft 365 Group [#2038](https://github.com/pnp/powershell/pull/2038)
 - Added `Get-Microsoft365GroupTeam` cmdlet to retrieve details on the Microsoft Teams team connected to a Microsoft 365 Group [#2038](https://github.com/pnp/powershell/pull/2038)
 - Added `Get-Microsoft365GroupEndpoints` cmdlet to retrieve details on all endpoints connected to a Microsoft 365 Group [#2038](https://github.com/pnp/powershell/pull/2038)
+- Added `-ExcludeDeletedSites` optional parameter to `Get-PnPSiteCollectionAppCatalogs` which allows for site collections with App Catalogs that are in the recycle bin to be exluded from the results [#2044](https://github.com/pnp/powershell/pull/2044)
+- Added `-CurrentSite` optional parameter to `Get-PnPSiteCollectionAppCatalogs` which allows for checking if the currently connected to site has a site collection App Catalogs provisioned on it [#2044](https://github.com/pnp/powershell/pull/2044)
 
 ### Changed
 
@@ -80,6 +82,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Changed that almost every cmdlet now supports passing in a specific connection using `-Connection`. If omitted, the default connection will be used. [#1949](https://github.com/pnp/powershell/pull/1949), [#2011](https://github.com/pnp/powershell/pull/2011), [#1958](https://github.com/pnp/powershell/pull/1958)
 - Changed connecting with `Connect-PnPOnline -Credentials` now throwing a clear exception when making a typo in the hostname instead of getting stuck [#686](https://github.com/pnp/pnpframework/pull/686)
 - Changed `Get-PnPHubSiteChild` to have its `-Identity` parameter become optional. If not provided, the currently connected to site will be used. [#2033](https://github.com/pnp/powershell/pull/2033)
+- Changed `Get-PnPSiteCollectionAppCatalogs` (plural) to `Get-PnPSiteCollectionAppCatalog` (singular) to follow the naming convention [#2044](https://github.com/pnp/powershell/pull/2044)
 
 ### Fixed
 
@@ -112,6 +115,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Fixed `Get-PnPHubSiteChild` throwing an exception when passing in a URL that is actually not a hub site [#2033](https://github.com/pnp/powershell/pull/2033)
 - Fixed `Add-PnPListItem` not showing field name when it has an improper value assigned to it [#2002](https://github.com/pnp/powershell/pull/2002)
 - Fixed connecting using `Connect-PnPOnline -Interactive -ClientId` not working well when already having an App-Only connection using the same ClientId [#2035](https://github.com/pnp/powershell/pull/2035)
+- Fixed `Get-PnPSiteCollectionAppCatalog` not returning updated site collection URLs if they had been renamed [#2044](https://github.com/pnp/powershell/pull/2044)
 - Fixed cmdlets inheriting from PnPAdminCmdlet not working well on vanity domain SharePoint Online tenants [#2052](https://github.com/pnp/powershell/pull/2052)
 - Fixed `Copy-PnPList` throwing an unauthorized exception when using it with a non SharePoint Online administrator user [#2054](https://github.com/pnp/powershell/pull/2054)
 

documentation/Get-PnPSiteCollectionAppCatalog.md

@@ -0,0 +1,104 @@
+---
+Module Name: PnP.PowerShell
+title: Get-PnPSiteCollectionAppCatalog
+schema: 2.0.0
+applicable: SharePoint Online
+external help file: PnP.PowerShell.dll-Help.xml
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPSiteCollectionAppCatalog.html
+---
+ 
+# Get-PnPSiteCollectionAppCatalog
+
+## SYNOPSIS
+Returns all site collection scoped app catalogs that exist on the tenant
+
+## SYNTAX
+
+```powershell
+Get-PnPSiteCollectionAppCatalog [-CurrentSite <SwitchParameter>] [-ExcludeDeletedSites <SwitchParameter>] [-Connection <PnPConnection>] [-Verbose] [<CommonParameters>]
+```
+
+## DESCRIPTION
+Returns all the site collection scoped app catalogs that exist on the tenant
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPSiteCollectionAppCatalog
+```
+Will return all the site collection app catalogs that exist on the tenant, including those that may be in the tenant recycle bin
+
+### EXAMPLE 2
+```powershell
+Get-PnPSiteCollectionAppCatalog -CurrentSite
+```
+Will return the site collection app catalog for the currently connected to site, if it has one. Otherwise it will yield no result.
+
+### EXAMPLE 2
+```powershell
+Get-PnPSiteCollectionAppCatalog -ExcludeDeletedSites
+```
+Will return all the site collection app catalogs that exist on the tenant excluding the site collections having App Catalogs that are in the tenant recycle bin
+
+## PARAMETERS
+
+### -CurrentSite
+When provided, it will check if the currently connected to site has a site collection App Catalog and will return information on it. If the current site holds no site collection App Catalog, an empty response will be returned.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ExcludeDeletedSites
+When provided, all site collections having site collection App Catalogs but residing in the tenant recycle bin, will be excluded
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+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.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+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)

documentation/Get-PnPSiteCollectionAppCatalogs.md

@@ -0,0 +1,90 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using Microsoft.SharePoint.Client;
+using PnP.PowerShell.Commands.Attributes;
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Model.SharePoint;
+
+namespace PnP.PowerShell.Commands
+{
+    [Cmdlet(VerbsCommon.Get, "PnPSiteCollectionAppCatalog")]
+    [Alias("Get-PnPSiteCollectionAppCatalogs")]
+    [WriteAliasWarning("Please use 'Get-PnPSiteCollectionAppCatalog' (singular). The alias 'Get-PnPSiteCollectionAppCatalogs' (plural) will be removed in a future release.")]
+    [OutputType(typeof(IEnumerable<SiteCollectionAppCatalog>))]
+    public class GetSiteCollectionAppCatalog : PnPAdminCmdlet
+    {
+        [Parameter(Mandatory = false)]
+        public SwitchParameter ExcludeDeletedSites;     
+
+        [Parameter(Mandatory = false)]
+        public SwitchParameter CurrentSite;  
+
+        protected override void ExecuteCmdlet()
+        {
+            WriteVerbose("Retrieving all site collection App Catalogs from SharePoint Online");
+
+            var appCatalogsCsom = ClientContext.Web.TenantAppCatalog.SiteCollectionAppCatalogsSites;
+            ClientContext.Load(appCatalogsCsom);
+            ClientContext.ExecuteQueryRetry();            
+
+            var appCatalogsLocalModel = appCatalogsCsom.Select(ac =>
+                new SiteCollectionAppCatalog {
+                    AbsoluteUrl = ac.AbsoluteUrl,
+                    ErrorMessage = ac.ErrorMessage,
+                    SiteID = ac.SiteID
+                }
+            ).ToList();
+
+            WriteVerbose($"{appCatalogsLocalModel.Count} site collection App Catalog{(appCatalogsLocalModel.Count != 1 ? "s have" : " has")} been retrieved");
+
+            if(CurrentSite.ToBool())
+            {
+                SiteContext.Site.EnsureProperties(s => s.Id);
+
+                WriteVerbose($"Filtering down to only the current site at {Connection.Url} with ID {SiteContext.Site.Id}");
+                var currentSite = appCatalogsLocalModel.FirstOrDefault(a => a.SiteID.HasValue && a.SiteID.Value == SiteContext.Site.Id);
+
+                appCatalogsLocalModel.Clear();
+
+                if(currentSite == null)
+                {
+                    WriteVerbose($"Current site at {Connection.Url} with ID {SiteContext.Site.Id} does not have a site collection App Catalog on it");
+                    return;
+                }
+
+                appCatalogsLocalModel.Add(currentSite);
+            }
+
+            var results = new List<SiteCollectionAppCatalog>(appCatalogsLocalModel.Count);
+            foreach (var appCatalogLocalModel in appCatalogsLocalModel)
+            {
+                if (appCatalogLocalModel.SiteID.HasValue)
+                {
+                    try
+                    {
+                        WriteVerbose($"Validating site collection App Catalog at {appCatalogLocalModel.AbsoluteUrl}");
+
+                        appCatalogLocalModel.AbsoluteUrl = Tenant.GetSitePropertiesById(appCatalogLocalModel.SiteID.Value, false).Url;
+                        results.Add(appCatalogLocalModel);
+                    }
+                    catch (Microsoft.SharePoint.Client.ServerException e) when (e.ServerErrorTypeName.Equals("Microsoft.Online.SharePoint.Common.SpoNoSiteException", StringComparison.InvariantCultureIgnoreCase))
+                    {                        
+                        if(!ExcludeDeletedSites.ToBool())
+                        {
+                            WriteVerbose($"Site collection App Catalog at {appCatalogLocalModel.AbsoluteUrl} regards a site that has been deleted");
+                            results.Add(appCatalogLocalModel);
+                        }
+                        else
+                        {
+                            WriteVerbose($"Site collection App Catalog at {appCatalogLocalModel.AbsoluteUrl} regards a site that has been deleted. Since the {nameof(ExcludeDeletedSites)} flag has been provided, it will not be included in the results.");
+                        }
+                    }                    
+                }
+            }
+
+            WriteObject(results, true);
+        }
+    }
+}

src/Commands/Admin/GetSiteCollectionAppCatalog.cs

@@ -4,7 +4,6 @@
 using Microsoft.Online.SharePoint.TenantAdministration;
 using Microsoft.SharePoint.Client;
 using PnP.PowerShell.Commands.Base;
-using PnP.PowerShell.Commands.Enums;
 using System.Collections.Generic;
 using Microsoft.Online.SharePoint.TenantManagement;
 using PnP.PowerShell.Commands.Base.PipeBinds;

src/Commands/Admin/GetSiteCollectionAppCatalogs.cs

@@ -0,0 +1,26 @@
+using System;
+
+namespace PnP.PowerShell.Commands.Model.SharePoint
+{
+    /// <summary>
+    /// All properties regarding a site collection scoped App Catalog
+    /// </summary>
+    public class SiteCollectionAppCatalog
+    {
+        /// <summary>
+        /// The full Url to the location of the App Catalog in the tenant
+        /// </summary>
+        public string AbsoluteUrl { get; set; }
+
+        /// <summary>
+        /// Informational message regarding the provisioning of the App Catalog
+        /// </summary>
+        public string ErrorMessage { get; set; }
+
+        /// <summary>
+        /// Unique identifier of the site on which this App Catalog is located
+        /// </summary>
+        public Guid? SiteID { get; set; }
+
+    }
+}