Настройка ошибок проверки параметров в PowerShell

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

В прошлом ошибки, которые передавались обратно пользователю, не всегда были очень полезны. Начиная с PowerShell Core и продолжая в PowerShell 7, появилась возможность определять собственное сообщение об ошибке. Вместо использования ошибки по умолчанию, основанной на оформлении параметра, вы можете определить свою собственную. Узнайте, как улучшить свои расширенные функции, чтобы воспользоваться преимуществами этой новой функциональности!

Что такое свойство ErrorMessage?

Возможно, вы уже видели декоратор параметров, такой как ValidateScript, и, если вы его использовали, вы обнаружили, что сообщение об ошибке не всегда было самым описательным. Часто бывает полезно создать собственное сообщение, более точно отражающее, что делает функция и почему у вас может возникнуть ошибка. Три декоратора проверки параметров имеют дополнительное свойство ErrorMessage, доступное им.

Проверить набор
Проверить скрипт
Проверить шаблон

Что на самом деле делает это свойство? Во-первых, давайте посмотрим на старый способ сделать это. В приведенном ниже примере кода мы используем ValidatePattern, чтобы проверить, состоит ли строка из 8 цифр. Если полностью числовая строка не указана, мы получаем ошибку, которую можно считать загадочной и не очень полезной для пользователя вашей функции.

Function Test-ValidatePattern {
    [CmdletBinding()]
    Param (
        [ValidatePattern('^\d{8}$')]
        [String]$Digits
    )

    Process {
      Write-Output $Digits
    }
}

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

Function Test-ValidatePattern {
    [CmdletBinding()]
    Param (
        [ValidatePattern('^\d{8}$',ErrorMessage = "Please use an 8 digit numeric value.")]
        [String]$Digits
    )

    Process {
      Write-Output $Digits
    }
}

Расширение функциональности ErrorMessage

Использование параметра ErrorMessage делает отображение ошибок более удобным для пользователя. Один аспект, который отсутствует, — это значение, которое передается само по себе. В исходном сообщении об ошибке по умолчанию вы, возможно, заметили, что и переданное значение, и сам шаблон регулярного выражения проверки были показаны в сообщении об ошибке. К счастью, используя синтаксис, аналогичный оператору форматирования в PowerShell, мы также можем включить эти значения в наше сообщение об ошибке.

{0} — переданное значение.
{1} — шаблон регулярного выражения.

Function Test-ValidatePattern {
    [CmdletBinding()]
    Param (
        [ValidatePattern('^\d{8}$',ErrorMessage = "{0} is not an 8 digit numeric value fitting the pattern, {1}")]
        [String]$Digits
    )

    Process {
      Write-Output $Digits
    }
}

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

Дополнительные примеры использования ErrorMessage

Чтобы проиллюстрировать, как использование ErrorMessage в декораторах ValidateSet, ValidateScript и ValidatePattern может дополнительно перемещать этапы проверки изнутри ваши блоки begin или process к самим параметрам, давайте взглянем на функцию, использующую все три декоратора параметров.

Function Get-Computer {
  [CmdletBinding()]
  Param (
    [ValidatePattern('^NET-\d{8}$',ErrorMessage = "{0} is not an 8 digit numeric value preceded by 'NET-' fitting the pattern, {1}")]
    [String]$ComputerName,

    [ValidateSet('Desktop','Laptop','Mobile',ErrorMessage = "{0} is not one of the allowed devices, {1}")]
    [String]$Type,

    [ValidateScript({
      $_ -GT (Get-Date)
    },ErrorMessage = "The expiration date, {0}, is not greater than the current date per the following script: {1}")]
    [DateTime]$ExpirationDate
  )

  Process {
    [PSCustomObject]@{
      "ComputerName" = $ComputerName
      "Type"         = $Type
      "ExpireDate"   = $ExpirationDate
    }
  }
}

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

Заключение

Добавление дополнительных функций для декораторов параметров ValidateSet, ValidateScript и ValidatePattern — это большое преимущество для удобства использования расширенных функций PowerShell. Вместо загадочных сообщений об ошибках, которые представляют минимальную ценность для пользователя, запускающего функцию, могут отображаться правильные сообщения об ошибках, которые дают представление о том, что пошло не так. Это перемещает обработку ошибок на более высокий уровень, чем блоки begin или process, что делает код более чистым и лаконичным.

Поскольку эта функция доступна в PowerShell Core и PowerShell 7, вам потребуется более новая версия PowerShell, чтобы воспользоваться преимуществами этой функции. С обновлением также приходят многочисленные преимущества в скорости, безопасности и функциональности. Расширьте свои расширенные функции с помощью этого полезного свойства и облегчите жизнь пользователям ваших функций уже сегодня!