UseCompatibleTypes

项目
10/31/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 是适用于 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），它将 .json 添加到末尾，并在默认配置文件目录中搜索。
文件名（如 my_custom_platform.json），将在默认配置文件目录中搜索该文件。
文件的绝对路径（如 D:\PowerShellProfiles\TargetMachine.json）。

默认配置文件目录位于 $PSScriptRoot/PSCompatibilityCollector/profiles PSScriptAnalzyer 模块下（此处 $PSScriptRoot 引用包含 PSScriptAnalyzer.psd1的目录）。

兼容性分析比较了用于目标配置文件和“联合”配置文件的类型（包含配置文件目录中任何配置文件可用的所有类型）。如果联合配置文件中不存在某个类型，则假定在本地创建并忽略该类型。否则，如果联合配置文件中存在某个类型但目标中不存在，则它被视为与该目标不兼容。

配置设置

配置密钥	意义	接受的值	命令的	例
`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：新配置文件 dir 的绝对路径	否（默认为 PSScriptAnalyzer 模块中的 `compatibility_profiles` 目录	`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 块上的属性与其他规则一样取消命令兼容性诊断。

[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

描述

配置设置

抑制

反馈

其他资源