UseCompatibleCommands

發行項
12/12/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/compatibility_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`
`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')]

共用方式為

UseCompatibleCommands

描述

組態設定

抑制

意見反應

其他資源