Merge pull request #1305 from ykuijs/SPUsageDefinition

[SPUsageDefinition] Added new resource
dsccommunity · Apr 8, 2021 · f0c242c · f0c242c
2 parents be2fe2b + 7e2b9b8
commit f0c242c
Show file tree

Hide file tree

Showing 6 changed files with 699 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- SPUsageDefinition
+  - New resource
+
 ## [4.6.0] - 2021-04-02
 
 ### Added

diff --git a/SharePointDsc/DSCResources/MSFT_SPUsageDefinition/MSFT_SPUsageDefinition.psm1 b/SharePointDsc/DSCResources/MSFT_SPUsageDefinition/MSFT_SPUsageDefinition.psm1
@@ -0,0 +1,308 @@
+$script:SPDscUtilModulePath = Join-Path -Path $PSScriptRoot -ChildPath '..\..\Modules\SharePointDsc.Util'
+Import-Module -Name $script:SPDscUtilModulePath
+
+function Get-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [ValidateRange(1, 31)]
+        [System.UInt32]
+        $DaysRetained,
+
+        [Parameter()]
+        [System.UInt32]
+        $DaysToKeepUsageFiles,
+
+        [Parameter()]
+        [System.UInt64]
+        $MaxTotalSizeInBytes,
+
+        [Parameter()]
+        [System.Boolean]
+        $Enabled,
+
+        [Parameter()]
+        [System.Boolean]
+        $UsageDatabaseEnabled,
+
+        [Parameter()]
+        [ValidateSet("Present", "Absent")]
+        [System.String]
+        $Ensure = "Present",
+
+        [Parameter()]
+        [System.Management.Automation.PSCredential]
+        $InstallAccount
+    )
+
+    Write-Verbose -Message "Getting configuration for Usage Definition {$Name}"
+
+    $result = Invoke-SPDscCommand -Credential $InstallAccount `
+        -Arguments $PSBoundParameters `
+        -ScriptBlock {
+        $params = $args[0]
+
+        $usageDefinition = Get-SPUsageDefinition -Identity $params.Name
+        $nullReturn = @{
+            Name                 = $params.Name
+            DaysRetained         = $params.DaysRetained
+            DaysToKeepUsageFiles = $params.DaysToKeepUsageFiles
+            MaxTotalSizeInBytes  = $params.MaxTotalSizeInBytes
+            Enabled              = $params.Enabled
+            UsageDatabaseEnabled = $params.UsageDatabaseEnabled
+            Ensure               = "Absent"
+        }
+        if ($null -eq $usageDefinition)
+        {
+            return $nullReturn
+        }
+
+        return @{
+            Name                 = $params.Name
+            DaysRetained         = $usageDefinition.Retention
+            DaysToKeepUsageFiles = $usageDefinition.DaysToKeepUsageFiles
+            MaxTotalSizeInBytes  = $usageDefinition.MaxTotalSizeInBytes
+            Enabled              = $usageDefinition.Enabled
+            UsageDatabaseEnabled = $usageDefinition.UsageDatabaseEnabled
+            Ensure               = "Present"
+        }
+    }
+    return $result
+}
+
+function Set-TargetResource
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [ValidateRange(1, 31)]
+        [System.UInt32]
+        $DaysRetained,
+
+        [Parameter()]
+        [System.UInt32]
+        $DaysToKeepUsageFiles,
+
+        [Parameter()]
+        [System.UInt64]
+        $MaxTotalSizeInBytes,
+
+        [Parameter()]
+        [System.Boolean]
+        $Enabled,
+
+        [Parameter()]
+        [System.Boolean]
+        $UsageDatabaseEnabled,
+
+        [Parameter()]
+        [ValidateSet("Present", "Absent")]
+        [System.String]
+        $Ensure = "Present",
+
+        [Parameter()]
+        [System.Management.Automation.PSCredential]
+        $InstallAccount
+    )
+
+    Write-Verbose -Message "Setting configuration for Usage Definition {$Name}"
+
+    if ($Ensure -eq "Absent")
+    {
+        $message = "This resource cannot remove a Usage Definition. Please use ensure equals Present."
+        Add-SPDscEvent -Message $message `
+            -EntryType 'Error' `
+            -EventID 100 `
+            -Source $MyInvocation.MyCommand.Source
+        throw $message
+    }
+
+    if ($PSBoundParameters.ContainsKey("DaysRetained") -eq $false -and `
+            $PSBoundParameters.ContainsKey("DaysToKeepUsageFiles") -eq $false -and `
+            $PSBoundParameters.ContainsKey("MaxTotalSizeInBytes") -eq $false -and `
+            $PSBoundParameters.ContainsKey("Enabled") -eq $false -and `
+            $PSBoundParameters.ContainsKey("UsageDatabaseEnabled") -eq $false)
+    {
+        $message = ("You have to at least specify one parameter: DaysRetained, DaysToKeepUsageFiles, " + `
+                "MaxTotalSizeInBytes, Enabled or UsageDatabaseEnabled.")
+        Add-SPDscEvent -Message $message `
+            -EntryType 'Error' `
+            -EventID 100 `
+            -Source $MyInvocation.MyCommand.Source
+        throw $message
+    }
+
+    if ((Get-SPDscInstalledProductVersion).FileMajorPart -eq 15 -and `
+            $PSBoundParameters.ContainsKey("UsageDatabaseEnabled") -eq $true)
+    {
+        $message = ("Parameter UsageDatabaseEnabled not supported in SharePoint 2013. Please " + `
+                "remove it from the configuration.")
+        Add-SPDscEvent -Message $message `
+            -EntryType 'Error' `
+            -EventID 100 `
+            -Source $MyInvocation.MyCommand.Source
+        throw $message
+    }
+
+    Invoke-SPDscCommand -Credential $InstallAccount `
+        -Arguments @($PSBoundParameters, $MyInvocation.MyCommand.Source) `
+        -ScriptBlock {
+        $params = $args[0]
+        $eventSource = $args[1]
+
+        $usageDefinition = Get-SPUsageDefinition -Identity $params.Name
+
+        if ($null -eq $usageDefinition)
+        {
+            $message = "The specified Usage Definition {" + $params.Name + "} could not be found."
+            Add-SPDscEvent -Message $message `
+                -EntryType 'Error' `
+                -EventID 100 `
+                -Source $eventSource
+            throw $message
+        }
+
+        $newParams = @{
+            Identity = $params.Name
+        }
+
+        if ($params.ContainsKey("DaysRetained"))
+        {
+            $newParams.DaysRetained = $params.DaysRetained
+        }
+
+        if ($params.ContainsKey("DaysToKeepUsageFiles"))
+        {
+            $newParams.DaysToKeepUsageFiles = $params.DaysToKeepUsageFiles
+        }
+
+        if ($params.ContainsKey("MaxTotalSizeInBytes"))
+        {
+            $newParams.MaxTotalSizeInBytes = $params.MaxTotalSizeInBytes
+        }
+
+        if ($params.ContainsKey("Enabled"))
+        {
+            $newParams.Enable = $params.Enabled
+        }
+
+        if ($params.ContainsKey("UsageDatabaseEnabled"))
+        {
+            $newParams.UsageDatabaseEnabled = $params.UsageDatabaseEnabled
+        }
+
+        Set-SPUsageDefinition @newParams
+    }
+}
+
+function Test-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [ValidateRange(1, 31)]
+        [System.UInt32]
+        $DaysRetained,
+
+        [Parameter()]
+        [System.UInt32]
+        $DaysToKeepUsageFiles,
+
+        [Parameter()]
+        [System.UInt64]
+        $MaxTotalSizeInBytes,
+
+        [Parameter()]
+        [System.Boolean]
+        $Enabled,
+
+        [Parameter()]
+        [System.Boolean]
+        $UsageDatabaseEnabled,
+
+        [Parameter()]
+        [ValidateSet("Present", "Absent")]
+        [System.String]
+        $Ensure = "Present",
+
+        [Parameter()]
+        [System.Management.Automation.PSCredential]
+        $InstallAccount
+    )
+
+    Write-Verbose -Message "Testing configuration for Usage Definition {$Name}"
+
+    $PSBoundParameters.Ensure = $Ensure
+
+    $CurrentValues = Get-TargetResource @PSBoundParameters
+
+    Write-Verbose -Message "Current Values: $(Convert-SPDscHashtableToString -Hashtable $CurrentValues)"
+    Write-Verbose -Message "Target Values: $(Convert-SPDscHashtableToString -Hashtable $PSBoundParameters)"
+
+    $result = Test-SPDscParameterState -CurrentValues $CurrentValues `
+        -Source $($MyInvocation.MyCommand.Source) `
+        -DesiredValues $PSBoundParameters `
+        -ValuesToCheck @("Ensure",
+        "Name",
+        "DaysRetained",
+        "DaysToKeepUsageFiles",
+        "MaxTotalSizeInBytes",
+        "Enabled",
+        "UsageDatabaseEnabled"
+    )
+
+    Write-Verbose -Message "Test-TargetResource returned $result"
+
+    return $result
+}
+
+function Export-TargetResource
+{
+    $VerbosePreference = "SilentlyContinue"
+    $ParentModuleBase = Get-Module "SharePointDsc" -ListAvailable | Select-Object -ExpandProperty Modulebase
+    $module = Join-Path -Path $ParentModuleBase -ChildPath "\DSCResources\MSFT_SPUsageDefinition\MSFT_SPUsageDefinition.psm1" -Resolve
+
+    $Content = ''
+    $params = Get-DSCFakeParameters -ModulePath $module
+
+    $usageDefinitions = Get-SPUsageDefinition
+    foreach ($usageDefinition in $usageDefinitions)
+    {
+        $PartialContent = "        SPUsageDefinition UsageDefinition_" + $($usageDefinition.Name -replace " ", '') + "`r`n"
+        $PartialContent += "        {`r`n"
+        $params.Name = $usageDefinition.Name
+        $params.Ensure = "Present"
+        $results = Get-TargetResource @params
+
+        $results = Repair-Credentials -results $results
+
+        $currentBlock = Get-DSCBlock -Params $results -ModulePath $module
+        $currentBlock = Convert-DSCStringParamToVariable -DSCBlock $currentBlock -ParameterName "PsDscRunAsCredential"
+
+        $PartialContent += $currentBlock
+        $PartialContent += "        }`r`n"
+        $Content += $PartialContent
+    }
+
+    return $Content
+}
+
+Export-ModuleMember -Function *-TargetResource
diff --git a/SharePointDsc/DSCResources/MSFT_SPUsageDefinition/MSFT_SPUsageDefinition.schema.mof b/SharePointDsc/DSCResources/MSFT_SPUsageDefinition/MSFT_SPUsageDefinition.schema.mof
@@ -0,0 +1,12 @@
+[ClassVersion("1.0.0.0"), FriendlyName("SPUsageDefinition")]
+class MSFT_SPUsageDefinition : OMI_BaseResource
+{
+    [Key, Description("Name of the Usage Definition to configure")] string Name;
+    [Write, Description("The number of days that usage is retained")] Uint32 DaysRetained;
+    [Write, Description("The number of days to keep usage file retention")] Uint32 DaysToKeepUsageFiles;
+    [Write, Description("Sets the maximum retention size in bytes")] Uint64 MaxTotalSizeInBytes;
+    [Write, Description("True enables the Usage Definition")] Boolean Enabled;
+    [Write, Description("True enables logging to the Usage database(SP2016 and above only)")] Boolean UsageDatabaseEnabled;
+    [Write, Description("Present to configure the diagnostics provider"), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] string Ensure;
+    [Write, Description("POWERSHELL 4 ONLY: The account to run this resource as, use PsDscRunAsCredential if using PowerShell 5"), EmbeddedInstance("MSFT_Credential")] String InstallAccount;
+};
diff --git a/SharePointDsc/DSCResources/MSFT_SPUsageDefinition/readme.md b/SharePointDsc/DSCResources/MSFT_SPUsageDefinition/readme.md
@@ -0,0 +1,11 @@
+# Description
+
+**Type:** Distributed
+**Requires CredSSP:** No
+
+This resource is responsible for configuring the Usage Definitions within
+the local SharePoint farm. Using Ensure=Absent is not supported.
+This resource can only apply configuration, not ensure they don't exist.
+
+To get an overview of all available Diagnostics Providers, use the cmdlet
+Get-SPUsageDefinition.