From 18a1cc3b7a9affb6be438ae22296332d4d51bf43 Mon Sep 17 00:00:00 2001 From: Daniel Scott-Raynsford Date: Wed, 8 Jul 2020 19:36:50 +1200 Subject: [PATCH] Added Set-DscMachineRebootRequired and New-InvalidDataException (#44) --- CHANGELOG.md | 7 +++ README.md | 47 +++++++++++++++++++ RequiredModules.psd1 | 2 +- source/Public/New-InvalidDataException.ps1 | 46 ++++++++++++++++++ .../Public/Set-DscMachineRebootRequired.ps1 | 37 +++++++++++++++ .../Set-DscMachineRebootRequired.Tests.ps1 | 39 +++++++++++++++ .../Public/New-InvalidDataException.Tests.ps1 | 25 ++++++++++ 7 files changed, 202 insertions(+), 1 deletion(-) create mode 100644 source/Public/New-InvalidDataException.ps1 create mode 100644 source/Public/Set-DscMachineRebootRequired.ps1 create mode 100644 tests/Integration/Public/Set-DscMachineRebootRequired.Tests.ps1 create mode 100644 tests/Unit/Public/New-InvalidDataException.Tests.ps1 diff --git a/CHANGELOG.md b/CHANGELOG.md index e188a36..785d666 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 435e27c..739a222 100644 --- a/README.md +++ b/README.md @@ -322,6 +322,31 @@ if ( -not $resultOfEvaluation ) } ``` +### `New-InvalidDataException` + +Creates and throws an invalid data exception. + +#### Syntax + +```plaintext +New-InvalidDataException [-ErrorId] [-ErrorMessage] [] +``` + +### 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 [] +``` + +### 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 diff --git a/RequiredModules.psd1 b/RequiredModules.psd1 index 14a383c..1ba769f 100644 --- a/RequiredModules.psd1 +++ b/RequiredModules.psd1 @@ -9,7 +9,7 @@ InvokeBuild = 'latest' PSScriptAnalyzer = 'latest' - Pester = 'latest' + Pester = '4.10.1' Plaster = 'latest' ModuleBuilder = 'latest' ChangelogManagement = 'latest' diff --git a/source/Public/New-InvalidDataException.ps1 b/source/Public/New-InvalidDataException.ps1 new file mode 100644 index 0000000..17229ce --- /dev/null +++ b/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 +} diff --git a/source/Public/Set-DscMachineRebootRequired.ps1 b/source/Public/Set-DscMachineRebootRequired.ps1 new file mode 100644 index 0000000..281453f --- /dev/null +++ b/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 +} diff --git a/tests/Integration/Public/Set-DscMachineRebootRequired.Tests.ps1 b/tests/Integration/Public/Set-DscMachineRebootRequired.Tests.ps1 new file mode 100644 index 0000000..c1ade09 --- /dev/null +++ b/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 + } + } +} diff --git a/tests/Unit/Public/New-InvalidDataException.Tests.ps1 b/tests/Unit/Public/New-InvalidDataException.Tests.ps1 new file mode 100644 index 0000000..da143ed --- /dev/null +++ b/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 +}