Partilhar via

UseCompatibleTypes

  • Artigo

Nível de Gravidade: Aviso

Description

Esta regra identifica tipos que não estão disponíveis (carregados por predefinição) em plataformas do PowerShell direcionadas.

Uma plataforma do PowerShell é identificada por um nome no seguinte formato:

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

Em que:

  • <os-name>: O nome do sistema operativo no qual o PowerShell está em execução. No Windows, isto inclui o número de SKU. No Linux, este é o nome da distribuição.
  • <os-arch>: a arquitetura da máquina em que o sistema operativo está a ser executado (normalmente x64, é ).
  • <os-version>: a versão auto-comunicada do sistema operativo (no Linux, esta é a versão de distribuição).
  • <ps-version>: a versão do PowerShell (de $PSVersionTable.PSVersion).
  • <ps-arch>: a arquitetura do computador do processo do PowerShell.
  • <dotnet-version>: A versão comunicada do PowerShell de runtime do .NET está em execução (a partir de System.Environment.Version).
  • <dotnet-edition>: O sabor de runtime .NET do PowerShell está em execução no (atualmente framework ou core).

Por exemplo:

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_frameworké o PowerShell 5.1 em execução no Windows 10 Enterprise (compilação 18312) para x64.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core é o PowerShell 6.1.2 em execução no mesmo sistema operativo.
  • ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core é o PowerShell 6.2.0 em execução no Ubuntu 18.04.

Algumas plataformas são agrupadas com o PSScriptAnalyzer como ficheiros JSON, nomeados desta forma para segmentação na sua configuração.

As plataformas agrupadas por predefinição são:

Versão do PowerShell Sistema Operativo ID
3.0 Windows Server 2012 win-8_x64_6.2.9200.0_3.0_x64_4.0.30319.42000_framework
4.0 Windows Server 2012R2 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 1809 (RS5) win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
6.2 Windows Server 2016 win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows Server 2019 win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10 1809 (RS5) win-4_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Ubuntu 18.04 LTS ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core
7.0 Windows Server 2016 win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core
7.0 Windows Server 2019 win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core
7.0 Windows 10 1809 (RS5) win-4_x64_10.0.17763.0_6.2.4_x64_3.1.2_core
7.0 Ubuntu 18.04 LTS ubuntu_x64_18.04_7.0.0_x64_3.1.2_core

Podem ser encontrados outros perfis no repositório do GitHub.

Também pode gerar o seu próprio perfil de plataforma com o módulo PSCompatibilityCollector.

As definições do perfil de compatibilidade levam uma lista de plataformas a visar em TargetProfiles. Uma plataforma pode ser especificada como:

  • Um nome de plataforma (como ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), que terá .json adicionado ao final e é procurado no diretório de perfil predefinido.
  • Um nome de ficheiro (como my_custom_platform.json), que será procurado no diretório de perfil predefinido.
  • Um caminho absoluto para um ficheiro (como D:\PowerShellProfiles\TargetMachine.json).

O diretório de perfil predefinido está no módulo PSScriptAnalzyer em $PSScriptRoot/PSCompatibilityCollector/profiles (onde $PSScriptRoot aqui se refere ao diretório que PSScriptAnalyzer.psd1contém ).

A análise de compatibilidade compara um tipo utilizado com um perfil de destino e um perfil "união" (que contém todos os tipos disponíveis em qualquer perfil no dir do perfil). Se um tipo não estiver presente no perfil de união, assume-se que foi criado localmente e ignorado. Caso contrário, se um tipo estiver presente no perfil sindical, mas não estiver presente num destino, será considerado incompatível com esse destino.

Definições de configuração

Chave de configuração Significado Valores aceites Obrigatório Exemplo
Enable Ativa a regra bool ($true/$false) Não (predefinição: $false) $true
TargetProfiles A lista de perfis do PowerShell para destino string[]: caminhos absolutos para ficheiros de perfil ou nomes de perfis no diretório de perfil Não (predefinição: @()) @('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 A localização para procurar perfis por nome e utilização para a geração de perfis sindicais cadeia: caminho absoluto para o novo dir de perfil Não (predefinições para o compatibility_profiles diretório no módulo PSScriptAnalyzer C:\Users\me\Documents\pssaCompatProfiles
IgnoreTypes Nomes completos de tipos ou aceleradores de tipos para ignorar a compatibilidade de em scripts string[]: nomes de tipos a ignorar Não (predefinição: @()) @('System.Collections.ArrayList','string')

Uma configuração de exemplo pode ter o seguinte aspeto:

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

Em alternativa, pode fornecer um objeto de definições da seguinte forma:

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'

Supressão

Os diagnósticos de compatibilidade de comandos podem ser suprimidos com um atributo no param bloco de um scriptblock como com outras regras.

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

A regra também pode ser suprimida apenas para tipos específicos:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes', 'System.Management.Automation.Security.SystemPolicy')]

E também suprimido apenas para membros do tipo:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands', 'System.Management.Automation.LanguagePrimitives/ConvertTypeNameToPSTypeName')]