Merge pull request #344 from andikrueger/SPOHomeSiteJan21

New Resource SPOHomeSite

CHANGELOG.md

@@ -39,6 +39,8 @@
     16.0.19515.12000;
   * Updated ReverseDSC dependency to version 2.0.0.2;
   * Updated SharePointPnPPowerShellOnline to version 3.17.2001.2;
+* SPOHomeSite
+  * Initial Release;
 
 ## 1.0.1.1395
 

Modules/Office365DSC/DSCResources/MSFT_SPOHomeSite/MSFT_SPOHomeSite.psm1

@@ -0,0 +1,195 @@
+function Get-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet("Yes")]
+        [String]
+        $IsSingleInstance,
+
+        [Parameter()]
+        [System.String]
+        $Url,
+
+        [Parameter()]
+        [ValidateSet("Present", "Absent")]
+        [System.String]
+        $Ensure = "Present",
+
+        [Parameter(Mandatory = $true)]
+        [System.Management.Automation.PSCredential]
+        $GlobalAdminAccount
+    )
+
+    Write-Verbose -Message "Getting configuration for hub site collection $Url"
+
+    Test-MSCloudLogin -O365Credential $GlobalAdminAccount `
+        -Platform PnP
+
+    $nullReturn = @{
+        IsSingleInstance   = $IsSingleInstance
+        Ensure             = "Absent"
+        GlobalAdminAccount = $GlobalAdminAccount
+    }
+
+    try
+    {
+        Write-Verbose -Message "Getting current home site collection settings"
+        $homeSiteUrl = Get-PnPHomeSite
+        if ($null -eq $homeSiteUrl)
+        {
+            Write-Verbose -Message "There is no Home Site Collection set."
+            return $nullReturn
+        }
+        else
+        {
+            $result = @{
+                IsSingleInstance   = $IsSingleInstance
+                $Url               = $homeSiteUrl
+                Ensure             = "Present"
+                GlobalAdminAccount = $GlobalAdminAccount
+            }
+            return $result
+        }
+    }
+    catch
+    {
+        Write-Verbose -Message "There was an error in the SPOHomeSite resource."
+    }
+    return $nullReturn
+}
+
+function Set-TargetResource
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet("Yes")]
+        [String]
+        $IsSingleInstance,
+
+        [Parameter()]
+        [System.String]
+        $Url,
+
+        [Parameter()]
+        [ValidateSet("Present", "Absent")]
+        [System.String]
+        $Ensure = "Present",
+
+        [Parameter(Mandatory = $true)]
+        [System.Management.Automation.PSCredential]
+        $GlobalAdminAccount
+    )
+
+    Write-Verbose -Message "Setting configuration for home site '$Url'"
+
+    Test-MSCloudLogin -O365Credential $GlobalAdminAccount `
+        -Platform PnP
+
+    $currentValues = Get-TargetResource @PSBoundParameters
+
+    if ($Ensure -eq "Present")
+    {
+        try
+        {
+            Write-Verbose -Message "Setting home site collection $Url"
+            Get-PnPTenantSite -Url $Url
+        }
+        catch
+        {
+            $Message = "The specified Site Collection $($Url) for SPOHomeSite doesn't exist."
+            New-Office365DSCLogEntry -Error $_ -Message $Message
+            throw $Message
+        }
+
+        Write-Verbose -Message "Configuring site collection as Home Site"
+        Set-PnPHomeSite -Url $Url
+    }
+
+    if ($Ensure -eq "Absent" -and $currentValues.Ensure -eq "Present")
+    {
+        # Remove home site
+        Remove-PnPHomeSite -Force
+    }
+}
+
+function Test-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet("Yes")]
+        [String]
+        $IsSingleInstance,
+
+        [Parameter()]
+        [System.String]
+        $Url,
+
+        [Parameter()]
+        [ValidateSet("Present", "Absent")]
+        [System.String]
+        $Ensure = "Present",
+
+        [Parameter(Mandatory = $true)]
+        [System.Management.Automation.PSCredential]
+        $GlobalAdminAccount
+    )
+
+    Write-Verbose -Message "Testing configuration for home site collection"
+
+    $CurrentValues = Get-TargetResource @PSBoundParameters
+
+    Write-Verbose -Message "Current Values: $(Convert-O365DscHashtableToString -Hashtable $CurrentValues)"
+    Write-Verbose -Message "Target Values: $(Convert-O365DscHashtableToString -Hashtable $PSBoundParameters)"
+
+    $valuesToCheck = @("Ensure")
+    if ($PSBoundParameters.ContainsKey("Url"))
+    {
+        $valuesToCheck += "Url"
+    }
+
+    $TestResult = Test-Office365DSCParameterState -CurrentValues $CurrentValues `
+        -Source $($MyInvocation.MyCommand.Source) `
+        -DesiredValues $PSBoundParameters `
+        -ValuesToCheck $valuesToCheck
+
+    Write-Verbose -Message "Test-TargetResource returned $TestResult"
+
+    return $TestResult
+}
+
+function Export-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.Management.Automation.PSCredential]
+        $GlobalAdminAccount
+    )
+
+    $params = @{
+        IsSingleInstance   = "Yes"
+        GlobalAdminAccount = $GlobalAdminAccount
+    }
+
+    $result = Get-TargetResource @params
+    $result.GlobalAdminAccount = "`$Credsglobaladmin"
+
+    $content = "        SPOHomeSite " + (New-GUID).ToString() + "`r`n"
+    $content += "        {`r`n"
+    $currentDSCBlock = Get-DSCBlock -Params $result -ModulePath $PSScriptRoot
+    $content += Convert-DSCStringParamToVariable -DSCBlock $currentDSCBlock -ParameterName "GlobalAdminAccount"
+    $content += "        }`r`n"
+    return $content
+}
+
+Export-ModuleMember -Function *-TargetResource

Modules/Office365DSC/DSCResources/MSFT_SPOHomeSite/MSFT_SPOHomeSite.schema.mof

@@ -0,0 +1,9 @@
+[ClassVersion("1.0.0.0"), FriendlyName("SPOHomeSite")]
+class MSFT_SPOHomeSite : OMI_BaseResource
+{
+    [Key, Description("Specifies the resource is a single instance, the value must be 'Yes'"), ValueMap{"Yes"}, Values{"Yes"}] String IsSingleInstance;
+    [Write, Description("The URL of the home site collection")] string Url;
+    [Write, Description("Present ensures the site collection is registered as home site, absent ensures it is unregistered"), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] string Ensure;
+    [Required, Description("Credentials of the SharePoint Global Admin"), EmbeddedInstance("MSFT_Credential")] string GlobalAdminAccount;
+};
+

Modules/Office365DSC/DSCResources/MSFT_SPOHomeSite/readme.md

@@ -0,0 +1,11 @@
+# Description
+
+This resource allows administrators to configure a Site Collection as the Home
+Site of the tenant. The menu of this SharePoint Site Collection will be shown on
+SharePoint Home.
+
+> NOTE:
+> This setting is not applied immediately and can take several hours to be fully
+> available within the tenant. Please use this resource with caution, as a direct
+> test run can lead to incorrect status results.
+> For more details about setting the home site, go to> aka.ms/homesites

Modules/Office365DSC/Examples/Resources/SPOHomeSite/1-ConfigureSPOHomeSite.ps1

@@ -0,0 +1,25 @@
+<#
+This example is used to test new resources and showcase the usage of new resources being worked on.
+It is not meant to use as a production baseline.
+#>
+
+Configuration Example
+{
+    param(
+        [Parameter(Mandatory = $true)]
+        [PSCredential]
+        $credsGlobalAdmin
+    )
+    Import-DscResource -ModuleName Office365DSC
+
+    node localhost
+    {
+        SPOHomeSite "SetMarketingSiteCollectionAsHomeSite"
+        {
+            IsSingleInstance     = "Yes"
+            Url                  = "https://office365dsc.sharepoint.com/sites/Marketing"
+            Ensure               = "Present"
+            GlobalAdminAccount   = $credsGlobalAdmin
+        }
+    }
+}

Modules/Office365DSC/Modules/O365DSCReverse.psm1

@@ -106,28 +106,56 @@ function Start-O365ConfigurationExtract
     Save-Credentials -UserName "globaladmin"
 
     $ResourcesPath = Join-Path -Path $PSScriptRoot `
-                               -ChildPath "..\DSCResources\" `
-                               -Resolve
-    $AllResources = Get-ChildItem $ResourcesPath -Recurse | Where-Object {$_.Name -like 'MSFT_*.psm1'}
+        -ChildPath "..\DSCResources\" `
+        -Resolve
+    $AllResources = Get-ChildItem $ResourcesPath -Recurse | Where-Object { $_.Name -like 'MSFT_*.psm1' }
 
     foreach ($ResourceModule in $AllResources)
     {
         try
         {
             $resourceName = $ResourceModule.Name.Split('.')[0].Replace('MSFT_', '')
-            $currentWorkload = $ResourceName.Substring(0,2)
+            $currentWorkload = $ResourceName.Substring(0, 2)
             switch ($currentWorkload)
             {
-                'O3' {$currentWorkload = 'O365'; break}
-                'OD' {$currentWorkload = 'OD'; break}
-                'PP' {$currentWorkload = 'PP'; break}
-                'SC' {$currentWorkload = 'SC'; break}
-                'SP' {$currentWorkload = 'SPO'; break}
-                'TE' {$currentWorkload = 'TEAMS'; break}
-                default {$currentWorkload = $null; break}
+                'O3'
+                {
+                    $currentWorkload = 'O365';
+                    break
+                }
+                'OD'
+                {
+                    $currentWorkload = 'OD';
+                    break
+                }
+                'PP'
+                {
+                    $currentWorkload = 'PP';
+                    break
+                }
+                'SC'
+                {
+                    $currentWorkload = 'SC';
+                    break
+                }
+                'SP'
+                {
+                    $currentWorkload = 'SPO';
+                    break
+                }
+                'TE'
+                {
+                    $currentWorkload = 'TEAMS';
+                    break
+                }
+                default
+                {
+                    $currentWorkload = $null;
+                    break
+                }
             }
             if (($null -ne $ComponentsToExtract -and
-                $ComponentsToExtract.Contains("chck" + $resourceName)) -or
+                    $ComponentsToExtract.Contains("chck" + $resourceName)) -or
                 $AllComponents -or ($null -ne $Workloads -and $Workloads.Contains($currentWorkload)))
             {
                 Import-Module $ResourceModule.FullName | Out-Null
@@ -197,7 +225,8 @@ function Start-O365ConfigurationExtract
             Write-Information "Directory `"$OutputDSCPath`" doesn't exist; creating..."
             New-Item -Path $OutputDSCPath -ItemType Directory | Out-Null
             if ($?)
-            { break
+            {
+                break
             }
         }
         catch
@@ -216,8 +245,8 @@ function Start-O365ConfigurationExtract
 
     #region Copy Downloaded files back into output folder
     if (($null -ne $ComponentsToExtract -and
-                $ComponentsToExtract.Contains("chckSPOApp")) -or
-                $AllComponents -or ($null -ne $Workloads -and $Workloads.Contains('SPO')))
+            $ComponentsToExtract.Contains("chckSPOApp")) -or
+        $AllComponents -or ($null -ne $Workloads -and $Workloads.Contains('SPO')))
     {
         $filesToDownload = Get-AllSPOPackages -GlobalAdminAccount $GlobalAdminAccount
         if ($filesToDownload.Count -gt 0)

Modules/Office365DSC/Modules/O365DSCReverseGUI.psm1

@@ -353,6 +353,15 @@ function Show-O365GUI
         $chckSPOHubSite.Text = "Hub Sites"
         $pnlSPO.Controls.Add($chckSPOHubSite)
 
+        $chckSPOHomeSite = New-Object System.Windows.Forms.CheckBox
+        $chckSPOHomeSite.Top = 40
+        $chckSPOHomeSite.AutoSize = $true;
+        $chckSPOHomeSite.Name = "chckSPOHomeSite"
+        $chckSPOHomeSite.Checked = $true
+        $chckSPOHomeSite.Enabled = $true
+        $chckSPOHomeSite.Text = "Home Site"
+        $pnlSPO.Controls.Add($chckSPOHomeSite)
+
         $chckSPOPropertyBag = New-Object System.Windows.Forms.CheckBox
         $chckSPOPropertyBag.Top = 60
         $chckSPOPropertyBag.AutoSize = $true;