Raise error powershell

Everything you wanted to know about exceptions

Error handling is just part of life when it comes to writing code. We can often check and validate conditions for expected behavior. When the unexpected happens, we turn to exception handling. You can easily handle exceptions generated by other people’s code or you can generate your own exceptions for others to handle.

The original version of this article appeared on the blog written by @KevinMarquette. The PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at PowerShellExplained.com.

Basic terminology

We need to cover some basic terms before we jump into this one.

Exception

An Exception is like an event that is created when normal error handling can’t deal with the issue. Trying to divide a number by zero or running out of memory are examples of something that creates an exception. Sometimes the author of the code you’re using creates exceptions for certain issues when they happen.

Throw and Catch

When an exception happens, we say that an exception is thrown. To handle a thrown exception, you need to catch it. If an exception is thrown and it isn’t caught by something, the script stops executing.

The call stack

The call stack is the list of functions that have called each other. When a function is called, it gets added to the stack or the top of the list. When the function exits or returns, it is removed from the stack.

When an exception is thrown, that call stack is checked in order for an exception handler to catch it.

Terminating and non-terminating errors

An exception is generally a terminating error. A thrown exception is either be caught or it terminates the current execution. By default, a non-terminating error is generated by Write-Error and it adds an error to the output stream without throwing an exception.

I point this out because Write-Error and other non-terminating errors do not trigger the catch .

Swallowing an exception

This is when you catch an error just to suppress it. Do this with caution because it can make troubleshooting issues very difficult.

Basic command syntax

Here is a quick overview of the basic exception handling syntax used in PowerShell.

Throw

To create our own exception event, we throw an exception with the throw keyword.

This creates a runtime exception that is a terminating error. It’s handled by a catch in a calling function or exits the script with a message like this.

Write-Error -ErrorAction Stop

I mentioned that Write-Error doesn’t throw a terminating error by default. If you specify -ErrorAction Stop , Write-Error generates a terminating error that can be handled with a catch .

Thank you to Lee Dailey for reminding about using -ErrorAction Stop this way.

Cmdlet -ErrorAction Stop

If you specify -ErrorAction Stop on any advanced function or cmdlet, it turns all Write-Error statements into terminating errors that stop execution or that can be handled by a catch .

Try/Catch

The way exception handling works in PowerShell (and many other languages) is that you first try a section of code and if it throws an error, you can catch it. Here is a quick sample.

The catch script only runs if there’s a terminating error. If the try executes correctly, then it skips over the catch . You can access the exception information in the catch block using the $_ variable.

Try/Finally

Sometimes you don’t need to handle an error but still need some code to execute if an exception happens or not. A finally script does exactly that.

Take a look at this example:

Anytime you open or connect to a resource, you should close it. If the ExecuteNonQuery() throws an exception, the connection isn’t closed. Here is the same code inside a try/finally block.

In this example, the connection is closed if there’s an error. It also is closed if there’s no error. The finally script runs every time.

Because you’re not catching the exception, it still gets propagated up the call stack.

Try/Catch/Finally

It’s perfectly valid to use catch and finally together. Most of the time you’ll use one or the other, but you may find scenarios where you use both.

$PSItem

Now that we got the basics out of the way, we can dig a little deeper.

Inside the catch block, there’s an automatic variable ( $PSItem or $_ ) of type ErrorRecord that contains the details about the exception. Here is a quick overview of some of the key properties.

For these examples, I used an invalid path in ReadAllText to generate this exception.

PSItem.ToString()

This gives you the cleanest message to use in logging and general output. ToString() is automatically called if $PSItem is placed inside a string.

$PSItem.InvocationInfo

This property contains additional information collected by PowerShell about the function or script where the exception was thrown. Here is the InvocationInfo from the sample exception that I created.

The important details here show the ScriptName , the Line of code and the ScriptLineNumber where the invocation started.

$PSItem.ScriptStackTrace

This property shows the order of function calls that got you to the code where the exception was generated.

I’m only making calls to functions in the same script but this would track the calls if multiple scripts were involved.

$PSItem.Exception

This is the actual exception that was thrown.

$PSItem.Exception.Message

This is the general message that describes the exception and is a good starting point when troubleshooting. Most exceptions have a default message but can also be set to something custom when the exception is thrown.

This is also the message returned when calling $PSItem.ToString() if there was not one set on the ErrorRecord .

$PSItem.Exception.InnerException

Exceptions can contain inner exceptions. This is often the case when the code you’re calling catches an exception and throws a different exception. The original exception is placed inside the new exception.

I will revisit this later when I talk about re-throwing exceptions.

$PSItem.Exception.StackTrace

This is the StackTrace for the exception. I showed a ScriptStackTrace above, but this one is for the calls to managed code.

You only get this stack trace when the event is thrown from managed code. I’m calling a .NET framework function directly so that is all we can see in this example. Generally when you’re looking at a stack trace, you’re looking for where your code stops and the system calls begin.

Working with exceptions

There is more to exceptions than the basic syntax and exception properties.

Catching typed exceptions

You can be selective with the exceptions that you catch. Exceptions have a type and you can specify the type of exception you want to catch.

The exception type is checked for each catch block until one is found that matches your exception. It’s important to realize that exceptions can inherit from other exceptions. In the example above, FileNotFoundException inherits from IOException . So if the IOException was first, then it would get called instead. Only one catch block is invoked even if there are multiple matches.

If we had a System.IO.PathTooLongException , the IOException would match but if we had a InsufficientMemoryException then nothing would catch it and it would propagate up the stack.

Catch multiple types at once

It’s possible to catch multiple exception types with the same catch statement.

Thank you /u/Sheppard_Ra for suggesting this addition.

Throwing typed exceptions

You can throw typed exceptions in PowerShell. Instead of calling throw with a string:

Use an exception accelerator like this:

But you have to specify a message when you do it that way.

You can also create a new instance of an exception to be thrown. The message is optional when you do this because the system has default messages for all built-in exceptions.

If you’re not using PowerShell 5.0 or higher, you must use the older New-Object approach.

By using a typed exception, you (or others) can catch the exception by the type as mentioned in the previous section.

Write-Error -Exception

We can add these typed exceptions to Write-Error and we can still catch the errors by exception type. Use Write-Error like in these examples:

Then we can catch it like this:

The big list of .NET exceptions

I compiled a master list with the help of the Reddit/r/PowerShell community that contains hundreds of .NET exceptions to complement this post.

I start by searching that list for exceptions that feel like they would be a good fit for my situation. You should try to use exceptions in the base System namespace.

Exceptions are objects

If you start using a lot of typed exceptions, remember that they are objects. Different exceptions have different constructors and properties. If we look at the FileNotFoundException documentation for System.IO.FileNotFoundException , we see that we can pass in a message and a file path.

And it has a FileName property that exposes that file path.

You should consult the .NET documentation for other constructors and object properties.

Re-throwing an exception

If all you’re going to do in your catch block is throw the same exception, then don’t catch it. You should only catch an exception that you plan to handle or perform some action when it happens.

There are times where you want to perform an action on an exception but re-throw the exception so something downstream can deal with it. We could write a message or log the problem close to where we discover it but handle the issue further up the stack.

Interestingly enough, we can call throw from within the catch and it re-throws the current exception.

We want to re-throw the exception to preserve the original execution information like source script and line number. If we throw a new exception at this point, it hides where the exception started.

Re-throwing a new exception

If you catch an exception but you want to throw a different one, then you should nest the original exception inside the new one. This allows someone down the stack to access it as the $PSItem.Exception.InnerException .

$PSCmdlet.ThrowTerminatingError()

The one thing that I don’t like about using throw for raw exceptions is that the error message points at the throw statement and indicates that line is where the problem is.

Having the error message tell me that my script is broken because I called throw on line 31 is a bad message for users of your script to see. It doesn’t tell them anything useful.

Dexter Dhami pointed out that I can use ThrowTerminatingError() to correct that.

If we assume that ThrowTerminatingError() was called inside a function called Get-Resource , then this is the error that we would see.

Do you see how it points to the Get-Resource function as the source of the problem? That tells the user something useful.

Because $PSItem is an ErrorRecord , we can also use ThrowTerminatingError this way to re-throw.

This changes the source of the error to the Cmdlet and hide the internals of your function from the users of your Cmdlet.

Try can create terminating errors

Kirk Munro points out that some exceptions are only terminating errors when executed inside a try/catch block. Here is the example he gave me that generates a divide by zero runtime exception.

Then invoke it like this to see it generate the error and still output the message.

But by placing that same code inside a try/catch , we see something else happen.

We see the error become a terminating error and not output the first message. What I don’t like about this one is that you can have this code in a function and it acts differently if someone is using a try/catch .

I have not ran into issues with this myself but it is corner case to be aware of.

$PSCmdlet.ThrowTerminatingError() inside try/catch

One nuance of $PSCmdlet.ThrowTerminatingError() is that it creates a terminating error within your Cmdlet but it turns into a non-terminating error after it leaves your Cmdlet. This leaves the burden on the caller of your function to decide how to handle the error. They can turn it back into a terminating error by using -ErrorAction Stop or calling it from within a try<. >catch <. >.

Public function templates

One last take a way I had with my conversation with Kirk Munro was that he places a try<. >catch <. >around every begin , process and end block in all of his advanced functions. In those generic catch blocks, he has a single line using $PSCmdlet.ThrowTerminatingError($PSItem) to deal with all exceptions leaving his functions.

Because everything is in a try statement within his functions, everything acts consistently. This also gives clean errors to the end user that hides the internal code from the generated error.

I focused on the try/catch aspect of exceptions. But there’s one legacy feature I need to mention before we wrap this up.

A trap is placed in a script or function to catch all exceptions that happen in that scope. When an exception happens, the code in the trap is executed and then the normal code continues. If multiple exceptions happen, then the trap is called over and over.

I personally never adopted this approach but I can see the value in admin or controller scripts that log any and all exceptions, then still continue to execute.

Adding proper exception handling to your scripts not only make them more stable, but also makes it easier for you to troubleshoot those exceptions.

I spent a lot of time talking throw because it is a core concept when talking about exception handling. PowerShell also gave us Write-Error that handles all the situations where you would use throw . So don’t think that you need to be using throw after reading this.

Now that I have taken the time to write about exception handling in this detail, I’m going to switch over to using Write-Error -Stop to generate errors in my code. I’m also going to take Kirk’s advice and make ThrowTerminatingError my goto exception handler for every function.

Источник

Все, что вы хотели знать об исключениях

Обработка ошибок — это лишь часть процесса написания кода. Зачастую можно проверить, выполняются ли условия для ожидаемого поведения. При возникновении непредвиденной ситуации необходимо переключиться на обработку исключений. Вы можете легко обрабатывать исключения, созданные кодом других разработчиков, или создавать собственные исключения, которые смогут обработать другие.

Оригинал этой статьи впервые был опубликован в блоге автора @KevinMarquette. Группа разработчиков PowerShell благодарит Кевина за то, что он поделился с нами этими материалами. Читайте его блог — PowerShellExplained.com.

Базовая терминология

Прежде чем двигаться дальше, необходимо разобраться с основными терминами.

Исключение

Исключение подобно событию, которое создается, когда не удается справиться с проблемой путем обычной обработки ошибок. Примерами проблем, которые приводят к исключениям, могут служить попытки деления числа на ноль и нехватка памяти. Иногда автор кода, который вы используете, создает исключения для определенных проблем в случае их возникновения.

Throw и Catch

Когда происходит исключение, мы говорим, что оно вызвано. Чтобы обработать вызванное исключение, его необходимо перехватить. Если вызывается исключение, которое не перехватывается никакими объектами, выполнение скрипта прекращается.

Стек вызовов

Стек вызовов — это список функций, которые вызывали друг друга. При вызове функции она добавляется в стек или вверх списка. При выходе из функции или возврате ею значения она удаляется из стека.

При вызове исключения выполняется проверка этого стека вызовов, чтобы обработчик исключений мог его перехватить.

Неустранимые и устранимые ошибки

Исключение обычно является неустранимой ошибкой. Вызванное исключение либо перехватывается, либо завершает текущее выполнение. По умолчанию устранимая ошибка генерируется Write-Error и приводит к добавлению ошибки в выходной поток без вызова исключения.

Обращаю внимание на это потому, что Write-Error и другие устранимые ошибки не активируют catch .

Игнорирование исключения

Это ситуация, когда ошибка перехватывается только для того, чтобы ее подавить. Используйте эту возможность с осторожностью, поскольку это может существенно усложнить устранение неполадок.

Основной синтаксис команды

Ниже приведен краткий обзор основного синтаксиса обработки исключений, используемого в PowerShell.

Ключевое слово throw

Чтобы вызвать собственное событие исключения, воспользуйтесь ключевым словом throw .

Это приведет к созданию исключения во время выполнения, которое является неустранимой ошибкой. Оно обрабатывается с помощью catch в вызывающей функции или приводит к выходу из скрипта с сообщением следующего вида.

Параметр -ErrorAction Stop командлета Write-Error

Я упоминал, что по умолчанию Write-Error не вызывает неустранимую ошибку. Если указать -ErrorAction Stop , то Write-Error создает неустранимую ошибку, которую можно обработать с помощью catch .

Благодарю Ли Дейли за напоминание о том, что -ErrorAction Stop можно использовать таким образом.

Параметр -ErrorAction Stop в командлете

Если указать -ErrorAction Stop в любой расширенной функции или командлете, все инструкции Write-Error будут преобразованы в неустранимые ошибки, которые приводят к остановке выполнения или могут быть обработаны с помощью catch .

Try и Catch

Принцип обработки исключений в PowerShell (и многих других языках) состоит в том, что сначала к разделу кода применяется try , а если происходит ошибка, к нему применяется catch . Приведем краткий пример.

Скрипт catch выполняется только в том случае, если произошла неустранимая ошибка. Если try выполняется правильно, catch пропускается. Можно получить доступ к информации об исключении в блоке catch с помощью переменной $_ .

Try и Finally

Иногда ошибку обрабатывать не требуется, но необходимо выполнить определенный код в зависимости от того, было ли создано исключение. Именно это и делает скрипт finally .

Взгляните на этот пример.

Всякий раз, когда вы открываете ресурс или подключаетесь к нему, его следует закрыть. Если ExecuteNonQuery() вызывает исключение, соединение не закрывается. Вот тот же код в блоке try/finally .

В этом примере соединение закрывается при возникновении ошибки. Оно также закрывается при отсутствии ошибок. При этом всякий раз выполняется скрипт finally .

Так как исключение не перехватывается, оно по-прежнему распространяет в стек вызовов.

Try, catch и finally

Вполне допустимо использовать catch и finally вместе. В большинстве случаев используется либо один, либо другой скрипт, но вам могут встретиться сценарии, в которых используются они оба.

$PSItem

Теперь, когда мы разобрались с основами, можно изучить вопрос подробнее.

В блоке catch существует автоматическая переменная ( $PSItem или $_ ) типа ErrorRecord , содержащая сведения об исключении. Ниже приведен краткий обзор некоторых ключевых свойств.

В этих примерах для создания такого исключения я использовал недопустимый путь в ReadAllText .

PSItem.ToString()

Этот метод позволяет получить максимально понятное сообщение, которое можно использовать при ведении журнала и выводе общего результата. ToString() вызывается автоматически, если в строку помещена переменная $PSItem .

$PSItem.InvocationInfo

Это свойство содержит дополнительные сведения, собираемые PowerShell о функции или скрипте, которые вызвали исключение. Ниже приведено свойство InvocationInfo из примера созданного мною исключения.

Здесь приведены важные сведения: имя ScriptName , строка кода Line и номер строки ScriptLineNumber , из которой инициирован вызов.

$PSItem.ScriptStackTrace

Это свойство показывает порядок вызовов функций, ведущих к коду, в котором создано исключение.

Я выполняю вызовы функций в пределах одного скрипта, но таким же образом можно отслеживать функции при использовании нескольких скриптов.

$PSItem.Exception

Это, собственно, и есть вызванное исключение.

$PSItem.Exception.Message

Это общее сообщение, которое описывает исключение и служит хорошей отправной точкой при устранении неполадок. Для большинства исключений предусмотрены сообщения по умолчанию, но при необходимости их можно настроить по своему усмотрению.

Это еще одно сообщение, возвращаемое при вызове $PSItem.ToString() , если для ErrorRecord не задан другой его вариант.

$PSItem.Exception.InnerException

Исключения могут содержать внутренние исключения. Это часто случается, когда вызываемый код перехватывает одно исключение и вызывает другое. Исходное исключение помещается в новое исключение.

Я вернусь к этому вопросу позже, когда буду рассказывать о повторном вызове исключений.

$PSItem.Exception.StackTrace

Это свойство StackTrace для исключения. Я продемонстрировал принцип работы свойства ScriptStackTrace выше, но это предназначено для вызовов управляемого кода.

Эта трассировка стека выполняется только в случае, если событие вызвано из управляемого кода. Я вызываю функцию .NET Framework напрямую, так что это все, что можно увидеть в этом примере. Как правило, трассировка стека просматривается, чтобы найти место остановки кода и начало системных вызовов.

Работа с исключениями

Для работы с исключениями недостаточно базового синтаксиса и основных свойств.

Перехват типизированных исключений

Исключения можно перехватывать избирательно. Исключения имеют тип, задав который можно перехватить только исключения определенного типа.

Каждый блок catch проверяется на наличие исключения заданного типа, пока не будет найден тот, в котором оно создается. Важно понимать, что исключения могут наследоваться от других исключений. В приведенном выше примере FileNotFoundException наследуется от IOException . Поэтому, если исключение IOException было первым, будет вызвано именно оно. Даже если совпадений несколько, вызывается только один блок catch.

При наличии исключения System.IO.PathTooLongException исключение IOException распознается как совпадение, но при наличии исключения InsufficientMemoryException перехватывать его нечем, поэтому оно распространится по стеку.

Одновременный перехват нескольких типов

С помощью одной инструкции catch можно перехватывать несколько типов исключений одновременно.

Благодарю /u/Sheppard_Ra за предложение добавить этот раздел.

Вызов типизированных исключений

В PowerShell можно вызывать типизированные исключения. Вместо вызова throw со строкой:

используйте ускоритель исключений следующим образом:

Но в таком случае необходимо указать сообщение.

Можно также создать новый экземпляр исключения для вызова. При этом сообщение является необязательным, так как в системе предусмотрены сообщения по умолчанию для всех встроенных исключений.

Если вы не используете PowerShell 5.0 или более поздних версий, необходимо использовать устаревший подход с применением New-Object .

Как упоминалось в предыдущем разделе, используя типизированное исключение, вы (или другие пользователи) можете перехватывать исключения по типу.

Параметр -Exception командлета Write-Error

Эти типизированные исключения можно добавить в Write-Error и при этом перехватывать исключения с помощью catch по их типу. Используйте командлет Write-Error , как показано в следующих примерах.

Теперь исключение можно перехватить следующим образом.

Большой список исключений .NET

В дополнение к этой публикации я (при помощи Сообщество Reddit/r/PowerShell) составил основной список, который содержит сотни исключений .NET.

Для начала я ищу в этом списке исключения, которые хорошо подходят для моей ситуации. Следует попытаться использовать исключения в базовом пространстве имен System .

Исключения как объекты

При использовании большого числа типизированных исключений следует помнить, что они являются объектами. Различные исключения имеют разные конструкторы и свойства. В документации FileNotFoundException для System.IO.FileNotFoundException указано, что для этого исключения можно передать сообщение и путь к файлу.

У него есть свойство FileName , которое предоставляет путь к этому файлу.

Сведения о других конструкторах и свойствах объектов см. в документации по Документация по .NET.

Повторный вызов исключения

Если блок catch используется только для вызова того же исключения с помощью throw , перехватывать его с помощью catch не стоит. Перехватывать с помощью catch следует только исключение, которое планируется обработать или использовать для выполнения какого-либо действия.

Бывают случаи, когда необходимо выполнить действие с исключением, но при этом вызывать его повторно, чтобы его можно было обработать на более низком уровне. Мы можем написать сообщение или записать проблему в журнал ближе к месту обнаружения, а обработать эту проблему на другом уровне стека.

Интересно, что throw можно вызвать из catch , и тогда текущее исключение будет вызвано повторно.

Исключение создается повторно, чтобы сохранить исходные сведения о выполнении, например исходный скрипт и номер строки. Если на этом этапе вызывается новое исключение, оно скрывает первоначальное место его возникновения.

Повторный вызов нового исключения

Если вы перехватили исключение, но хотите вызвать другое, следует вложить исходное исключение в новое. Это позволяет объекту на более низком уровне стека получить к нему доступ как к $PSItem.Exception.InnerException .

$PSCmdlet.ThrowTerminatingError()

Единственное, что мне не нравится в использовании throw для необработанных исключений, заключается в том, что в качестве причины ошибки в сообщении об ошибке указывается инструкция throw и номер проблемной строки.

Если сообщение об ошибке сообщает о том, что скрипт работает неправильно из-за вызова throw в строке 31, оно не подходит для отображения пользователям скрипта. Оно не сообщает им ничего полезного.

Декстер Дхами отметил, что для устранения этой проблемы я могу использовать ThrowTerminatingError() .

Если предположить, что метод ThrowTerminatingError() вызван внутри функции с именем Get-Resource , сообщение об ошибке будет таким, как показано ниже.

Вы заметили, что в качестве источника проблемы в нем указана функция Get-Resource ? Теперь пользователь узнает что-то полезное.

Так как значением $PSItem является ErrorRecord , можно таким же образом использовать ThrowTerminatingError для повторного вызова.

При этом источник ошибки изменится на командлет, а внутренние данные о функции будут скрыты от его пользователей.

Try как источник неустранимой ошибки

Кирк Манро указывает, что некоторые исключения являются неустранимыми ошибками только при выполнении внутри блока try/catch . В этом предоставленном им примере исключение во время выполнения вызывается вследствие деления на ноль.

Вызовем его теперь следующим образом, чтобы код содержал ошибку, но при этом выводилось сообщение.

Однако если поместить этот же код в try/catch , то происходит нечто иное.

Ошибка становится неустранимой, а первое сообщение не выводится. Не нравится мне в этом то, что при наличии такого кода в функции поведение становится другим, если использовать try/catch .

Сам я не сталкивался с такой проблемой, но это крайний случай, о котором следует помнить.

Метод $PSCmdlet.ThrowTerminatingError() в try/catch

Одна из особенностей $PSCmdlet.ThrowTerminatingError() заключается в том, что в командлете этот метод вызывает неустранимую ошибку, но после выхода из него ошибка становится устранимой. Из-за этого тому, кто вызывает функцию, приходится решать, как следует обрабатывать такую ошибку. В этом случае можно превратить ее снова в неустранимую ошибку с помощью -ErrorAction Stop или воспользоваться вызовом из try<. >catch <. >.

Шаблоны общих функций

В одной из последних бесед с Кирком Манро мы говорили о том, что он помещает каждый блок begin , process и end во всех своих расширенных функциях в блок try<. >catch <. >. В этих универсальных блоках catch у него есть одна строка с методом $PSCmdlet.ThrowTerminatingError($PSItem) для обработки всех исключений, вызываемых его функциями.

Поскольку в его функциях все находится в операторе try , весь код работает единообразно. Это также позволяет выводить для пользователя понятные сообщения об ошибках, в которых скрыты данные о внутреннем коде.

Ключевое слово trap

Я уделил много внимания особенностям блока try/catch . Однако прежде чем закрывать эту тему, нужно упомянуть об одной устаревшей функции.

Ключевое слово trap помещается в скрипт или функцию для перехвата всех исключений, возникающих в соответствующей области. При возникновении исключения выполняется код в ловушке trap , а затем продолжается выполнение стандартного кода. Если происходит несколько исключений, ловушка вызывается снова и снова.

Я лично никогда не применял этот подход. Однако, судя по скриптам администраторов и контроллеров, которые заносят в журнал абсолютно все исключения, а затем продолжают выполнение, могу сказать, что в нем есть своя польза.

Заключительное слово

Добавление соответствующей обработки исключений в скрипты не только делает эти скрипты более стабильными, но и упрощает устранение таких исключений.

Я уделил так много внимания throw , так как это основное понятие, которым мы оперируем при обсуждении обработки исключений. В PowerShell также предоставляется командлет Write-Error , справляющийся со всеми ситуациями, в которых следовало бы использовать throw . Так что изложенное в этой статье вовсе не означает, что вам обязательно необходимо использовать throw .

Теперь, когда я подробно рассказал об обработке исключений, я собираюсь заняться вопросом использования Write-Error -Stop для создания ошибок в коде. Я также собираюсь воспользоваться советом Кирка и перейти на использование ThrowTerminatingError в качестве обработчика исключений для каждой функции.

Источник

You need to understand how PowerShell handles errors and exceptions if you wish to create a script that behaves as you expect. It’s a fact of life that on occasions your PowerShell scripts will throw errors.

No one writes perfect code or can account for the slew of environmental changes that may be going on to write a PowerShell script that executes correctly 100% of the time.

The first thing you’ll need to realize when working with errors in PowerShell is that there’s not just one kind of «error,» there are two: terminating and non-terminating errors. You will undoubtedly come across both.

Non-terminating errors

Non-terminating errors are still «errors» in PowerShell but not quite as severe as terminating ones. Non-terminating errors aren’t as serious because they do not halt script execution. Moreover, you can silence them, unlike terminating errors. You can create non-terminating errors with the Write-Error cmdlet. This cmdlet writes text to the error stream.

You can also manipulate non-terminating errors with the common ErrorAction and ErrorVariable parameters on all cmdlets and advanced functions. For example, if you’ve created an advanced function that contains a Write-Error reference, you can temporarily silence this as shown below.

function Do-Thing {
    [CmdletBinding()]
    param()
    Write-Error 'An error occurred'
}
## Execute on its own
PS> Do-Thing

I can silence this error with the built-in ErrorAction parameter and choose to SilentlyContinue as well.

Do-Thing -ErrorAction SilentlyContinue

You see when executing the above code, it will return nothing.

Terminating errors

Terminating errors are those that halt script execution. These errors are meant to be more serious than non-terminating errors. The most common way to create a terminating error is to use the throw command. The throw command «throws» an exception, which is essentially the same thing as a terminating error. For example, the below code will not return anything. You might expect that it would return «the string variable did not equal foo» because I did not include an else condition. However, it does not, because throw halts execution.

$string = 'foo'
if ($string -eq 'foo') {
    throw 'string equaled foo when it was not supposed to'
}
Write-Output 'the string variable did not equal foo'

Unlike with non-terminating errors, the ErrorAction or ErrorVariable parameters cannot handle terminating errors. Only try/catch blocks can handle them. You can use this pair of blocks together to form a net of sorts around a piece of code. When a try block throws a terminating error, it will immediately halt execution of any further code inside of that try block and begin execution of the code inside of the catch block. The example below shows this behavior.

try {
    $string = 'foo'
    if ($string -eq 'foo') {
        throw 'string equaled foo when it was not supposed to'
    }
    Write-Output 'the string variable did not equal foo'
} catch {
    Write-Output 'we ended up in the catch block'
}

When run, the code returns the string «we ended up in the catch block.» Without try/catch blocks, the code will simply write out a terminating error (exception) to the host as the first example shows. Here, we did not see any red error text but just the «we ended up in the catch block» string. This is how the code handles terminating errors.

Turning non-terminating errors into terminating errors

Sometimes you have no control over which errors are terminating vs. non-terminating. And you may want to ensure that when a script runs, it always stops for every error regardless of the type. To consider all errors as terminating errors, you can manipulate the $ErrorActionPreference automatic variable. This variable controls what happens when a non-terminating error occurs. The default setting for this variable is Continue. However, if you want to ensure every non-terminating error halts script execution just like a terminating error, you can change this to Stop as the example below shows.

$ErrorActionPreference = 'Stop'

$string = 'foo'
if ($string -eq 'foo') {
    Write-Error 'string equaled foo when it was not supposed to'
}
Write-Output 'we are past the error here'

By executing the above code, you’ll see that it returns both the error and the output. This is because Write-Error returns a non-terminating error or sends a string to the error stream. However, when setting $ErrorActionPreference to Stop, you’ll see that the code never returns «we are past the error here» because it halts script execution.

Subscribe to 4sysops newsletter!

Wrap-up

Understanding how errors occur and how to invoke them at appropriate times is an important skill to master in PowerShell. Proper error handling can make the difference between a script that blows up and a well-structured one that is much more robust.

There are a few different kinds of errors in PowerShell, and it can be a little bit of a minefield on occasion.
There are always two sides to consider, too: how you write code that creates errors, and how you handle those errors in your own code.
Let’s have a look at some ways to effectively utilise the different kinds of errors you can work with in PowerShell, and how to handle them.

Different Types of Errors

Terminating Errors

Terminating errors are mostly an «exactly what it sounds like» package in general use.
They’re very similar to C#’s Exception system, although PowerShell uses ErrorRecord as its base error object.
Their common characteristics are as follows:

• Trigger try/catch blocks
• Return control to the caller, along with the exception, if they’re not handled using a try/catch block.

There are a couple different ways to get a terminating error in PowerShell, and each has its own small differences that make them more useful in a tricky situation.

Throw

First is your typical throw statement, which simply takes an exception message as its only input.

throw "Something went wrong"

throw creates an exception and an ErrorRecord (PowerShell’s more detailed version of an exception) in a single, simple statement, and wraps them together.
Its exceptions display the entered error message, a generic RuntimeException, and the errorID matches the entered exception message.
The line number and position displayed from a throw error message point back to the throw statement itself.
throw exceptions are affected by -ErrorAction parameters of their advanced functions.

throw should generally be used for simple runtime errors, where you need to halt execution, but typically only if you plan to catch it yourself later.
There is no guarantee a user will not elect to simply ignore your error with -ErrorAction Ignore and continue with their lives if it is passed up from your functions.

ThrowTerminatingError()

Next, we have a more advanced version of the throw statement. ThrowTerminatingError() is a method that comes directly from PowerShell’s PSCmdlet .NET class.
It is accessible only in advanced functions via the $PSCmdlet variable.

using namespace System.Management.Automation;
$Exception = [Exception]::new("error message")
$ErrorRecord = [System.Management.Automation.ErrorRecord]::new(
    $Exception,
    "errorID",
    [System.Management.Automation.ErrorCategory]::NotSpecified,
    $TargetObject # usually the object that triggered the error, if possible
)
$PSCmdlet.ThrowTerminatingError($ErrorRecord)

As you can see, these require a little more manual labor.
You can bypass some of this by deliberately using the throw statement and then later catching the generated ErrorRecord to pass it into the ThrowTerminatingError() method directly.
This saves a decent amount of the code involved, and offloads the work to PowerShell’s engine instead.
However, this will still involve essentially the same work being done, without necessarily giving you a chance to specify the finer details of the error record.

ThrowTerminatingError() creates a terminating error (as the name implies), however unlike throw its errors are unaffected by -ErrorAction parameters applied to the parent function.
It will also never reveal the code around it.
When you see an error thrown via this method, it will always display only the line where the command was called, never the code within the command that actually threw the error.

ThrowTerminatingError() should generally be used for serious errors, where continuing to process in spite of the error may lead to corrupted data, and you want any specified -ErrorAction parameter to be ignored.

Non-Terminating Errors

Non-terminating errors are PowerShell’s concession demanded by the fact that it is a shell that supports pipelines.
Not all errors warrant halting all ongoing actions, and only need to inform the user that a minor error occurred, but continue processing the remainder of the items.

Unlike terminating errors, non-terminating errors:

• Do not trigger try/catch blocks.
• Do not affect the script’s control flow.

Write-Error

Write-Error is a bit like the non-terminating version of throw, albeit more versatile.
It too creates a complete ErrorRecord, which has a NotSpecified category and some predefined Exception and ErrorCode properties that both refer to Write-Error.

This is a very simple and effective way to write a non-terminating error, but it is somewhat limited in its use.
While you can override its predefined default exception type, error code, and essentially everything about the generated ErrorRecord, Write-Error is similar to throw in that it too points directly back to the line where Write-Error itself was called.
This can often make the error display very unclear, which is rarely a good thing.

Write-Error is a great way to emit straightforward, non-terminating errors, but its tendency to muddy the error display makes it difficult to recommend for any specific uses.
However, as it is itself a cmdlet, it is also possible to make it create terminating errors as well, by using the -ErrorAction Stop parameter argument.

WriteError()

WriteError() is the non-terminating cousin of ThrowTerminatingError(), and is also available as one of the members of the automatic $PSCmdlet variable in advanced functions.
It behaves similarly to its cousin in that it too hides the code that implements it and instead points back to the point where its parent function was called as the source point of the error.
This is often preferable when dealing with expected errors such as garbled input or arguments, or simple «could not find the requested item» errors in some cases.

$Exception = [Exception]::new("error message")
$ErrorRecord = [System.Management.Automation.ErrorRecord]::new(
    $Exception,
    "errorID",
    [System.Management.Automation.ErrorCategory]::NotSpecified,
    $TargetObject # usually the object that triggered the error, if possible
)
$PSCmdlet.WriteError($ErrorRecord)

Emit Errors Responsibly

There are no true hard-and-fast rules here.
If one solution works especially well for what you happen to be putting together, don’t let me deter you.
However, I would urge you to consider both the impact to your users as well as yourself or your team before selecting a single-minded approach to error creation.
Not all error scenarios are created equal, so it’s very rare that I would recommend using one type over all others.

WriteError() is generally preferred over its cmdlet form Write-Error, because it offers more control over how you emit the error.
Both tend to be used for expected and technically avoidable errors that occur, but the $PSCmdlet method has the additional benefit of not divulging implementation details unnecessarily.

If you expect the error to occur sometimes, I would generally advise using WriteError() unless the error’s presence significantly impairs your cmdlet’s ability to process the rest of its input, in which case I would use ThrowTerminatingError().

throw is generally nice as a quick way to trigger a try/catch block in your own code, but I would also recommend using it for: those truly unexpected errors, that last-ditch catch clause after several more specific catch blocks have been put in place and bypassed.
At this point, a final ending catch block that simply triggers a throw $_ call to re-throw the caught exception into the parent scope and quickly pass execution back to the caller.
It’s a very quick and very effective way to have the error be noticed, but should usually be kept internal to the function more than anything else, except in the last scenario mentioned.
Use of Write-Error -ErrorAction Stop may potentially also be substituted for that purpose if you personally prefer.

Thanks for reading!