Feature #3700 - added cmdlet to change site archive state.

documentation/Set-PnPSiteArchiveState.md

@@ -0,0 +1,110 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Set-PnPSiteArchiveState.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Set-PnPSiteArchiveState
+---
+
+# Set-PnPSiteArchiveState
+
+## SYNOPSIS
+
+**Required Permissions**
+
+* SharePoint: Access to the SharePoint Tenant Administration site
+
+Sets the archived state of the site. Can be used to archive and reactivate sites.
+
+## SYNTAX
+
+```powershell
+Set-PnPSiteArchiveState -Identity <SPOSitePipeBind> -ArchiveState <SPOArchiveState> [-NoWait] [-Force]
+```
+
+## DESCRIPTION
+
+Use this cmdlet to change the archive status of the site. You must be a SharePoint Online administrator or Global administrator and be a site collection administrator to run the cmdlet.
+Microsoft 365 Archive needs to be enabled for the organization to be able to use this feature.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+Set-PnPSiteArchiveState https://contoso.sharepoint.com/sites/Marketing -ArchiveState Archived
+```
+
+This example marks the site as Archived. For seven days after the operation, the site will remain in a "RecentlyArchived" state, where any reactivations will be free and instantaneous. If a site is reactivated after seven days, any reactivations will be charged and will take time.
+
+### Example 2
+
+```powershell
+Set-PnPSiteArchiveState https://contoso.sharepoint.com/sites/Marketing -ArchiveState Active
+```
+
+This example triggers the reactivation of a site. If the site is reactivated from the "RecentlyArchived" state, it will become available instantaneously. If the site is reactivated from the "FullyArchived" state, it may take time for it to be reactivated.
+
+## PARAMETERS
+
+### -Identity
+Specifies the full URL of the SharePoint Online site collection that needs to be renamed.
+
+```yaml
+Type: SPOSitePipeBind
+Parameter Sets: (All)
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True
+Accept wildcard characters: False
+```
+
+### -ArchiveState
+
+Sets the archived state of the site. Valid values are Archived, Active.
+
+```yaml
+Type: SPOArchiveState
+Parameter Sets: (All)
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -NoWait
+If specified the task will return immediately after creating the archive state site job.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Force
+If provided, no confirmation will be asked for changing the archive state.
+
+```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)

src/Commands/Admin/SetSiteArchiveState.cs

@@ -0,0 +1,94 @@
+using Microsoft.Online.SharePoint.TenantAdministration;
+using Microsoft.SharePoint.Client;
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Base.PipeBinds;
+using PnP.PowerShell.Commands.Enums;
+using System;
+using System.Management.Automation;
+
+namespace PnP.PowerShell.Commands.Admin
+{
+    [Cmdlet(VerbsCommon.Set, "PnPSiteArchiveState")]
+    public class SetSiteArchiveState : PnPAdminCmdlet
+    {
+        [Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true)]
+        public SPOSitePipeBind Identity;
+
+        [Parameter(Mandatory = true, Position = 1)]
+        public SPOArchiveState ArchiveState;
+
+        [Parameter(Mandatory = false)]
+        public SwitchParameter NoWait;
+
+        [Parameter(Mandatory = false)]
+        public SwitchParameter Force;
+
+        protected override void ExecuteCmdlet()
+        {
+            SpoOperation spoOperation = null;
+            switch (ArchiveState)
+            {
+                case SPOArchiveState.Archived:
+                    {
+                        WriteObject("The site and its contents cannot be accessed when a site is archived. The site needs to be reactivated if it needs to be accessed. Archived sites can be reactivated instantaneously, without any additional charges within 7 days of the action. After 7 days, reactivations will be charged as per Microsoft 365 Archive Billing, and will take time.");
+
+                        if (Force || ShouldProcess(Identity.Url))
+                        {
+                            spoOperation = Tenant.ArchiveSiteByUrl(Identity.Url);
+                            AdminContext.Load(spoOperation);
+                            AdminContext.ExecuteQueryRetry();
+                        }
+
+                        break;
+                    }
+                case SPOArchiveState.Active:
+                    {
+                        SiteProperties sitePropertiesByUrl = Tenant.GetSitePropertiesByUrl(Identity.Url, includeDetail: false);
+                        AdminContext.Load(sitePropertiesByUrl);
+                        AdminContext.ExecuteQueryRetry();
+
+                        switch (sitePropertiesByUrl.ArchiveStatus)
+                        {
+                            case "FullyArchived":
+                                {
+                                    WriteWarning("Reactivating a site from \"Archived\" state is a paid operation. It can take upto 24hrs for the site to be reactivated. Performing the operation \"Reactivate Archived site\" on target.");
+                                    if (Force || ShouldProcess(Identity.Url))
+                                    {
+                                        spoOperation = Tenant.UnarchiveSiteByUrl(Identity.Url);
+                                        AdminContext.Load(spoOperation);
+                                        AdminContext.ExecuteQueryRetry();
+                                        WriteObject("Reactivation in progress. It may take upto 24hrs for reactivation to complete.");
+                                    }
+                                    break;
+                                }
+                            case "RecentlyArchived":
+                                {
+                                    string resourceString = "Reactivating a site from \"Recently Archived\" state is free. Site will be available as an Active site soon.";
+                                    WriteObject(resourceString);
+                                    if (Force || ShouldProcess(Identity.Url))
+                                    {
+                                        spoOperation = Tenant.UnarchiveSiteByUrl(Identity.Url);
+                                        AdminContext.Load(spoOperation);
+                                        AdminContext.ExecuteQueryRetry();
+                                    }
+                                    break;
+                                }
+                            case "NotArchived":
+                                WriteObject("The site is already in Active state and cannot be reactivated.");
+                                return;
+                            case "Reactivating":
+                                WriteObject("The site is already reactivating and cannot be reactivated.");
+                                return;
+                        }
+                        break;
+                    }
+                default:
+                    throw new InvalidOperationException("OperationAborted");
+            }
+            if (!NoWait.ToBool())
+            {
+                PollOperation(spoOperation);
+            }
+        }
+    }
+}

src/Commands/Enums/SiteArchiveState.cs

@@ -0,0 +1,8 @@
+namespace PnP.PowerShell.Commands.Enums
+{
+    public enum SPOArchiveState
+    {
+        Archived,
+        Active
+    }
+}