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

UseCompatibleTypes

  • Статья

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

Описание

Это правило определяет типы, которые недоступны (загружаются по умолчанию) на целевых платформах 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>: powerShell версии среды выполнения .NET выполняется в (в настоящее 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) для 64-разрядных приложений.
  • 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 Операционная система ID
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 1809 (RS5) win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
6.2 Windows Server 2016 win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows Server 2019 win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10 1809 (RS5) win-4_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Ubuntu 18.04 LTS ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core
7,0 Windows Server 2016 win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core
7,0 Windows Server 2019 win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core
7,0 Windows 10 1809 (RS5) win-4_x64_10.0.17763.0_6.2.4_x64_3.1.2_core
7,0 Ubuntu 18.04 LTS ubuntu_x64_18.04_6.2.4_x64_3.1.2_core

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

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

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

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

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

Анализ совместимости сравнивает тип, используемый как с целевым профилем, так и с профилем union (который содержит все типы, доступные в любом профиле в каталоге профиля). Если тип отсутствует в профиле объединения, предполагается, что он создается локально и игнорируется. В противном случае, если тип присутствует в профиле объединения, но отсутствует в целевом объекте, он считается несовместим с этим целевым объектом.

Параметры конфигурации

Ключ конфигурации Значение Допустимые значения Обязательный Пример
Enable Активирует правило. bool ($true/$false) Нет (по умолчанию: $false) $true
TargetProfiles Список целевых профилей PowerShell string[]: абсолютные пути к файлам профилей или имена профилей в каталоге профилей Нет (по умолчанию: @()) @('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')
ProfileDirPath Расположение для поиска профилей по имени и использования для создания профилей объединения string: абсолютный путь к новому каталогу профиля Нет (по умолчанию используется compatibility_profiles каталог в модуле PSScriptAnalyzer. C:\Users\me\Documents\pssaCompatProfiles
IgnoreTypes Полные имена типов или ускорителей типов для пропуска совместимости в скриптах string[]: имена типов, которые следует игнорировать Нет (по умолчанию: @()) @('System.Collections.ArrayList','string')

Пример конфигурации может выглядеть следующим образом:

@{
    Rules = @{
        PSUseCompatibleTypes = @{
            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 types to not check like this, which will also ignore methods and members on it:
            IgnoreTypes = @(
                'System.IO.Compression.ZipFile'
            )
        }
    }
}

Кроме того, можно указать объект параметров следующим образом:

PS> $settings = @{
      Rules = @{
        PSUseCompatibleTypes = @{
          Enable = $true
          TargetProfiles = @('win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework')
        }
      }
}
PS> Invoke-ScriptAnalyzer -Settings $settings -ScriptDefinition '[System.Management.Automation.SemanticVersion]'1.18.0-rc1''

RuleName                Severity     ScriptName Line  Message
--------                --------     ---------- ----  -------
PSUseCompatibleTypes    Warning                 1     The type 'System.Management.Automation.SemanticVersion' is
                                                      not available by default in PowerShell version
                                                      '5.1.17763.316' on platform 'Microsoft Windows 10 Pro'

Подавление

Диагностика совместимости команд можно подавлять с помощью атрибута в блоке param scriptblock, как и в других правилах.

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

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

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes', 'System.Management.Automation.Security.SystemPolicy')]

А также подавляется только для элементов типа:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands', 'System.Management.Automation.LanguagePrimitives/ConvertTypeNameToPSTypeName')]