Add New-Exception, and PassThru parameter to exception commands

CHANGELOG.md

@@ -15,6 +15,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     that can copy from omne target to the other ([issue #102](https://github.com/dsccommunity/DscResource.Common/issues/102)).
   - A new parameter `PassThru` that, if specified, returns the path that
     was set.
+- `New-Exception`
+  - New command that creates and returns an `[System.Exception]`.
+- `New-ArgumentException`
+  - Now takes a parameter `PassThru` that returns the error record that was
+    created (and does not throw).
+- `New-InvalidOperationException`
+  - Now takes a parameter `PassThru` that returns the error record that was
+    created (and does not throw) ([issue #98](https://github.com/dsccommunity/DscResource.Common/issues/98)).
+- `New-InvalidResultException`
+  - Now takes a parameter `PassThru` that returns the error record that was
+    created (and does not throw).
+- `New-NotImplementedException`
+  - Now takes a parameter `PassThru` that returns the error record that was
+    created (and does not throw).
 
 ### Changed
 
@@ -23,20 +37,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Change the word cmdlet to command throughout in the documentation, code
   and localization strings.
 - A meta task now removes the built module from the session if it is imported.
+- Wiki source file HOME was modified to not link to README for help after
+  command documentation now is in the wiki.
 - `Get-LocalizedData`
   - Refactored to simplify execution and debugging. The command previously
     used a steppable pipeline (proxies `Import-LocalizedData`), that was
     removed since it was not possible to use the command in a pipeline.
     It just made it more complex and harder to debug. There are more
     debug messages added to hopefully simplify solving some hard to find
     edge cases bugs.
+- `New-ArgumentException`
+  - Now has a command alias `New-InvalidArgumentException` and the command
+    was renamed to match the exception name.
+- `New-InvalidDataException`
+  - The parameter `Message` has a parameter alias `ErrorMessage` to make
+    the command have the same parameter names as the other `New-*Exception`
+    commands.
 
 ### Fixed
 
 - `Assert-BoundParameter`
   - Fixed example in documentation that were referencing an invalid command name.
 - `Get-LocalizedData`
   - One debug message was wrongly using a format operator ([issue #111](https://github.com/dsccommunity/DscResource.Common/issues/111).
+- `New-ObjectNotFoundException`
+  - Updated typo in comment-based help.
 
 ## [0.16.0] - 2023-04-10
 

source/Public/New-InvalidArgumentException.ps1 → source/Public/New-ArgumentException.ps1

@@ -1,29 +1,41 @@
 <#
     .SYNOPSIS
-        Creates and throws an invalid argument exception.
+        Creates and throws or returns an invalid argument exception.
 
     .DESCRIPTION
-        Creates and throws an invalid argument exception.
+        Creates and throws or returns an invalid argument exception.
 
     .PARAMETER Message
         The message explaining why this error is being thrown.
 
     .PARAMETER ArgumentName
         The name of the invalid argument that is causing this error to be thrown.
 
+    .PARAMETER PassThru
+        If specified, returns the error record instead of throwing it.
+
     .OUTPUTS
         None
+        System.Management.Automation.ErrorRecord
 
     .EXAMPLE
-        New-InvalidArgumentException -ArgumentName 'Action' -Message 'My error message'
+        New-ArgumentException -ArgumentName 'Action' -Message 'My error message'
 
         Creates and throws an invalid argument exception for (parameter) 'Action'
         with the message 'My error message'.
+
+    .EXAMPLE
+        $errorRecord = New-ArgumentException -ArgumentName 'Action' -Message 'My error message' -PassThru
+
+        Creates an invalid argument exception for (parameter) 'Action'
+        with the message 'My error message' and returns the exception.
 #>
-function New-InvalidArgumentException
+
+function New-ArgumentException
 {
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
     [CmdletBinding()]
+    [Alias('New-InvalidArgumentException')]
     param
     (
         [Parameter(Mandatory = $true)]
@@ -34,7 +46,11 @@ function New-InvalidArgumentException
         [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
         [System.String]
-        $ArgumentName
+        $ArgumentName,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $PassThru
     )
 
     $argumentException = New-Object -TypeName 'ArgumentException' `
@@ -47,5 +63,12 @@ function New-InvalidArgumentException
 
     $errorRecord = New-Object @newObjectParameters
 
-    throw $errorRecord
+    if ($PassThru.IsPresent)
+    {
+        return $argumentException
+    }
+    else
+    {
+        throw $errorRecord
+    }
 }

source/Public/New-Exception.ps1

@@ -0,0 +1,68 @@
+<#
+    .SYNOPSIS
+        Creates and returns an exception.
+
+    .DESCRIPTION
+        Creates and returns an exception.
+
+    .OUTPUTS
+        None
+
+    .PARAMETER Message
+        The message explaining why this error is being thrown.
+
+    .PARAMETER ErrorRecord
+        The error record containing the exception that is causing this terminating error.
+
+    .OUTPUTS
+        System.Management.Automation.ErrorRecord
+
+    .EXAMPLE
+        $errorRecord = New-Exception -Message 'An error occurred'
+
+        Creates and returns an exception with the message 'An error occurred'.
+
+    .EXAMPLE
+        try
+        {
+            Get-ChildItem -Path $path -ErrorAction 'Stop'
+        }
+        catch
+        {
+            $exception = New-Exception -Message 'Could not get files' -ErrorRecord $_
+        }
+
+        Returns an exception with the message 'Could not get files' and includes
+        the exception that caused this terminating error.
+
+#>
+function New-Exception
+{
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $Message,
+
+        [Parameter()]
+        [ValidateNotNull()]
+        [System.Management.Automation.ErrorRecord]
+        $ErrorRecord
+    )
+
+    if ($null -eq $ErrorRecord)
+    {
+        $exception = New-Object -TypeName 'System.Exception' `
+            -ArgumentList @($Message)
+    }
+    else
+    {
+        $exception = New-Object -TypeName 'System.Exception' `
+            -ArgumentList @($Message, $ErrorRecord.Exception)
+    }
+
+    return $exception
+}

source/Public/New-InvalidDataException.ps1

@@ -15,7 +15,7 @@
         The error message to assign to the exception.
 
     .EXAMPLE
-        New-InvalidDataException -ErrorId 'InvalidDataError' -ErrorMessage 'My error message'
+        New-InvalidDataException -ErrorId 'InvalidDataError' -Message 'My error message'
 
         Creates and throws an invalid data exception with the error id 'InvalidDataError'
         and with the message 'My error message'.
@@ -31,16 +31,19 @@ function New-InvalidDataException
         $ErrorId,
 
         [Parameter(Mandatory = $true)]
+        [Alias('ErrorMessage')]
         [System.String]
-        $ErrorMessage
+        $Message
     )
 
     $errorCategory = [System.Management.Automation.ErrorCategory]::InvalidData
+
     $exception = New-Object `
-        -TypeName System.InvalidOperationException `
-        -ArgumentList $ErrorMessage
+        -TypeName 'System.InvalidOperationException' `
+        -ArgumentList $Message
+
     $errorRecord = New-Object `
-        -TypeName System.Management.Automation.ErrorRecord `
+        -TypeName 'System.Management.Automation.ErrorRecord' `
         -ArgumentList $exception, $ErrorId, $errorCategory, $null
 
     throw $errorRecord

source/Public/New-InvalidOperationException.ps1

@@ -1,19 +1,23 @@
 <#
     .SYNOPSIS
-        Creates and throws an invalid operation exception.
+        Creates and throws or returns an invalid operation exception.
 
     .DESCRIPTION
-        Creates and throws an invalid operation exception.
+        Creates and throws or returns an invalid operation exception.
 
     .OUTPUTS
-        None
+        None. If the PassThru parameter is not specified the command throws an error record.
+        System.Management.Automation.ErrorRecord. If the PassThru parameter is specified the command returns an error record.
 
     .PARAMETER Message
         The message explaining why this error is being thrown.
 
     .PARAMETER ErrorRecord
         The error record containing the exception that is causing this terminating error.
 
+    .PARAMETER PassThru
+        If specified, returns the error record instead of throwing it.
+
     .EXAMPLE
         try
         {
@@ -26,7 +30,12 @@
 
         Creates and throws an invalid operation exception with the message 'My error message'
         and includes the exception that caused this terminating error.
-#>
+
+    .EXAMPLE
+        $errorRecord = New-InvalidOperationException -Message 'My error message' -PassThru
+
+        Creates and returns an invalid operation exception with the message 'My error message'.
+    #>
 function New-InvalidOperationException
 {
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
@@ -41,7 +50,11 @@ function New-InvalidOperationException
         [Parameter()]
         [ValidateNotNull()]
         [System.Management.Automation.ErrorRecord]
-        $ErrorRecord
+        $ErrorRecord,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $PassThru
     )
 
     if ($null -eq $ErrorRecord)
@@ -65,7 +78,14 @@ function New-InvalidOperationException
         )
     }
 
-    $errorRecordToThrow = New-Object @newObjectParameters
+    $errorRecordToReturn = New-Object @newObjectParameters
 
-    throw $errorRecordToThrow
+    if ($PassThru.IsPresent)
+    {
+        return $invalidOperationException
+    }
+    else
+    {
+        throw $errorRecordToReturn
+    }
 }

source/Public/New-NotImplementedException.ps1

@@ -1,18 +1,22 @@
 <#
     .SYNOPSIS
-        Creates and throws an not implemented exception.
+        Creates and throws or returns an not implemented exception.
 
     .DESCRIPTION
-        Creates and throws an not implemented exception.
+        Creates and throws or returns an not implemented exception.
 
     .PARAMETER Message
         The message explaining why this error is being thrown.
 
     .PARAMETER ErrorRecord
         The error record containing the exception that is causing this terminating error.
 
+    .PARAMETER PassThru
+        If specified, returns the error record instead of throwing it.
+
     .OUTPUTS
         None
+        System.Management.Automation.ErrorRecord
 
     .EXAMPLE
         if ($notImplementedFeature)
@@ -21,7 +25,13 @@
         }
 
         Creates and throws an not implemented exception with the message 'This feature
-        is not implemented yet'
+        is not implemented yet'.
+
+    .EXAMPLE
+        $errorRecord = New-NotImplementedException -Message 'This feature is not implemented yet' -PassThru
+
+        Creates and returns an not implemented exception with the message 'This feature
+        is not implemented yet'.
 #>
 function New-NotImplementedException
 {
@@ -37,7 +47,11 @@ function New-NotImplementedException
         [Parameter()]
         [ValidateNotNull()]
         [System.Management.Automation.ErrorRecord]
-        $ErrorRecord
+        $ErrorRecord,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $PassThru
     )
 
     if ($null -eq $ErrorRecord)
@@ -61,7 +75,14 @@ function New-NotImplementedException
         )
     }
 
-    $errorRecordToThrow = New-Object @newObjectParameters
+    $errorRecord = New-Object @newObjectParameters
 
-    throw $errorRecordToThrow
+    if ($PassThru.IsPresent)
+    {
+        return $invalidOperationException
+    }
+    else
+    {
+        throw $errorRecord
+    }
 }

source/Public/New-ObjectNotFoundException.ps1

@@ -24,7 +24,7 @@
         }
         catch
         {
-            New-ObjectNotFoundException -Message 'COuld not get files' -ErrorRecord $_
+            New-ObjectNotFoundException -Message 'Could not get files' -ErrorRecord $_
         }
 
         Creates and throws an object not found exception with the message 'Could not

source/WikiSource/Home.md

@@ -2,8 +2,6 @@
 
 <sup>*DscResource.Common v#.#.#*</sup>
 
-For documentation please see the [README.md](https://github.com/dsccommunity/DscResource.Common/blob/main/README.md)
-
 Please leave comments, feature requests, and bug reports for this module in
 the [issues section](https://github.com/dsccommunity/DscResource.Common/issues)
 for this repository.