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/PSUseCompatibleTypes is a PSScriptAnalyzer diagnostic emitted by tally for PowerShell snippets embedded in Dockerfiles.
PropertyValue
SeverityWarning
CategoryPSScriptAnalyzer
Auto-fixNo

​
Description

This rule identifies types that are not available (loaded by default) in targeted PowerShell platforms. 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/PSCompatibilityCollector/profiles (where $PSScriptRoot here refers to the directory containing PSScriptAnalyzer.psd1). The compatibility analysis compares a type used to both a target profile and a ‘union’ profile (containing all types available in any profile in the profile dir). If a type is not present in the union profile, it is assumed to be locally created and ignored. Otherwise, if a type 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
IgnoreTypesFull names of types or type accelerators to ignore compatibility of in scriptsstring[]: names of types to ignoreNo (default: @())@('System.Collections.ArrayList','string')
An example configuration might look like: 
@{
    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'
            )
        }
    }
}
Alternatively, you could provide a settings object as follows: 
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'

​
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('PSUseCompatibleTypes', '')]
The rule can also be suppressed only for particular types: 
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes',
    'System.Management.Automation.Security.SystemPolicy')]
And also suppressed only for type members: 
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes',
    'System.Management.Automation.LanguagePrimitives/ConvertTypeNameToPSTypeName')]

​
Source

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