UseCompatibleTypes

Статья
12/12/2024

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

Описание

Это правило определяет типы, которые недоступны (загружены по умолчанию) на целевых платформах 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 Pro	`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), которое будет .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`	Расположение для поиска профилей по имени и использованию для создания профилей объединения	строка: абсолютный путь к новому каталогу профиля	Нет (по умолчанию используется каталог `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'
            )
        }
    }
}

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

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 блока скрипта, как и в других правилах.

[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')]

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

UseCompatibleTypes

Описание

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

Подавление

Обратная связь

Дополнительные ресурсы