Поделиться через


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.