Compartir a través de

UseCompatibleCommands

  • Artículo

Nivel de gravedad de : advertencia

Descripción

Esta regla identifica los comandos que no están disponibles en una plataforma de PowerShell de destino.

Una plataforma de PowerShell se identifica con un nombre en el formato siguiente:

<os-name>_<os-arch>_<os-version>_<ps-version>_<ps-arch>_<dotnet-version>_<dotnet-edition>

Dónde:

  • <os-name>: el nombre del sistema operativo en el que se ejecuta PowerShell. En Windows, esto incluye el número de SKU. En Linux, este es el nombre de la distribución.
  • <os-arch>: la arquitectura de máquina en la que se ejecuta el sistema operativo (normalmente se x64).
  • <os-version>: la versión autoinformó del sistema operativo (en Linux, esta es la versión de distribución).
  • <ps-version>: la versión de PowerShell (de $PSVersionTable.PSVersion).
  • <ps-arch>: la arquitectura de máquina del proceso de PowerShell.
  • <dotnet-version>: la versión notificada de PowerShell en tiempo de ejecución de .NET se ejecuta (desde System.Environment.Version).
  • <dotnet-edition>: PowerShell del tipo de tiempo de ejecución de .NET se está ejecutando (actualmente framework o core).

Por ejemplo:

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework es PowerShell 5.1 que se ejecuta en Windows 10 Enterprise (compilación 18312) para x64.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core es PowerShell 6.1.2 que se ejecuta en el mismo sistema operativo.
  • ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core es PowerShell 6.2.0 que se ejecuta en Ubuntu 18.04.

Algunas plataformas se incluyen con PSScriptAnalyzer como archivos JSON, denominados de esta manera para dirigirse a la configuración.

Las plataformas agrupadas de forma predeterminada son:

Versión de PowerShell Sistema operativo IDENTIFICACIÓN
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

Puede encontrar otros perfiles en el repositorio de GitHub de .

También puede generar su propio perfil de plataforma mediante el módulo PSCompatibilityCollector de .

La configuración del perfil de compatibilidad toma una lista de plataformas de destino en TargetProfiles. Se puede especificar una plataforma como:

  • Nombre de la plataforma (como ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), que tendrá .json agregado al final y se buscará en el directorio de perfil predeterminado.
  • Un nombre de archivo (como my_custom_platform.json), que se buscará en el directorio de perfil predeterminado.
  • Ruta de acceso absoluta a un archivo (como D:\PowerShellProfiles\TargetMachine.json).

El directorio de perfil predeterminado está en el módulo PSScriptAnalzyer en $PSScriptRoot/compatibility_profiles (donde $PSScriptRoot aquí hace referencia al directorio que contiene PSScriptAnalyzer.psd1).

El análisis de compatibilidad compara un comando usado para un perfil de destino y un perfil de "unión" (que contiene todos los comandos disponibles en cualquier perfil de en el dir de perfil). Si un comando no está presente en el perfil de unión, se supone que se crea y se omite localmente. De lo contrario, si un comando está presente en el perfil de unión, pero no está presente en un destino, se considera incompatible con ese destino.

Configuración

Clave de configuración Significado Valores aceptados Obligatorio Ejemplo
Enable Activa la regla bool ($true/$false) No (valor predeterminado: $false) $true
TargetProfiles La lista de perfiles de PowerShell que se van a dirigir string[]: rutas de acceso absolutas a archivos de perfil o nombres de perfiles en el directorio de perfiles No (valor predeterminado: @()) @('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 Ubicación que se va a buscar perfiles por nombre y uso para la generación de perfiles de unión string: ruta de acceso absoluta al nuevo dir de perfil No (el valor predeterminado es compatibility_profiles directorio en el módulo PSScriptAnalyzer C:\Users\me\Documents\pssaCompatProfiles
IgnoreCommands Comandos para omitir la compatibilidad de en scripts string[]: nombres de comandos que se omitirán No (valor predeterminado: @()) @('Get-ChildItem','Import-Module')

Una configuración de ejemplo podría ser similar a la siguiente:

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

Supresión

Los diagnósticos de compatibilidad de comandos se pueden suprimir con un atributo en el bloque param de un scriptblock como con otras reglas.

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

La regla también se puede suprimir solo para determinados comandos:

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

Y también se suprime solo para los parámetros:

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