Invoke-ScriptAnalyzer
Вычисляет скрипт или модуль на основе выбранных правил рекомендаций
Синтаксис
Path_SuppressedOnly (По умолчанию)
Invoke-ScriptAnalyzer
[-Path] <string>
[-CustomRulePath <string[]>]
[-RecurseCustomRulePath]
[-IncludeDefaultRules]
[-ExcludeRule <string[]>]
[-IncludeRule <string[]>]
[-Severity <string[]>]
[-Recurse]
[-SuppressedOnly]
[-Fix]
[-EnableExit]
[-Settings <Object>]
[-SaveDscDependency]
[-ReportSummary]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Path_IncludeSuppressed
Invoke-ScriptAnalyzer
[-Path] <string>
-IncludeSuppressed
[-CustomRulePath <string[]>]
[-RecurseCustomRulePath]
[-IncludeDefaultRules]
[-ExcludeRule <string[]>]
[-IncludeRule <string[]>]
[-Severity <string[]>]
[-Recurse]
[-Fix]
[-EnableExit]
[-Settings <Object>]
[-SaveDscDependency]
[-ReportSummary]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
ScriptDefinition_IncludeSuppressed
Invoke-ScriptAnalyzer
[-ScriptDefinition] <string>
-IncludeSuppressed
[-CustomRulePath <string[]>]
[-RecurseCustomRulePath]
[-IncludeDefaultRules]
[-ExcludeRule <string[]>]
[-IncludeRule <string[]>]
[-Severity <string[]>]
[-Recurse]
[-EnableExit]
[-Settings <Object>]
[-SaveDscDependency]
[-ReportSummary]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
ScriptDefinition_SuppressedOnly
Invoke-ScriptAnalyzer
[-ScriptDefinition] <string>
[-CustomRulePath <string[]>]
[-RecurseCustomRulePath]
[-IncludeDefaultRules]
[-ExcludeRule <string[]>]
[-IncludeRule <string[]>]
[-Severity <string[]>]
[-Recurse]
[-SuppressedOnly]
[-EnableExit]
[-Settings <Object>]
[-SaveDscDependency]
[-ReportSummary]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Описание
Invoke-ScriptAnalyzer оценивает скрипты или файлы модулей (.ps1, .psm1и файлы .psd1) на основе коллекции правил рекомендаций и возвращает объекты, представляющие нарушения правил. Она также включает специальные правила для анализа ресурсов DSC.
Invoke-ScriptAnalyzer поставляется с набором встроенных правил. По умолчанию он использует все правила. Можно использовать параметры IncludeRule и ExcludeRule, чтобы выбрать нужные правила. Вы можете использовать командлет Get-ScriptAnalyzerRule для проверки и выбора правил, которые необходимо включить или исключить из оценки.
Вы также можете использовать настраиваемые правила, которые вы пишете в скриптах PowerShell, или компилировать в сборках с помощью C#. Пользовательские правила также можно выбрать с помощью параметров IncludeRule и ExcludeRu le.
Вы также можете включить правило в анализ, но отключить выходные данные этого правила для выбранных функций или скриптов. Эту функцию следует использовать только при необходимости. Чтобы получить правила, которые были отключены, выполните Invoke-ScriptAnalyzer с параметром SuppressedOnly.
Для использования в системах CI EnableExit завершает оболочку с кодом выхода, равным количеству записей об ошибках.
Примеры
ПРИМЕР 1. Выполнение всех правил анализатора скриптов в скрипте
Invoke-ScriptAnalyzer -Path C:\Scripts\Get-LogData.ps1
ПРИМЕР 2. Выполнение всех правил анализатора скриптов для всех файлов в каталоге modules
В этом примере выполняются все правила анализатора скриптов для всех .ps1 и .psm1 файлов в каталоге Modules пользователя и его подкаталогах.
Invoke-ScriptAnalyzer -Path $home\Documents\WindowsPowerShell\Modules -Recurse
ПРИМЕР 3. Выполнение одного правила в модуле
В этом примере выполняется только правило PSAvoidUsingPositionalParameters для файлов в папке модуля PSDiagnostics. Для поиска всех экземпляров определенного нарушения правила можно использовать следующую команду.
Invoke-ScriptAnalyzer -Path C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDiagnostics -IncludeRule PSAvoidUsingPositionalParameters
ПРИМЕР 4. Выполнение всех правил, кроме двух в модулях
В этом примере выполняются все правила, за исключением PSAvoidUsingCmdletAliases и PSAvoidUsingInternalURLs на .ps1 и .psm1 файлах в каталоге MyModules и в его подкаталогах.
Invoke-ScriptAnalyzer -Path C:\ps-test\MyModule -Recurse -ExcludeRule PSAvoidUsingCmdletAliases, PSAvoidUsingInternalURLs
ПРИМЕР 5. Запуск анализатора скриптов с пользовательскими правилами
В этом примере выполняется анализатор скриптов на Test-Script.ps1 со стандартными правилами и правилами в пути C:\CommunityAnalyzerRules.
Invoke-ScriptAnalyzer -Path D:\test_scripts\Test-Script.ps1 -CustomRulePath C:\CommunityAnalyzerRules -IncludeDefaultRules
ПРИМЕР 6. Выполните только правила, которые являются серьезностью ошибок и имеют имя источника PSDSC
$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse
ПРИМЕР 7. Подавление нарушений правил
В этом примере показано, как подавлять отчеты о нарушениях правил в функции и как обнаруживать нарушения правил, которые подавляются.
В примере используется атрибут SuppressMessageAttribute для подавления правил PSUseSingularNouns и правил PSAvoidUsingCmdletAliases для функции Get-Widgets в скрипте Get-Widgets.ps1.
Этот атрибут можно использовать для подавления правила модуля, скрипта, класса, функции, параметра или строки.
Первая команда запускает анализатор скриптов в файле скрипта, содержаемом функцию. Выходные данные сообщают о нарушении правила. Несмотря на нарушение дополнительных правил, ни один из подавляемых правил не сообщается.
function Get-Widgets
{
[CmdletBinding()]
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "")]
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingCmdletAliases", "", Justification="Resolution in progress.")]
Param()
dir $pshome
...
}
Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1
RuleName Severity FileName Line Message
-------- -------- -------- ---- -------
PSProvideCommentHelp Information ManageProf 14 The cmdlet 'Get-Widget' does not have a help comment.
iles.psm1
Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 -SuppressedOnly
Rule Name Severity File Name Line Justification
--------- -------- --------- ---- -------------
PSAvoidUsingCmdletAliases Warning ManageProf 21 Resolution in progress.
iles.psm1
PSUseSingularNouns Warning ManageProf 14
iles.psm1
Вторая команда использует параметр SuppressedOnly для сообщения о нарушениях правил, которые подавляют файл скрипта.
ПРИМЕР 8. Анализ файлов скриптов с помощью определения профиля
В этом примере мы создадим профиль анализатора скриптов и сохраните его в файле ScriptAnalyzerProfile.txt в текущем каталоге. Мы запускаем Invoke-ScriptAnalyzer в файлах модулей BitLocker. Значение параметра профиля — путь к профилю анализатора скриптов.
# In .\ScriptAnalyzerProfile.txt
@{
Severity = @('Error', 'Warning')
IncludeRules = 'PSAvoid*'
ExcludeRules = '*WriteHost'
}
Invoke-ScriptAnalyzer -Path $pshome\Modules\BitLocker -Settings .\ScriptAnalyzerProfile.txt
Если в команду Invoke-ScriptAnalyzer включен конфликтующий параметр, например -Severity Error, командлет использует значение профиля и игнорирует этот параметр.
ПРИМЕР 9. Анализ скрипта, хранящегося в виде строки
В этом примере используется параметр scriptDefinition для анализа функции в командной строке. Строка функции заключена в кавычки.
Invoke-ScriptAnalyzer -ScriptDefinition "function Get-Widgets {Write-Host 'Hello'}"
RuleName Severity FileName Line Message
-------- -------- -------- ---- -------
PSAvoidUsingWriteHost Warning 1 Script
because
there i
suppres
Write-O
PSUseSingularNouns Warning 1 The cmd
noun sh
При использовании параметра scriptDefinition свойство FileName объекта DiagnosticRecord$null.
Параметры
-Confirm
Запрашивает подтверждение перед запуском cmdlet.
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
| Aliases: | cf |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-CustomRulePath
Введите путь к файлу, который определяет правила или каталог, содержащий файлы, определяющие правила.
Поддерживаются подстановочные знаки. При указании CustomRulePath для анализа используются только пользовательские правила, найденные в указанных путях. Если Invoke-ScriptAnalyzer не удается найти правила в нем, он выполняет стандартные правила без уведомления.
Чтобы добавить правила, определенные в подкаталогах пути, используйте параметр RecurseCustomRulePath. Чтобы включить встроенные правила, добавьте параметр IncludeDefaultRules.
Свойства параметров
| Тип: | String[] |
| Default value: | None |
| Поддерживаются подстановочные знаки: | True |
| DontShow: | False |
| Aliases: | CustomizedRulePath (Путь к правилам) |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-EnableExit
По завершении анализа этот параметр завершает сеансы PowerShell и возвращает код выхода, равный количеству записей ошибок. Это может быть полезно в конвейере непрерывной интеграции (CI).
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-ExcludeRule
Окупит указанные правила из теста анализатора скриптов. Поддерживаются подстановочные знаки.
Введите разделенный запятыми список имен правил, переменную, содержащую имена правил, или команду, которая получает имена правил. Вы также можете указать список исключенных правил в файле профиля анализатора скриптов. Вы можете исключить стандартные правила и правила в пользовательском пути правила.
При исключении правила правило не выполняется ни на одном из файлов в пути. Чтобы исключить правило в определенной строке, параметре, функции, скрипте или классе, настройте параметр Path или отключите правило. Сведения о подавлении правила см. в примерах.
Если правило указано в коллекциях ExcludeRule и IncludeRule, это правило исключается.
Свойства параметров
| Тип: | String[] |
| Default value: | All rules are included. |
| Поддерживаются подстановочные знаки: | True |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-Fix
Исправлены некоторые предупреждения, содержащие исправление в DiagnosticRecord.
При использовании исправленияInvoke-ScriptAnalyzer применяет исправления перед выполнением анализа. При использовании этого параметра убедитесь, что у вас есть резервная копия файлов. Он пытается сохранить кодировку файла, но по-прежнему есть некоторые случаи, когда кодировка может измениться.
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
Path_SuppressedOnly
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
Path_IncludeSuppressed
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-IncludeDefaultRules
Вызов правил по умолчанию вместе с пользовательскими правилами.
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-IncludeRule
Выполняет только указанные правила в тесте анализатора скриптов. По умолчанию PSScriptAnalyzer выполняет все правила.
Введите разделенный запятыми список имен правил, переменную, содержащую имена правил, или команду, которая получает имена правил. Поддерживаются подстановочные знаки. Вы также можете указать имена правил в файле профиля анализатора скриптов.
При использовании параметра CustomedRulePath этот параметр можно использовать для включения стандартных правил и правил в путь настраиваемых правил.
Если правило указано в коллекциях ExcludeRule и IncludeRule, это правило исключается.
Параметр серьезности имеет приоритет над IncludeRule. Например, еслиErrorErrorсерьезности Error, нельзя использовать IncludeRule для включения правила .
Свойства параметров
| Тип: | String[] |
| Default value: | All rules are included. |
| Поддерживаются подстановочные знаки: | True |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-IncludeSuppressed
Включите подавляемую диагностику в выходные данные.
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
Path_IncludeSuppressed
| Position: | Named |
| Обязательно: | True |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
ScriptDefinition_IncludeSuppressed
| Position: | Named |
| Обязательно: | True |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-Path
Указывает путь к скриптам или модулям, которые необходимо проанализировать. Поддерживаются подстановочные знаки.
Введите путь к скрипту (.ps1) или файлу модуля (.psm1) или в каталог, содержащий скрипты или модули. Если каталог содержит другие типы файлов, они игнорируются.
Чтобы проанализировать файлы, которые не находятся в корневом каталоге указанного пути, используйте подстановочный знак (C:\Modules\MyModule\*) или параметр Recurse.
Свойства параметров
| Тип: | String |
| Default value: | None |
| Поддерживаются подстановочные знаки: | True |
| DontShow: | False |
| Aliases: | PSPath |
Наборы параметров
Path_SuppressedOnly
| Position: | 0 |
| Обязательно: | True |
| Значение из конвейера: | True |
| Значение из конвейера по имени свойства: | True |
| Значение из оставшихся аргументов: | False |
Path_IncludeSuppressed
| Position: | 0 |
| Обязательно: | True |
| Значение из конвейера: | True |
| Значение из конвейера по имени свойства: | True |
| Значение из оставшихся аргументов: | False |
-Recurse
Выполняет анализатор скриптов для файлов в каталоге пути и всех подкаталогов рекурсивно.
Рекурс применяется только к значению параметра Path. Чтобы выполнить поиск CustomRulePath рекурсивно, используйте параметр RecurseCustomRulePath.
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-RecurseCustomRulePath
Добавляет правила, определенные в подкаталогах расположения CustomRulePath. По умолчанию Invoke-ScriptAnalyzer использует только пользовательские правила, определенные в указанном файле или каталоге. Чтобы включить встроенные правила, используйте параметр IncludeDefaultRules.
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-ReportSummary
Напишите сводку о нарушениях, обнаруженных на узле.
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-SaveDscDependency
Разрешение зависимостей ресурсов DSC.
При запуске Invoke-ScriptAnalyzer с этим параметром выполняется поиск экземпляров Import-DSCResource -ModuleName <somemodule>. Если <somemodule> не удается найти, выполнив поиск $env:PSModulePath, Invoke-ScriptAnalyzer возвращает ошибку синтаксического анализа. Эта ошибка вызвана тем, что средство синтаксического анализа PowerShell не сможет найти символ для <somemodule>.
Если Invoke-ScriptAnalyzer найти модуль в коллекции PowerShell, он скачивает отсутствующий модуль в временный путь. Затем временный путь добавляется в $env:PSModulePath для длительности сканирования.
Временное расположение можно найти в $LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir.
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-ScriptDefinition
Выполняет анализ команд, функций или выражений в строке. Эту функцию можно использовать для анализа операторов, выражений и функций, независимо от контекста скрипта.
Свойства параметров
| Тип: | String |
| Default value: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
ScriptDefinition_IncludeSuppressed
| Position: | 0 |
| Обязательно: | True |
| Значение из конвейера: | True |
| Значение из конвейера по имени свойства: | True |
| Значение из оставшихся аргументов: | False |
ScriptDefinition_SuppressedOnly
| Position: | 0 |
| Обязательно: | True |
| Значение из конвейера: | True |
| Значение из конвейера по имени свойства: | True |
| Значение из оставшихся аргументов: | False |
-Settings
Путь к файлу, содержаму определяемый пользователем профиль или хэш-объект, содержащий параметры scriptAnalyzer.
Выполняется Invoke-ScriptAnalyzer с параметрами и значениями, указанными в файле или хэш-таблицы.
Если путь или содержимое файла или хэш-таблицы недопустимы, он игнорируется. Параметры и значения в профиле имеют приоритет над тем же параметром и значениями, указанными в командной строке.
Файл профиля анализатора скриптов — это текстовый файл, содержащий хэш-таблицу с одним или несколькими из следующих ключей:
- CustomRulePath
- ExcludeRules
- IncludeDefaultRules
- IncludeRules
- RecurseCustomRulePath
- Правила
- Степень серьезности
Ключи и значения в профиле интерпретируются так, как если бы они были стандартными параметрами и значениями Invoke-ScriptAnalyzer, похожими на сплочение. Дополнительные сведения см. в about_Splatting.
Свойства параметров
| Тип: | Object |
| Default value: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
| Aliases: | Профиль |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-Severity
После выполнения анализатора скриптов со всеми правилами этот параметр выбирает нарушения правил с указанным уровнем серьезности.
Допустимые значения:
- Ошибка
- Предупреждение
- Сведения.
Можно указать одно или несколько значений серьезности.
Параметр фильтрует нарушения правил только после выполнения всех правил. Чтобы эффективно фильтровать правила, используйте Get-ScriptAnalyzerRule для выбора правил, которые требуется выполнить.
Параметр серьезности имеет приоритет над IncludeRule. Например, еслиErrorErrorсерьезности Error, нельзя использовать IncludeRule для включения правила .
Свойства параметров
| Тип: | String[] |
| Default value: | All rule violations |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-SuppressedOnly
Возвращает нарушения только для правил, которые подавляются.
Возвращает объект SuppressedRecord (Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord).
Чтобы отключить правило, используйте SuppressMessageAttribute. Дополнительные сведения см. в примерах.
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
Path_SuppressedOnly
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
ScriptDefinition_SuppressedOnly
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-WhatIf
Показывает, что произойдет, если командлет будет запущен. Командлет не запускается.
Свойства параметров
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
| Aliases: | wi |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
CommonParameters
Этот командлет поддерживает общие параметры: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction и -WarningVariable. Дополнительные сведения см. в разделе about_CommonParameters.
Входные данные
None
Входные данные в этот командлет невозможно передать.
Выходные данные
Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord
По умолчанию Invoke-ScriptAnalyzer возвращает один объект DiagnosticRecord для каждого нарушения правила.
Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord
Если вы используете параметр SuppressedOnly, Invoke-ScriptAnalyzer вместо этого возвращает объекты SuppressedRecord.