UseCompatibleCommands

уровень серьезности : предупреждение

Состояние по умолчанию: отключено

Описание

Это правило обнаруживает команды, которые недоступны на вашей целевой платформе PowerShell.

Названия платформ PowerShell используют следующий формат:

<os-name>_<os-arch>_<os-version>_<ps-version>_<ps-arch>_<dotnet-version>_<dotnet-edition>

Где:

  • <os-name>: имя операционной системы PowerShell запущено. В Windows включен номер SKU. В Linux значение — это название дистрибутива.
  • <os-arch>: Архитектура машины, на которой работает операционная система (обычно x64).
  • <os-version>: Версия операционной системы (версия дистрибуции на Linux).
  • <ps-version>: версия PowerShell (из $PSVersionTable.PSVersion).
  • <ps-arch>: архитектура компьютера процесса PowerShell.
  • <dotnet-version>: указанная версия среды выполнения .NET PowerShell запущена (начиная с System.Environment.Version).
  • <dotnet-edition>: среда выполнения .NET работает в PowerShell (в настоящее время framework или core).

Например:

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework — PowerShell 5.1, запущенная в Windows 10 Корпоративная (сборка 18312) для x64.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core — PowerShell 6.1.2, запущенная в той же операционной системе.
  • ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core — PowerShell 6.2.0, запущенная в Ubuntu 18.04.

PSScriptAnalyzer включает некоторые платформенные профили в виде JSON-файлов. Вы можете нацеливаться на эти встроенные профили непосредственно в вашей конфигурации.

Платформы, упакованные по умолчанию, :

Версия PowerShell Операционная система ИДЕНТИФИКАТОР
3.0 Windows Server 2012 win-8_x64_6.2.9200.0_3.0_x64_4.0.30319.42000_framework
4.0 Windows Server 2012 R2 win-8_x64_6.3.9600.0_4.0_x64_4.0.30319.42000_framework
5.1 Windows Server 2016 win-8_x64_10.0.14393.0_5.1.14393.2791_x64_4.0.30319.42000_framework
5.1 Windows Server 2019 win-8_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
5.1 Windows 10 Профессиональная win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
6.2 Ubuntu 18.04 LTS ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10.0.14393 win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10.0.17763 win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10.0.18362 win-4_x64_10.0.18362.0_6.2.4_x64_4.0.30319.42000_core
7.0 Ubuntu 18.04 LTS ubuntu_x64_18.04_7.0.0_x64_3.1.2_core
7.0 Windows 10.0.14393 win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core
7.0 Windows 10.0.17763 win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core
7.0 Windows 10.0.18362 win-4_x64_10.0.18362.0_7.0.0_x64_3.1.2_core

Другие профили можно найти в репозитории GitHub.

Вы также можете создать собственный профиль платформы с помощью модуля PSCompatibilityCollector.

Настройки совместимости принимают список платформ под TargetProfiles. Вы можете указать каждую целевой платформу как:

  • Название платформы (например, ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core). PSScriptAnalyzer добавляет .json и ищет его в каталоге профилей по умолчанию.
  • Имя файла (например, my_custom_platform.json), которое PSScriptAnalyzer ищет в каталоге профилей по умолчанию.
  • Абсолютный путь к файлу (например, D:\PowerShellProfiles\TargetMachine.json).

Каталог профиля по умолчанию находится в модуле PSScriptAnalyzer по адресу $PSScriptRoot/compatibility_profiles (где $PSScriptRoot здесь указано на каталог, содержащий PSScriptAnalyzer.psd1).

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

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

Пример

Следующие примеры предполагают TargetProfiles , что включают ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core (Ubuntu 18.04, PowerShell 6.2).

Несоответствующий

function Get-OsInfo {
    $os = Get-WmiObject -Class Win32_OperatingSystem
    return $os.Caption
}

Compliant

function Get-OsInfo {
    $os = Get-CimInstance -ClassName Win32_OperatingSystem
    return $os.Caption
}

Правило настройки

@{
    Rules = @{
        PSUseCompatibleCommands = @{
            Enable = $true
            TargetProfiles = @(
                'ubuntu_x64_18.04_6.1.3_x64_4.0.30319.42000_core'
                'win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework'
                'MyProfile'
                'another_custom_profile_in_the_profiles_directory.json'
                'D:\My Profiles\profile1.json'
            )
            # You can specify commands to not check like this, which also will ignore its parameters:
            IgnoreCommands = @(
                'Install-Module'
            )
        }
    }
}

Parameters

Enable

Этот параметр контролирует, проверяет ли ScriptAnalyzer код по этому правилу. Он принимает булево значение. Чтобы включить это правило, установите этот параметр на $true. Значение по умолчанию — $false.

TargetProfiles

Этот параметр определяет список профилей платформ для проверки совместимости. Здесь принимается массив строк. Каждое значение может быть названием платформы, именем файла или абсолютным путём к файлу профиля. Значение по умолчанию — @().

ProfileDirPath

Этот параметр управляет каталогом, который ScriptAnalyzer ищет профили по имени и использует для создания объединённого профиля. Он принимает строку, содержащую абсолютный путь. По умолчанию compatibility_profiles находится каталог в модуле PSScriptAnalyzer.

IgnoreCommands

Этот параметр определяет команды, которые исключаются из проверок совместимости. Он принимает массив строк имен команд. Значение по умолчанию — @().

Подавление

Как и с другими правилами, диагностику совместимости команд можно подавить, добавив атрибут подавления в param блок скриптблока.

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands', '')]

Вы также можете подавить это правило для конкретных команд:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'Start-Service')]

Вы также можете подавить его по определённым параметрам:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'Import-Module/FullyQualifiedName')]
  • Last updated on