Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tally.wharflab.com/llms.txt

Use this file to discover all available pages before exploring further.

powershell/PSUseCompatibleCommands is a PSScriptAnalyzer diagnostic emitted by tally for PowerShell snippets embedded in Dockerfiles.
PropertyValue
SeverityWarning
CategoryPSScriptAnalyzer
Auto-fixNo

​
Description

This rule identifies commands that are not available on a targeted PowerShell platform.
This page describes upstream PSScriptAnalyzer compatibility profiles. tally runs the analyzer through PowerShell 7 (pwsh); Windows PowerShell 5.1 (powershell.exe) is out of scope as a sidecar host.
A PowerShell platform is identified by a name in the following format: 
`<os-name>`_`<os-arch>`_`<os-version>`_`<ps-version>`_`<ps-arch>`_`<dotnet-version>`_`<dotnet-edition>`
Where:
  • <os-name>: The name of the operating system PowerShell is running on. On Windows, this includes the SKU number. On Linux, this is the name of the distribution.
  • <os-arch>: The machine architecture the operating system is running on (this is usually x64).
  • <os-version>: The self-reported version of the operating system (on Linux, this is the distribution version).
  • <ps-version>: The PowerShell version (from $PSVersionTable.PSVersion).
  • <ps-arch>: The machine architecture of the PowerShell process.
  • <dotnet-version>: The reported version of the .NET runtime PowerShell is running on (from System.Environment.Version).
  • <dotnet-edition>: The .NET runtime flavor PowerShell is running on (currently framework or core).
For example:
  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework is PowerShell 5.1 running on Windows 10 Enterprise (build 18312) for x64.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core is PowerShell 6.1.2 running on the same operating system.
  • ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core is PowerShell 6.2.0 running on Ubuntu 18.04.
Some platforms come bundled with PSScriptAnalyzer as JSON files, named in this way for targeting in your configuration. Platforms bundled by default are:
PowerShell VersionOperating SystemID
3.0Windows Server 2012win-8_x64_6.2.9200.0_3.0_x64_4.0.30319.42000_framework
4.0Windows Server 2012 R2win-8_x64_6.3.9600.0_4.0_x64_4.0.30319.42000_framework
5.1Windows Server 2016win-8_x64_10.0.14393.0_5.1.14393.2791_x64_4.0.30319.42000_framework
5.1Windows Server 2019win-8_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
5.1Windows 10 Prowin-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
6.2Ubuntu 18.04 LTSubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core
6.2Windows 10.0.14393win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core
6.2Windows 10.0.17763win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2Windows 10.0.18362win-4_x64_10.0.18362.0_6.2.4_x64_4.0.30319.42000_core
7.0Ubuntu 18.04 LTSubuntu_x64_18.04_7.0.0_x64_3.1.2_core
7.0Windows 10.0.14393win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core
7.0Windows 10.0.17763win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core
7.0Windows 10.0.18362win-4_x64_10.0.18362.0_7.0.0_x64_3.1.2_core
Other profiles can be found in the GitHub repo. You can also generate your own platform profile using the PSCompatibilityCollector module. The compatibility profile settings takes a list of platforms to target under TargetProfiles. A platform can be specified as:
  • A platform name (like ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), which will have .json added to the end and is searched for in the default profile directory.
  • A filename (like my_custom_platform.json), which will be searched for in the default profile directory.
  • An absolute path to a file (like D:\PowerShellProfiles\TargetMachine.json).
The default profile directory is under the PSScriptAnalyzer module at $PSScriptRoot/compatibility_profiles (where $PSScriptRoot here refers to the directory containing PSScriptAnalyzer.psd1). The compatibility analysis compares a command used to both a target profile and a ‘union’ profile (containing all commands available in any profile in the profile dir). If a command is not present in the union profile, it is assumed to be locally created and ignored. Otherwise, if a command is present in the union profile but not present in a target, it is deemed to be incompatible with that target.

​
Configuration settings

Configuration keyMeaningAccepted valuesMandatoryExample
EnableActivates the rulebool ($true/$false)No (default: $false)$true
TargetProfilesThe list of PowerShell profiles to targetstring[]: absolute paths to profile files or names of profiles in the profile directoryNo (default: @())@('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')
ProfileDirPathThe location to search for profiles by name and use for union profile generationstring: absolute path to new profile dirNo (defaults to compatibility_profiles directory in PSScriptAnalyzer module)C:\Users\me\Documents\pssaCompatProfiles
IgnoreCommandsCommands to ignore compatibility of in scriptsstring[]: names of commands to ignoreNo (default: @())@('Get-ChildItem','Import-Module')
An example configuration might look like: 
@{
    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'
            )
        }
    }
}

​
Suppression

Command compatibility diagnostics can be suppressed with an attribute on the param block of a scriptblock as with other rules. 
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands', '')]
The rule can also be suppressed only for particular commands: 
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'Start-Service')]
And also suppressed only for parameters: 
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'Import-Module/FullyQualifiedName')]

​
Source

This rule documentation is adapted from Microsoft’s PSScriptAnalyzer documentation for UseCompatibleCommands, licensed under CC BY 4.0.