diff --git a/src/PowerShellTips/2024-11-27-use-erroraction-to-change-what-happens-when-an-error-occurs.ps1 b/src/PowerShellTips/2024-11-27-use-erroraction-to-change-what-happens-when-an-error-occurs.ps1 new file mode 100644 index 0000000..9fdf97b --- /dev/null +++ b/src/PowerShellTips/2024-11-27-use-erroraction-to-change-what-happens-when-an-error-occurs.ps1 @@ -0,0 +1,48 @@ +$tip = [tiPS.PowerShellTip]::new() +$tip.CreatedDate = [DateTime]::Parse('2024-11-27') +$tip.Title = 'Use ErrorAction to change what happens when an error occurs' +$tip.TipText = @' +The `-ErrorAction` common parameter allows you to change what happens when a non-terminating error occurs in a cmdlet or script, such as when `Write-Error` is used. The default behavior is to display an error message and continue executing the script. You can change this behavior to: + +- `Stop`: Display the error message and stop executing the script. That is, treat it as a terminating error. +- `Continue`: Display the error message and continue executing the script. This is the default. +- `SilentlyContinue`: Suppress the error message (so it is not written to the error stream) and continue executing the script. +- `Ignore`: Suppress the error message and continue executing the script. Unlike SilentlyContinue, Ignore doesn't add the error message to the $Error automatic variable. +- `Inquire`: Display the error message and prompt the user to continue or stop executing the script. +- `Break`: Display the error message and enter the debugger. Also breaks into the debugger when a terminating error occurs. + +You can set the global behaviour for the current scope by setting the `$ErrorActionPreference` variable. This will be the default value for all cmdlets called that don't have the `-ErrorAction` parameter specified. +'@ +$tip.Example = @' +function Test-ErrorAction { + [CmdletBinding()] # This attribute is required to use the `-ErrorAction` common parameter. + param() + + Write-Error "This is an error message" +} + +Test-ErrorAction # Displays the error message and continues executing the script. +Test-ErrorAction -ErrorAction Stop # Displays the error message and stops executing the script. + +$ErrorActionPreference = "SilentlyContinue" # Sets the global error action preference to suppress error messages. +Test-ErrorAction # Suppresses the error message and continues executing the script, because the global setting is SilentlyContinue. +Test-ErrorAction -ErrorAction Stop # Displays the error message and stops executing the script, because the `-ErrorAction` parameter overrides the global setting. +'@ +$tip.Urls = @( + 'https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_commonparameters#-erroraction' + 'https://devblogs.microsoft.com/scripting/handling-errors-the-powershell-way/' +) +$tip.Category = [tiPS.TipCategory]::Syntax # Community, Editor, Module, NativeCmdlet, Performance, Security, Syntax, Terminal, or Other. +$tip.Author = 'Daniel Schroeder (deadlydog)' # Optional. Get credit for your tip. e.g. 'Daniel Schroeder (deadlydog)'. +#$tip.ExpiryDate = [DateTime]::Parse('2024-10-30') # Optional. If the tip is not relevant after a certain date, set the expiration date. e.g. Announcing a conference or event. + +# Category meanings: +# Community: Social events and community resources. e.g. PowerShell Summit, podcasts, etc. +# Editor: Editor tips and extensions. e.g. VSCode, ISE, etc. +# Module: Modules and module tips. e.g. PSScriptAnalyzer, Pester, etc. +# NativeCmdlet: Native cmdlet tips. e.g. Get-Process, Get-ChildItem, Get-Content, etc. +# Performance: Tips to improve runtime performance. e.g. foreach vs ForEach-Object, ForEach-Object -Parallel, etc. +# Security: Security tips. e.g. ExecutionPolicy, Constrained Language Mode, passwords, etc. +# Syntax: Syntax tips. e.g. splatting, pipeline, etc. +# Terminal: Terminal shortcuts and tips. e.g. PSReadLine, Windows Terminal, ConEmu, etc. +# Other: Tips that don't fit into any of the other categories. diff --git a/src/tiPS/PowerShellTips.json b/src/tiPS/PowerShellTips.json index 9d9ed0f..44f8845 100644 --- a/src/tiPS/PowerShellTips.json +++ b/src/tiPS/PowerShellTips.json @@ -789,5 +789,31 @@ "Category": 7, "ExpiryDate": "9999-12-31T23:59:59.9999999", "Author": "Adrian Muscat (adrimus)" + }, + { + "CreatedDate": "2024-11-18T00:00:00", + "Title": "Get the members of an array", + "TipText": "PowerShell sends the items in an array one at a time when you pipe an array to Get-Member and it ignores duplicates", + "Example": "# When you pipe to Get-Member PowerShell enumerates the array and you get the properties of the items inside the array, in this case a string\r\nPS C:\\> [array]$myArray = @('one','two','three')\r\nPS C:\\> $myArray | Get-Member\r\n\r\n TypeName: System.String\r\n\r\n# This example will output the members of the array\r\nPS C:\\> Get-Member -InputObject $myArray\r\n\r\n TypeName: System.Object[]\r\n\r\n# This will also do the same by making the array the second item in an array of arrays\r\n,$myArray | Get-Member\r\n\r\n# To see what type of object is in a variable use the GetType method.\r\nPS C:\\> $myArray.GetType()\r\n\r\nIsPublic IsSerial Name BaseType\r\n-------- -------- ---- --------\r\nTrue True Object[] System.Array", + "Urls": [ + "https://learn.microsoft.com/en-us/powershell/scripting/learn/deep-dives/everything-about-arrays?view=powershell-7.4", + "https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.4#get-the-members-of-an-array" + ], + "Category": 3, + "ExpiryDate": "9999-12-31T23:59:59.9999999", + "Author": "Adrian Muscat (adrimus)" + }, + { + "CreatedDate": "2024-11-27T00:00:00", + "Title": "Use ErrorAction to change what happens when an error occurs", + "TipText": "The `-ErrorAction` common parameter allows you to change what happens when a non-terminating error occurs in a cmdlet or script, such as when `Write-Error` is used. The default behavior is to display an error message and continue executing the script. You can change this behavior to:\r\n\r\n- `Stop`: Display the error message and stop executing the script. That is, treat it as a terminating error.\r\n- `Continue`: Display the error message and continue executing the script. This is the default.\r\n- `SilentlyContinue`: Suppress the error message (so it is not written to the error stream) and continue executing the script.\r\n- `Ignore`: Suppress the error message and continue executing the script. Unlike SilentlyContinue, Ignore doesn't add the error message to the $Error automatic variable.\r\n- `Inquire`: Display the error message and prompt the user to continue or stop executing the script.\r\n- `Break`: Display the error message and enter the debugger. Also breaks into the debugger when a terminating error occurs.\r\n\r\nYou can set the global behaviour for the current scope by setting the `$ErrorActionPreference` variable. This will be the default value for all cmdlets called that don't have the `-ErrorAction` parameter specified.", + "Example": "function Test-ErrorAction {\r\n [CmdletBinding()] # This attribute is required to use the `-ErrorAction` common parameter.\r\n param()\r\n\r\n Write-Error \"This is an error message\"\r\n}\r\n\r\nTest-ErrorAction # Displays the error message and continues executing the script.\r\nTest-ErrorAction -ErrorAction Stop # Displays the error message and stops executing the script.\r\n\r\n$ErrorActionPreference = \"SilentlyContinue\" # Sets the global error action preference to suppress error messages.\r\nTest-ErrorAction # Suppresses the error message and continues executing the script, because the global setting is SilentlyContinue.\r\nTest-ErrorAction -ErrorAction Stop # Displays the error message and stops executing the script, because the `-ErrorAction` parameter overrides the global setting.", + "Urls": [ + "https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_commonparameters#-erroraction", + "https://devblogs.microsoft.com/scripting/handling-errors-the-powershell-way/" + ], + "Category": 6, + "ExpiryDate": "9999-12-31T23:59:59.9999999", + "Author": "Daniel Schroeder (deadlydog)" } ]