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 Enterprise (ビルド 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 Pro 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)です。 PSScriptAnalyzerは .json を追加し、デフォルトのプロファイルディレクトリで検索します。
  • PSScriptAnalyzerがデフォルトのプロファイルディレクトリで検索するファイル名(例えば my_custom_platform.json)。
  • ファイルへの絶対パス (D:\PowerShellProfiles\TargetMachine.jsonなど)。

デフォルトのプロファイルディレクトリは $PSScriptRoot/compatibility_profiles のPSScriptAnalyzerモジュールの下にあり(ここで $PSScriptRoot は PSScriptAnalyzer.psd1を含むディレクトリを指します)。

互換性分析では、使用する各コマンドをターゲットプロファイルとユニオンプロファイルの両方と比較しています。 ユニオンプロファイルには、プロファイルディレクトリ内の任意のプロファイルで利用可能なすべてのコマンドが含まれています。

もしコマンドがユニオンプロファイルに含まれていなければ、ルールはそれが環境のローカルであるとみなして無視します。 もしコマンドがユニオンプロファイルに含まれていてターゲットプロファイルに欠けている場合、そのルールはそのコマンドをそのターゲットと互換性がないとフラグ付けします。

例

以下の例は TargetProfilesubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core (Ubuntu 18.04、PowerShell 6.2)を含むことを前提としています。

非準拠

function Get-OsInfo {
    $os = Get-WmiObject -Class Win32_OperatingSystem
    return $os.Caption
}

対応

function Get-OsInfo {
    $os = Get-CimInstance -ClassName Win32_OperatingSystem
    return $os.Caption
}

ルールの設定

@{
    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'
            )
        }
    }
}

Parameters

Enable

このパラメータは、ScriptAnalyzerがこのルールに対してコードをチェックするかどうかを制御します。 ブール値も受け入れます。 このルールを有効にするには、このパラメータを $trueに設定します。 既定値は $false です。

ターゲットプロファイル

このパラメータは互換性をチェックするプラットフォームプロファイルのリストを指定します。 文字列の配列を指定できます。 各値はプラットフォーム名、ファイル名、またはプロファイルファイルへの絶対パスのいずれかです。 既定値は @() です。

プロフィールディアパス

このパラメータは、ScriptAnalyzerが名前でプロファイルを検索し、ユニオンプロファイルを生成する際に使うディレクトリを制御します。 絶対パスを含む文字列を受け入れます。 デフォルトの場所はPSScriptAnalyzerモジュールの compatibility_profiles ディレクトリです。

コマンドを無視する

このパラメータは互換性チェックから除外するコマンドを指定します。 コマンド名文字列の配列を受け入れます。 既定値は @() です。

抑制

他のルールと同様に、スクリプトブロックの param ブロックに抑制属性を追加することで、コマンド互換性診断を抑制できます。

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands', '')]

特定のコマンドに対してはルールを抑制することもできます:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'Start-Service')]

特定のパラメータに対して抑制することも可能です:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'Import-Module/FullyQualifiedName')]
  • Last updated on