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 是适用于 x64 的 Windows 10 企业版（内部版本 18312）上运行的 PowerShell 5.1。
  • 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 是在 Ubuntu 18.04 上运行的 PowerShell 6.2.0。

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 专业版 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.jsonPSScriptAnalyzer 会在默认配置文件目录中搜索。
  • 文件的绝对路径（如 D:\PowerShellProfiles\TargetMachine.json）。

默认配置文件目录位于PSScriptAnalyzer模块 $PSScriptRoot/compatibility_profiles 下方（ $PSScriptRoot 此处指的是包含的 PSScriptAnalyzer.psd1目录）。

兼容性分析会将你使用的每个命令与目标配置文件和联合配置文件进行比较。 union配置文件包含配置文件目录中任何配置文件中可用的所有命令。

如果命令不在union配置文件中，规则会假设它是本地的，从而忽略它。 如果命令在union配置文件中存在但目标配置文件中缺失，规则会标记该命令与该目标不兼容。

例

以下示例假设 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
}

合规的

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'
            )
        }
    }
}

参数

启用

该参数控制 ScriptAnalyzer 是否会根据该规则检查代码。 它接受一个布尔值。 要启用该规则，将该参数设为 $true。 默认值为 $false。

目标配置文件

该参数指定了用于检查兼容性的平台配置文件列表。 此字段接受字符串数组。 每个值可以是平台名称、文件名或配置文件文件的绝对路径。 默认值为 @()。

配置文件DirPath

该参数控制 ScriptAnalyzer 通过名称搜索配置文件并生成联合配置文件的目录。 它接受包含绝对路径的字符串。 默认位置是 compatibility_profiles PSScriptAnalyzer模块中的目录。

忽略命令

该参数指定了排除兼容性检查的命令。 它接受一系列命令名字符串。 默认值为 @()。

抑制

与其他规则一样，你可以通过在脚本块的块中添加抑制属性 param 来抑制命令兼容性诊断。

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

你也可以针对特定命令抑制该规则：

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

你也可以针对特定参数进行抑制：

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