UseCompatibleCommands

Nivel de gravedad de : advertencia

Estado por defecto: Desactivado

Descripción

Esta regla detecta comandos que no están disponibles en tu plataforma PowerShell objetivo.

Los nombres de plataformas PowerShell utilizan el siguiente formato:

<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, el número SKU está incluido. En Linux, el valor es el nombre de la distribución.
  • <os-arch>: La arquitectura de la máquina en la que se ejecuta el sistema operativo (normalmente x64).
  • <os-version>: La versión auto-reportada del sistema operativo (la versión de distribución en Linux).
  • <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.

PSScriptAnalyzer incluye algunos perfiles de plataforma como archivos JSON. Puedes dirigir estos perfiles integrados directamente a tu 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 puedes generar tu propio perfil de plataforma con el módulo PSCompatibilityCollector.

La configuración de compatibilidad incluye una lista de plataformas bajo TargetProfiles. Puedes especificar cada plataforma objetivo como:

  • Un nombre de plataforma (por ejemplo, ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core). PSScriptAnalyzer lo añade .json y lo busca en el directorio de perfil por defecto.
  • Un nombre de archivo (por ejemplo, my_custom_platform.json), que PSScriptAnalyzer busca en el directorio de perfil por defecto.
  • Ruta de acceso absoluta a un archivo (como D:\PowerShellProfiles\TargetMachine.json).

El directorio de perfil por defecto está bajo el módulo PSScriptAnalyzer en $PSScriptRoot/compatibility_profiles (donde $PSScriptRoot aquí se refiere al directorio que contiene PSScriptAnalyzer.psd1).

El análisis de compatibilidad compara cada comando que usas tanto con un perfil objetivo como con un perfil de unión. El perfil de unión contiene todos los comandos disponibles en cualquier perfil del directorio de perfil.

Si un comando no está en el perfil de la unión, la regla asume que es local para tu entorno y lo ignora. Si un comando está en el perfil de unión pero falta en un perfil de objetivo, la regla lo marca como incompatible con ese objetivo.

Ejemplo

Los siguientes ejemplos asumen TargetProfiles incluyendo ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core (Ubuntu 18.04, PowerShell 6.2).

No conforme

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

Compliant

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

Configurar regla

@{
    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

Este parámetro controla si ScriptAnalyzer comprueba el código con esta regla. Acepta un valor booleano. Para habilitar esta regla, establece este parámetro en $true. El valor por defecto es $false.

Perfiles de Objetivo

Este parámetro especifica la lista de perfiles de plataforma para comprobar la compatibilidad con ella. Acepta una matriz de cadenas. Cada valor puede ser un nombre de plataforma, un nombre de archivo o una ruta absoluta hacia un archivo de perfil. El valor por defecto es @().

PerfilDirPath

Este parámetro controla el directorio que ScriptAnalyzer busca perfiles por nombre y utiliza para generar el perfil de unión. Acepta una cadena que contiene un camino absoluto. La ubicación predeterminada es el compatibility_profiles directorio en el módulo PSScriptAnalyzer.

IgnorarComandas

Este parámetro especifica comandos que deben excluirse de las comprobaciones de compatibilidad. Acepta una matriz de cadenas de nombres de comando. El valor por defecto es @().

Supresión

Como con otras reglas, puedes suprimir diagnósticos de compatibilidad de comandos añadiendo un atributo de supresión al param bloque de un bloque de script.

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

También puedes suprimir la regla para comandos específicos:

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

También puedes suprimirlo para parámetros específicos:

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