|
| 1 | +# * PScmdWrapper |
| 2 | +function Show-ErrorMsg { |
| 3 | + <# |
| 4 | + .SYNOPSIS |
| 5 | + Displays a formatted error message and throws a terminating exception. |
| 6 | + |
| 7 | + .DESCRIPTION |
| 8 | + Show-ErrorMsg is a private utility function used to throw consistent, formatted |
| 9 | + terminating errors within the Set-TouchFile module. It is typically called by validation |
| 10 | + and wrapper functions to report failures with meaningful context. |
| 11 | + |
| 12 | + It accepts the name of the calling function, a custom message, and optionally an exception |
| 13 | + object. If an exception is provided, its message is appended to the output. This standardizes |
| 14 | + error output across the module, especially in `try/catch` and validation scenarios. |
| 15 | + |
| 16 | + .PARAMETER FunctionName |
| 17 | + The name of the function where the error originated. This is used to prefix the final message. |
| 18 | + |
| 19 | + .PARAMETER CustomMessage |
| 20 | + A short, human-readable explanation of what failed. This should clearly state what went wrong. |
| 21 | + |
| 22 | + .PARAMETER Exception |
| 23 | + (Optional) An exception object caught via `$_.Exception`. If provided, its message will be |
| 24 | + included in the error output. |
| 25 | + |
| 26 | + .EXAMPLE |
| 27 | + Show-ErrorMsg ` |
| 28 | + -FunctionName "Resolve-PathwErr" ` |
| 29 | + -CustomMessage "Failed to resolve path." |
| 30 | + |
| 31 | + Throws: |
| 32 | + [Resolve-PathwErr] Failed to resolve path. |
| 33 | + |
| 34 | + .EXAMPLE |
| 35 | + Show-ErrorMsg ` |
| 36 | + -FunctionName $MyInvocation.MyCommand.Name ` |
| 37 | + -CustomMessage "Manual resolve failed." ` |
| 38 | + -Exception $_.Exception |
| 39 | + |
| 40 | + Throws: |
| 41 | + [YourFunctionName] Manual resolve failed. Reason: <Exception.Message> |
| 42 | + |
| 43 | + .INPUTS |
| 44 | + [string], [System.Exception] |
| 45 | + |
| 46 | + .OUTPUTS |
| 47 | + None. The function throws a terminating exception. |
| 48 | + |
| 49 | + .NOTES |
| 50 | + Private helper function for the Set-TouchFile module. |
| 51 | + Not intended for direct use by end users. |
| 52 | + |
| 53 | + Scope: Private |
| 54 | + Author: Jialiang Chang |
| 55 | + Version: 1.0.0 |
| 56 | + Last Updated: 2025年06月24日 |
| 57 | + #> |
| 58 | + |
| 59 | + [CmdletBinding()] |
| 60 | + param ( |
| 61 | + [Parameter(Mandatory = $true)] |
| 62 | + [string]$FunctionName, |
| 63 | + |
| 64 | + [Parameter(Mandatory = $true)] |
| 65 | + [string]$CustomMessage, |
| 66 | + |
| 67 | + [Parameter(Mandatory = $false)] |
| 68 | + [System.Exception]$Exception |
| 69 | + ) |
| 70 | + |
| 71 | + $fullMessage = if ($Exception) { |
| 72 | + "[$FunctionName] $CustomMessage Reason: $($Exception.Message)" |
| 73 | + } |
| 74 | + else { |
| 75 | + "[$FunctionName] $CustomMessage" |
| 76 | + } |
| 77 | + |
| 78 | + throw $fullMessage |
| 79 | +} |
0 commit comments