Added Set-DscMachineRebootRequired and New-InvalidDataException (#44)

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## Added
+
+- Added cmdlet `New-InvalidDataException` - fixes [Issue #42](https://github.com/dsccommunity/DscResource.Common/issues/42).
+- Added cmdlet `Set-DscMachineRebootRequired` - fixes [Issue #43](https://github.com/dsccommunity/DscResource.Common/issues/43).
+- Pinned `Pester` module version to `4.10.1` to enable build until
+  `v5.x` is ready for use.
+
 ## [0.9.0] - 2020-05-18
 
 ### Added

README.md

@@ -322,6 +322,31 @@ if ( -not $resultOfEvaluation )
 }
 ```
 
+### `New-InvalidDataException`
+
+Creates and throws an invalid data exception.
+
+#### Syntax
+
+```plaintext
+New-InvalidDataException [-ErrorId] <string> [-ErrorMessage] <string> [<CommonParameters>]
+```
+
+### Outputs
+
+None.
+
+### Example
+
+```powershell
+if ( -not $resultOfEvaluation )
+{
+    $errorMessage = $script:localizedData.InvalidData -f $Action
+
+    New-InvalidDataException -ErrorId 'InvalidDataError' -ErrorMessage $errorMessage
+}
+```
+
 ### `New-InvalidOperationException`
 
 Creates and throws an invalid operation exception.
@@ -460,6 +485,28 @@ Remove-CommonParameter -Hashtable $PSBoundParameters
 
 Returns a new hashtable without the common and optional common parameters.
 
+### `Set-DscMachineRebootRequired`
+
+Set the DSC reboot required status variable.
+
+#### Syntax
+
+```plaintext
+Set-DscMachineRebootRequired [<CommonParameters>]
+```
+
+### Outputs
+
+None.
+
+### Example
+
+```powershell
+Set-DscMachineRebootRequired
+```
+
+Sets the $global:DSCMachineStatus variable to 1.
+
 ### `Set-PSModulePath`
 
 This is a wrapper to set environment variable PSModulePath in the current

RequiredModules.psd1

@@ -9,7 +9,7 @@
 
     InvokeBuild                 = 'latest'
     PSScriptAnalyzer            = 'latest'
-    Pester                      = 'latest'
+    Pester                      = '4.10.1'
     Plaster                     = 'latest'
     ModuleBuilder               = 'latest'
     ChangelogManagement         = 'latest'

source/Public/New-InvalidDataException.ps1

@@ -0,0 +1,46 @@
+<#
+    .SYNOPSIS
+        Creates and throws an invalid data exception.
+
+    .DESCRIPTION
+        Creates and throws an invalid data exception.
+
+    .PARAMETER ErrorId
+        The error Id to assign to the exception.
+
+    .PARAMETER ErrorMessage
+        The error message to assign to the exception.
+
+    .EXAMPLE
+        if ( -not $resultOfEvaluation )
+        {
+            $errorMessage = $script:localizedData.InvalidData -f $Action
+
+            New-InvalidDataException -ErrorId 'InvalidDataError' -ErrorMessage $errorMessage
+        }
+#>
+function New-InvalidDataException
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $ErrorId,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $ErrorMessage
+    )
+
+    $errorCategory = [System.Management.Automation.ErrorCategory]::InvalidData
+    $exception = New-Object `
+        -TypeName System.InvalidOperationException `
+        -ArgumentList $ErrorMessage
+    $errorRecord = New-Object `
+        -TypeName System.Management.Automation.ErrorRecord `
+        -ArgumentList $exception, $ErrorId, $errorCategory, $null
+
+    throw $errorRecord
+}

source/Public/Set-DscMachineRebootRequired.ps1

@@ -0,0 +1,37 @@
+<#
+    .SYNOPSIS
+        Set the DSC reboot required status variable.
+
+    .DESCRIPTION
+        Sets the global DSCMachineStatus variable to a value of 1.
+        This function is used to set the global variable that indicates
+        to the LCM that a reboot of the node is required.
+
+    .EXAMPLE
+        PS C:\> Set-DscMachineRebootRequired
+
+        Sets the $global:DSCMachineStatus variable to 1.
+
+    .NOTES
+        This function is implemented so that individual resource modules
+        do not need to use and therefore suppress Global variables
+        directly. It also enables mocking to increase testability of
+        consumers.
+#>
+function Set-DscMachineRebootRequired
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
+    # Suppressing this rule because $global:DSCMachineStatus is used to trigger a reboot.
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '')]
+    <#
+        Suppressing this rule because $global:DSCMachineStatus is only set,
+        never used (by design of Desired State Configuration).
+    #>
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '')]
+    [CmdletBinding()]
+    param
+    (
+    )
+
+    $global:DSCMachineStatus = 1
+}

tests/Integration/Public/Set-DscMachineRebootRequired.Tests.ps1

@@ -0,0 +1,39 @@
+$ProjectPath = "$PSScriptRoot\..\..\.." | Convert-Path
+$ProjectName = ((Get-ChildItem -Path $ProjectPath\*\*.psd1).Where{
+        ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and
+        $(try
+            {
+                Test-ModuleManifest $_.FullName -ErrorAction Stop
+            }
+            catch
+            {
+                $false
+            } )
+    }).BaseName
+
+Import-Module $ProjectName -Force
+
+Describe 'Set-DscMachineRebootRequired' -Tag 'Set-DscMachineRebootRequired' {
+    BeforeAll {
+        $script:currentDSCMachineStatus = $global:DSCMachineStatus
+    }
+
+    Context 'When setting the DSC reboot status' {
+        BeforeAll {
+            $global:DSCMachineStatus = 0
+        }
+
+        AfterAll {
+            if ($script:currentDSCMachineStatus -ne $global:DSCMachineStatus)
+            {
+                $global:DSCMachineStatus = $script:currentDSCMachineStatus
+            }
+        }
+
+        It 'Should not throw an error and have set the correct value' {
+            { Set-DscMachineRebootRequired } | Should -Not -Throw
+
+            $global:DSCMachineStatus | Should -Be 1
+        }
+    }
+}

tests/Unit/Public/New-InvalidDataException.Tests.ps1

@@ -0,0 +1,25 @@
+$ProjectPath = "$PSScriptRoot\..\..\.." | Convert-Path
+$ProjectName = ((Get-ChildItem -Path $ProjectPath\*\*.psd1).Where{
+        ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and
+        $(try { Test-ModuleManifest $_.FullName -ErrorAction Stop } catch { $false } )
+    }).BaseName
+
+Import-Module $ProjectName -Force
+
+Describe 'New-InvalidDataException' {
+    Context 'When calling with both the ErrorId and ErrorMessage parameter' {
+        It 'Should throw the correct error' {
+            $mockErrorId = 'MockedErrorId'
+            $mockErrorMessage = 'Mocked error'
+
+            $exception = { New-InvalidDataException -ErrorId $mockErrorId -ErrorMessage $mockErrorMessage } |
+                Should -Throw -PassThru
+
+            $exception.CategoryInfo.Category | Should -Be 'InvalidData'
+            $exception.FullyQualifiedErrorId | Should -Be $mockErrorId
+            $exception.Exception.Message | Should -Be $mockErrorMessage
+        }
+    }
+
+    Assert-VerifiableMock
+}