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>：.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_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) 的目录。

兼容性分析比较用于目标配置文件的类型和“联合”配置文件 (包含配置文件 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
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')]