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 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 です。

一部のプラットフォームは、構成でターゲットを設定するためにこの方法で名前が付けられた JSON ファイルとして PSScriptAnalyzer にバンドルされています。

既定でバンドルされているプラットフォームは次のとおりです。

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 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など) .json 末尾に追加され、既定のプロファイルディレクトリで検索されます。
既定のプロファイルディレクトリで検索されるファイル名 (my_custom_platform.jsonなど)。
ファイルへの絶対パス (D:\PowerShellProfiles\TargetMachine.jsonなど)。

既定のプロファイルディレクトリは、$PSScriptRoot/PSCompatibilityCollector/profiles の PSScriptAnalzyer モジュールの下にあります (ここで $PSScriptRootPSScriptAnalyzer.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: 新しいプロファイルディレクトリへの絶対パス	いいえ (既定では 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

形容

構成設定

抑制

フィードバック

その他のリソース