OfficeOnlineServerHost: New resource proposal

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - OfficeOnlineServerDsc
   - Imports DscResource.Common module
+- OfficeOnlineServerHost
+  - Adds new resource OfficeOnlineServerHost
 
 ### Changed
 

src/DSCResources/MSFT_OfficeOnlineServerHost/MSFT_OfficeOnlineServerHost.psm1

@@ -0,0 +1,234 @@
+$script:resourceHelperModulePath = @(
+    (Join-Path -Path $PSScriptRoot -ChildPath '..\..\Modules\OfficeOnlineServerDsc.Util'),
+    (Join-Path -Path $PSScriptRoot -ChildPath '..\..\Modules\DscResource.Common')
+)
+Import-Module -Name $script:resourceHelperModulePath
+
+$script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'
+$script:OOSDscRegKey = "HKLM:\SOFTWARE\OOSDsc"
+
+function Get-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [String]
+        $IsSingleInstance,
+
+        [Parameter()]
+        [System.String[]]
+        $Domains,
+
+        [Parameter()]
+        [System.String[]]
+        $DomainsToInclude,
+
+        [Parameter()]
+        [System.String[]]
+        $DomainsToExclude
+    )
+
+    Write-Verbose -Message $script:localizedData.GetAllowList
+
+    Import-Module -Name 'OfficeWebApps' -ErrorAction 'Stop' -Verbose:$false
+
+    Confirm-OosDscEnvironmentVariables
+
+    $currentValues = Remove-CommonParameter $PSBoundParameters
+
+    Test-OfficeOnlineServerHostBoundParameter @currentValues
+
+    try
+    {
+        $currentValues.Domains = [System.Array](Get-OfficeWebAppsHost -ErrorAction 'Stop').AllowList
+    }
+    catch
+    {
+        throw $_
+    }
+
+    return $currentValues
+}
+
+function Set-TargetResource
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [String]
+        $IsSingleInstance,
+
+        [Parameter()]
+        [System.String[]]
+        $Domains,
+
+        [Parameter()]
+        [System.String[]]
+        $DomainsToInclude,
+
+        [Parameter()]
+        [System.String[]]
+        $DomainsToExclude
+    )
+
+    Write-Verbose -Message $script:localizedData.UpdateAllowList
+
+    $currentValues = Get-TargetResource -Domains $Domains -IsSingleInstance 'Yes'
+    $targetValues = Remove-CommonParameter $PSBoundParameters
+
+    if ($PSBoundParameters.ContainsKey('Domains'))
+    {
+        # Pass empty array, then all existing domains will be deleted
+        if ($null -eq $Domains)
+        {
+            $targetValues.Add('DomainsToExclude', $currentValues.Domains) | Out-Null
+        }
+        # Compares current vs target domains and decided wich ones to keep
+        else
+        {
+            $targetValues.Add('DomainsToInclude', $Domains) | Out-Null
+
+            if ($domainsToBeExcluded = $currentValues.Domains | Where-Object -FilterScript { $_ -notin $Domains })
+            {
+                $targetValues.Add('DomainsToExclude', $domainsToBeExcluded) | Out-Null
+            }
+        }
+    }
+
+    # Removes only the passed domains.
+    if ($targetValues.ContainsKey('DomainsToExclude'))
+    {
+        foreach ($domain in $targetValues.DomainsToExclude)
+        {
+            if ($domain -in $currentValues.Domains)
+            {
+                Write-Verbose -Message "$($script:localizedData.RemoveDomain) '$domain'"
+                Remove-OfficeWebAppsHost -Domain $domain | Out-Null
+            }
+        }
+    }
+
+    # Adds the passed domains. Already existing ones stay unchanged.
+    if ($targetValues.ContainsKey('DomainsToInclude'))
+    {
+        foreach ($domain in $targetValues.DomainsToInclude)
+        {
+            if ($domain -notin $currentValues.Domains)
+            {
+                Write-Verbose -Message "$($script:localizedData.AddDomain) '$domain'"
+                New-OfficeWebAppsHost -Domain $domain | Out-Null
+            }
+        }
+    }
+}
+
+function Test-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [String]
+        $IsSingleInstance,
+
+        [Parameter()]
+        [System.String[]]
+        $Domains,
+
+        [Parameter()]
+        [System.String[]]
+        $DomainsToInclude,
+
+        [Parameter()]
+        [System.String[]]
+        $DomainsToExclude
+    )
+
+    Write-Verbose -Message $script:localizedData.TestAllowList
+
+    $currentValues = Get-TargetResource @PSBoundParameters
+    $targetValues = Remove-CommonParameter -Hashtable $PSBoundParameters
+
+    Write-Verbose -Message "Current Values: $(Convert-OosDscHashtableToString -Hashtable $currentValues)"
+    Write-Verbose -Message "Target Values: $(Convert-OosDscHashtableToString -Hashtable $targetValues)"
+
+    if ($targetValues.ContainsKey('Domains'))
+    {
+        return Test-DscParameterState -CurrentValues $currentValues -DesiredValues $targetValues -Properties 'Domains' -TurnOffTypeChecking
+    }
+
+    if ($targetValues.ContainsKey('DomainsToInclude'))
+    {
+        foreach ($domain in $targetValues.DomainsToInclude)
+        {
+            if ($domain -notin $currentValues.Domains)
+            {
+                return $false
+            }
+        }
+    }
+
+    if ($targetValues.ContainsKey('DomainsToExclude'))
+    {
+        foreach ($domain in $targetValues.DomainsToExclude)
+        {
+            if ($domain -in $currentValues.Domains)
+            {
+                return $false
+            }
+        }
+    }
+
+    return $true
+}
+
+<#
+    .SYNOPSIS
+        Validates the PSBoundParameters of OfficeOnlineServerHost
+
+    .EXAMPLE
+        Test-OfficeOnlineServerHostBoundParameter @PSBoundParameters
+#>
+function Test-OfficeOnlineServerHostBoundParameter
+{
+    [CmdletBinding()]
+    [OutputType()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [String]
+        $IsSingleInstance,
+
+        [Parameter()]
+        [System.String[]]
+        $Domains,
+
+        [Parameter()]
+        [System.String[]]
+        $DomainsToInclude,
+
+        [Parameter()]
+        [System.String[]]
+        $DomainsToExclude
+    )
+
+    Assert-BoundParameter -BoundParameterList $PSBoundParameters -MutuallyExclusiveList1 'Domains' -MutuallyExclusiveList2 'DomainsToInclude', 'DomainsToExclude'
+
+    if (($PSBoundParameters.ContainsKey('DomainsToInclude') -and $PSBoundParameters.ContainsKey('DomainsToExclude')))
+    {
+        if (Compare-Object -ReferenceObject $DomainsToInclude -DifferenceObject $DomainsToExclude -IncludeEqual -ExcludeDifferent)
+        {
+            New-InvalidOperationException -Message $script:localizedData.DuplicateDomains
+        }
+    }
+}
+
+Export-ModuleMember -Function *-TargetResource

src/DSCResources/MSFT_OfficeOnlineServerHost/MSFT_OfficeOnlineServerHost.schema.mof

@@ -0,0 +1,8 @@
+[ClassVersion("1.0.0.0"), FriendlyName("OfficeOnlineServerHost")]
+class MSFT_OfficeOnlineServerHost : OMI_BaseResource
+{
+    [Key, Description("Specifies the resource is a single instance, the value must be 'Yes'"),ValueMap{"Yes"},Values{"Yes"}] String IsSingleInstance;
+    [Write, Description("Host domains to which Office Online Server allows file operations requests. Already existing ones, that are not included in this list, will be removed.")] String Domains[];
+    [Write, Description("Host domains that should be added to the Office Online Server hosts allow list.")] String DomainsToInclude[];
+    [Write, Description("Host domains that should be removed from the Office Online Server hosts allow list.")] String DomainsToExclude[];
+};

src/DSCResources/MSFT_OfficeOnlineServerHost/en-US/MSFT_OfficeOnlineServerHost.strings.psd1

@@ -0,0 +1,8 @@
+ConvertFrom-StringData @'
+    GetAllowList = Retrieving Office Online Server Farm host allow list.
+    UpdateAllowList = Updating Office Online Server Farm host allow list.
+    RemoveDomain = Removing domain
+    AddDomain = Adding domain
+    TestAllowList = Testing Office Online Server Farm host allow list.
+    DuplicateDomains = DomainsToInclude and DomainsToExclude contains one or more identical values. Please resolve
+'@

src/DSCResources/MSFT_OfficeOnlineServerHost/readme.md

@@ -0,0 +1,4 @@
+# Description
+
+The OfficeOnlineServerHost resource is used to manage host domains 
+to which Office Online Server allows file operations requests.

src/Examples/FullExamples/NewFarm.ps1

@@ -99,4 +99,11 @@ Configuration Example
         EditingEnabled = $true
         DependsOn      = "[OfficeOnlineServerInstall]InstallBinaries"
     }
+
+    OfficeOnlineServerHost 'HostsAllowList'
+    {
+        IsSingleInstance = 'Yes'
+        Domains          = 'example.contoso.com'
+        DependsOn        = "[OfficeOnlineServerFarm]LocalFarm"
+    }
 }

src/Examples/Resources/OfficeOnlineServerHost/1-AddHostToAllowList.ps1

@@ -0,0 +1,52 @@
+
+<#PSScriptInfo
+
+.VERSION 1.5.0
+
+.GUID 80d306fa-8bd4-4a8d-9f7a-bf40df95e661
+
+.AUTHOR DSC Community
+
+.COMPANYNAME DSC Community
+
+.COPYRIGHT DSC Community contributors. All rights reserved.
+
+.TAGS
+
+.LICENSEURI https://github.com/dsccommunity/OfficeOnlineServerDsc/blob/master/LICENSE
+
+.PROJECTURI https://github.com/dsccommunity/OfficeOnlineServerDsc
+
+.ICONURI https://dsccommunity.org/images/DSC_Logo_300p.png
+
+.EXTERNALMODULEDEPENDENCIES
+
+.REQUIREDSCRIPTS
+
+.EXTERNALSCRIPTDEPENDENCIES
+
+.RELEASENOTES
+Updated author, copyright notice, and URLs.
+
+.PRIVATEDATA
+
+#>
+
+<#
+.DESCRIPTION
+ This example shows how to adds a host domain to the list of host domains
+ to which Office Online Server allows file operations requests.
+#>
+
+Configuration Example
+{
+        Param()
+
+        Import-DscResource -ModuleName OfficeOnlineServerDsc
+
+        OfficeOnlineServerHost 'HostsAllowList'
+        {
+                IsSingleInstance = 'Yes'
+                Domains          = 'example.contoso.com'
+        }
+}

tests/Integration/MSFT_OfficeOnlineServerWebAppsHost.Integration.tests.ps1

@@ -0,0 +1,52 @@
+$Script:DSCModuleName = 'OfficeOnlineServerDsc'
+$Script:DSCResourceName = 'MSFT_OfficeOnlineServerHost'
+
+[String] $moduleRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $Script:MyInvocation.MyCommand.Path))
+if ( (-not (Test-Path -Path (Join-Path -Path $moduleRoot -ChildPath 'DSCResource.Tests'))) -or `
+    (-not (Test-Path -Path (Join-Path -Path $moduleRoot -ChildPath 'DSCResource.Tests\TestHelper.psm1'))) )
+{
+    & git @('clone', 'https://github.com/PowerShell/DscResource.Tests.git', (Join-Path -Path $moduleRoot -ChildPath '\DSCResource.Tests\'))
+}
+else
+{
+    & git @('-C', (Join-Path -Path $moduleRoot -ChildPath '\DSCResource.Tests\'), 'pull')
+}
+Import-Module (Join-Path -Path $moduleRoot -ChildPath 'DSCResource.Tests\TestHelper.psm1') -Force
+$TestEnvironment = Initialize-TestEnvironment `
+    -DSCModuleName $Script:DSCModuleName `
+    -DSCResourceName $Script:DSCResourceName `
+    -TestType Integration
+
+try
+{
+    $ConfigFile = Join-Path -Path $PSScriptRoot -ChildPath "$($Script:DSCResourceName).config.ps1"
+    . $ConfigFile
+
+    Describe "$($Script:DSCResourceName)_Integration" {
+        It 'Should compile without throwing' {
+            {
+                Invoke-Expression -Command "$($Script:DSCResourceName)_Config -OutputPath `$TestEnvironment.WorkingFolder"
+                Start-DscConfiguration -Path $TestEnvironment.WorkingFolder `
+                    -ComputerName localhost -Wait -Verbose -Force
+            } | Should not throw
+        }
+
+        It 'Should be able to call Get-DscConfiguration without throwing' {
+            { Get-DscConfiguration -Verbose -ErrorAction Stop } | Should Not throw
+        }
+
+        It 'Should have set the resource and all the parameters should match' {
+
+            $result = Get-OfficeWebAppsHost
+
+            foreach ($key in $webAppsHost.keys)
+            {
+                $result.$key | Should Be $webAppsHost[$key]
+            }
+        }
+    }
+}
+finally
+{
+    Restore-TestEnvironment -TestEnvironment $TestEnvironment
+}