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 2012R2 | 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_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/compatibility_profiles
, (此处 $PSScriptRoot
引用包含 PSScriptAnalyzer.psd1
) 的目录。
兼容性分析将用于目标配置文件的命令与“联合”配置文件进行比较, (包含配置文件 dir) 中任何 配置文件中可用的所有命令。 如果联合配置文件中不存在命令,则假定该命令是在本地创建并忽略的。 否则,如果命令存在于联合配置文件中,但不存在于目标中,则被视为与该目标不兼容。
配置设置
配置密钥 | 含义 | 接受的值 | 必需 | 示例 |
---|---|---|---|---|
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:新配置文件的绝对路径 | PSScriptAnalyzer 模块中没有默认 compatibility_profiles 目录 ( |
C:\Users\me\Documents\pssaCompatProfiles |
IgnoreCommands |
用于在脚本中忽略 兼容性的命令 | string[]:要忽略的命令的名称 | 无 (默认值: @() ) |
@('Get-ChildItem','Import-Module') |
示例配置可能如下所示:
@{
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'
)
}
}
}
禁止
命令兼容性诊断可以使用脚本块上的 param
属性进行抑制,就像其他规则一样。
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands', '')]
也可以仅针对特定命令禁止显示该规则:
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands', 'Start-Service')]
还仅对参数禁止显示:
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands', 'Import-Module/FullyQualifiedName')]