UseCompatibleTypes

發行項
12/15/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 是在Ubuntu18.04上執行的PowerShell 6.2.0。

某些平台隨附於 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 專業版	`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的目錄）。

相容性分析會比較用於目標配置檔和「等位」配置檔的類型（包含 配置檔 dir 中任何 設定檔中所有可用的類型）。如果聯集配置檔中沒有類型，則會假設它是在本機建立並忽略。否則，如果類型存在於聯集配置檔中，但不存在於目標中，則會被視為與該目標不相容。

組態設定

設定金鑰	意義	接受的值	命令的	例
`Enable`	啟動規則	布林（`$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

描述

組態設定

抑制

意見反應

其他資源