Add support for applying built-in Microsoft site designs (store 1) (#5358)

The existing Get-PnPSiteDesign and Invoke-PnPSiteDesign cmdlets used CSOM
(Tenant.GetSiteDesigns / Tenant.ApplySiteDesign) which only works for
tenant-registered custom designs (store 0). Microsoft's built-in site
designs such as Event, Department and Human Resources live in the SharePoint
site template store (store 1) and require the SiteScriptUtility REST API
with a store parameter — there was no way to reach them from PnP PowerShell.

- Add Get-PnPSiteDesign -BuiltIn switch: calls SiteScriptUtility.GetSiteDesigns
  with store 1 and returns BuiltInSiteDesign objects (Id, Title, Template enum)
- Add Invoke-PnPSiteDesign -Template <BuiltInSiteTemplates>: resolves the GUID
  from the existing BuiltInSiteTemplates enum mapping and calls
  SiteScriptUtility.ApplySiteDesign with store 1
- Add BuiltInSiteDesign model class for deserialising the REST response
- Add GetBuiltInSiteDesigns and ApplyBuiltInSiteDesign utility methods to
  SiteTemplates.cs so the REST logic is centralised
- Fix missing DefaultParameterSetName on Get-PnPSiteDesign to prevent
  ambiguous parameter set error when called without arguments
- Update documentation for both cmdlets with new syntax, parameter descriptions
  and usage examples

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

Author: fabianhutzli

documentation/Get-PnPSiteDesign.md

@@ -15,42 +15,66 @@ online version: https://pnp.github.io/powershell/cmdlets/Get-PnPSiteDesign.html
 
 * SharePoint: Access to the SharePoint Tenant Administration site
 
-Retrieve Site Designs that have been registered on the current tenant.
+Retrieve Site Designs that have been registered on the current tenant, or list the built-in Microsoft site designs.
 
 ## SYNTAX
 
+### Default (Default)
+
 ```powershell
 Get-PnPSiteDesign [[-Identity] <TenantSiteDesignPipeBind>] [-Connection <PnPConnection>] 
 ```
 
+### BuiltIn
+
+```powershell
+Get-PnPSiteDesign -BuiltIn [-Connection <PnPConnection>] 
+```
+
 ## DESCRIPTION
 
 Retrieve Site Designs that have been registered on the current tenant. When providing a name with -Identity, it returns all site designs with that name.
 
+Use the -BuiltIn switch to instead return the built-in Microsoft site designs (e.g. Event, Department, Human Resources) which are available from the SharePoint site template store.
+
 ## EXAMPLES
 
 ### EXAMPLE 1
 ```powershell
 Get-PnPSiteDesign
 ```
 
-Returns all registered site designs
+Returns all tenant-registered site designs.
 
 ### EXAMPLE 2
 ```powershell
 Get-PnPSiteDesign -Identity 5c73382d-9643-4aa0-9160-d0cba35e40fd
 ```
 
-Returns a specific registered site designs
+Returns a specific registered site design.
+
+### EXAMPLE 3
+```powershell
+Get-PnPSiteDesign -BuiltIn
+```
+
+Returns all built-in Microsoft site designs, including their Ids, titles, and matching template enum values.
+
+### EXAMPLE 4
+```powershell
+Get-PnPSiteDesign -BuiltIn | Where-Object { $_.Template -eq "Event" }
+```
+
+Returns the built-in Event site design.
 
 ## PARAMETERS
 
 ### -Identity
-If specified will retrieve the specified site design
+If specified, retrieves the site design with the given Id or name.
 
 ```yaml
 Type: TenantSiteDesignPipeBind
-Parameter Sets: (All)
+Parameter Sets: Default
 
 Required: False
 Position: 0
@@ -59,6 +83,20 @@ Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
+### -BuiltIn
+When specified, returns the built-in Microsoft site designs from the SharePoint site template store (store 1) instead of tenant-registered designs.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: BuiltIn
+
+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.
 
@@ -75,4 +113,4 @@ Accept wildcard characters: False
 
 ## RELATED LINKS
 
-[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

documentation/Invoke-PnPSiteDesign.md

@@ -14,14 +14,27 @@ Apply a Site Design to an existing site. * Requires Tenant Administration Rights
 
 ## SYNTAX
 
+### By Site Design (Default)
+
 ```powershell
 Invoke-PnPSiteDesign [-Identity] <TenantSiteDesignPipeBind> [-WebUrl <String>] 
  [-Connection <PnPConnection>]   
 ```
 
+### By Built-in Template
+
+```powershell
+Invoke-PnPSiteDesign -Template <BuiltInSiteTemplates> [-WebUrl <String>] 
+ [-Connection <PnPConnection>]   
+```
+
 ## DESCRIPTION
 
-Applies the Site Design provided through Identity to an existing site. When providing a site design name and multiple site designs exist with the same name, all of them will be invoked.
+Applies a Site Design to an existing site.
+
+Use `-Identity` to apply a tenant-registered site design by Id or name. When a name matches multiple designs, all of them will be invoked.
+
+Use `-Template` to apply one of the built-in Microsoft site designs (e.g. Event, Department, Human Resources) directly by name, without needing to look up the design Id first. This calls the SharePoint SiteScriptUtility REST API against the built-in template store (store 1).
 
 ## EXAMPLES
 
@@ -44,30 +57,30 @@ Applies the specified site design to the specified site.
 Get-PnPSiteDesign | ?{$_.Title -eq "Demo"} | Invoke-PnPSiteDesign
 ```
 
-Applies the specified site design to the specified site.
-
-## PARAMETERS
+Applies the site design named "Demo" to the current site via the pipeline.
 
-### -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.
+### EXAMPLE 4
+```powershell
+Invoke-PnPSiteDesign -Template Event -WebUrl "https://contoso.sharepoint.com/sites/myevent"
+```
 
-```yaml
-Type: PnPConnection
-Parameter Sets: (All)
+Applies the built-in Event site design to the specified communication site.
 
-Required: False
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
+### EXAMPLE 5
+```powershell
+Invoke-PnPSiteDesign -Template Department
 ```
 
+Applies the built-in Department site design to the current site.
+
+## PARAMETERS
+
 ### -Identity
-The Site Design Id or an actual Site Design object to apply
+The Site Design Id, name, or an actual Site Design object to apply.
 
 ```yaml
 Type: TenantSiteDesignPipeBind
-Parameter Sets: (All)
+Parameter Sets: By Site Design
 
 Required: True
 Position: 0
@@ -76,7 +89,19 @@ Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
+### -Template
+The name of a built-in Microsoft site design to apply. Uses the SharePoint SiteScriptUtility REST API against the built-in template store (store 1). Cannot be combined with -Identity.
 
+```yaml
+Type: BuiltInSiteTemplates
+Parameter Sets: By Built-in Template
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
 
 ### -WebUrl
 The URL of the web to apply the site design to. If not specified it will default to the current web based upon the URL specified with Connect-PnPOnline.
@@ -92,7 +117,20 @@ 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
+```
+
 ## RELATED LINKS
 
 [Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)
-

src/Commands/Model/SharePoint/BuiltInSiteDesign.cs

@@ -0,0 +1,32 @@
+using System;
+using System.Text.Json.Serialization;
+using PnP.PowerShell.Commands.Enums;
+using PnP.PowerShell.Commands.Model.SharePoint;
+
+namespace PnP.PowerShell.Commands.Model.SharePoint
+{
+    /// <summary>
+    /// Represents a built-in Microsoft SharePoint site design returned from the SiteScriptUtility REST API (store 1)
+    /// </summary>
+    public class BuiltInSiteDesign
+    {
+        [JsonPropertyName("Id")]
+        public Guid Id { get; set; }
+
+        [JsonPropertyName("Title")]
+        public string Title { get; set; }
+
+        /// <summary>
+        /// Maps the Id back to the known BuiltInSiteTemplates enum value, if recognised
+        /// </summary>
+        public BuiltInSiteTemplates? Template
+        {
+            get
+            {
+                if (BuiltInSiteTemplateSettings.BuiltInSiteTemplateMappings.TryGetValue(Id, out var template))
+                    return template;
+                return null;
+            }
+        }
+    }
+}

src/Commands/SiteDesigns/GetSiteDesign.cs

@@ -1,25 +1,52 @@
-using Microsoft.Online.SharePoint.TenantAdministration;
+using Microsoft.Online.SharePoint.TenantAdministration;
 using Microsoft.SharePoint.Client;
 using PnP.PowerShell.Commands.Base;
 using PnP.PowerShell.Commands.Base.PipeBinds;
+using PnP.PowerShell.Commands.Model.SharePoint;
+using PnP.PowerShell.Commands.Utilities;
+using System.Collections.Generic;
 using System.Linq;
 using System.Management.Automation;
 
 namespace PnP.PowerShell.Commands
 {
-    [Cmdlet(VerbsCommon.Get, "PnPSiteDesign")]
+    [Cmdlet(VerbsCommon.Get, "PnPSiteDesign", DefaultParameterSetName = "Default")]
+    [OutputType(typeof(TenantSiteDesign), ParameterSetName = new[] { "Default" })]
+    [OutputType(typeof(IEnumerable<BuiltInSiteDesign>), ParameterSetName = new[] { "BuiltIn" })]
     public class GetSiteDesign : PnPSharePointOnlineAdminCmdlet
     {
-        [Parameter(Mandatory = false, Position = 0, ValueFromPipeline = true)]
+        [Parameter(Mandatory = false, Position = 0, ValueFromPipeline = true, ParameterSetName = "Default")]
         public TenantSiteDesignPipeBind Identity;
 
+        /// <summary>
+        /// When specified, returns built-in Microsoft site designs (store 1) instead of tenant-custom ones
+        /// </summary>
+        [Parameter(Mandatory = true, ParameterSetName = "BuiltIn")]
+        public SwitchParameter BuiltIn;
+
         protected override void ExecuteCmdlet()
         {
+            if (ParameterSetName == "BuiltIn")
+            {
+                LogDebug("Retrieving built-in Microsoft site designs from store 1");
+
+                AdminContext.Load(AdminContext.Web, w => w.Url);
+                AdminContext.ExecuteQueryRetry();
+
+                var results = SiteTemplates.GetBuiltInSiteDesigns(SharePointRequestHelper, AdminContext.Web.Url);
+
+                if (results?.Items != null)
+                {
+                    WriteObject(results.Items.ToList(), true);
+                }
+                return;
+            }
+
             if (ParameterSpecified(nameof(Identity)))
             {
                 var siteDesigns = Identity.GetTenantSiteDesign(Tenant);
 
-                if(siteDesigns == null || siteDesigns.Length == 0)
+                if (siteDesigns == null || siteDesigns.Length == 0)
                 {
                     LogDebug("No site designs with the identity provided through Identity have been found");
                     return;
@@ -37,4 +64,4 @@ protected override void ExecuteCmdlet()
             }
         }
     }
-}
+}