UseCompatibleTypes

Artigo
12/12/2024

Nível de gravidade: Aviso

Descrição

Esta regra identifica tipos que não estão disponíveis (carregados por padrão) em plataformas PowerShell de destino.

Uma plataforma 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 operacional em que o PowerShell está sendo executado. No Windows, isso inclui o número SKU. No Linux, este é o nome da distribuição.
<os-arch>: A arquitetura da máquina em que o sistema operacional está sendo executado (geralmente é x64).
<os-version>: A versão auto-relatada do sistema operacional (no Linux, esta é a versão de distribuição).
<ps-version>: A versão do PowerShell (do $PSVersionTable.PSVersion).
<ps-arch>: A arquitetura de máquina do processo do PowerShell.
<dotnet-version>: A versão relatada do PowerShell de tempo de execução do .NET está sendo executada em (a partir de System.Environment.Version).
<dotnet-edition>: O tipo de tempo de execução do .NET PowerShell está sendo executado em (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 operacional.
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 vêm junto com o PSScriptAnalyzer como arquivos JSON, nomeados dessa forma para direcionamento em sua configuração.

As plataformas agrupadas por padrão são:

Versão do PowerShell	Sistema Operativo	Identificação
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	Janelas 10.0.14393	`win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core`
6.2	Janelas 10.0.17763	`win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core`
6.2	Janelas 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	Janelas 10.0.14393	`win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core`
7.0	Janelas 10.0.17763	`win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core`
7.0	Janelas 10.0.18362	`win-4_x64_10.0.18362.0_7.0.0_x64_3.1.2_core`

Outros perfis podem ser encontrados no repositório GitHub.

Você também pode gerar seu próprio perfil de plataforma usando o módulo PSCompatibilityCollector.

As configurações de perfil de compatibilidade levam uma lista de plataformas para segmentar 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 é pesquisado no diretório de perfil padrão.
Um nome de arquivo (como my_custom_platform.json), que será pesquisado para o no diretório de perfil padrão.
Um caminho absoluto para um arquivo (como D:\PowerShellProfiles\TargetMachine.json).

O diretório de perfil padrão está sob o módulo PSScriptAnalzyer em $PSScriptRoot/PSCompatibilityCollector/profiles (onde $PSScriptRoot aqui se refere ao diretório que contém PSScriptAnalyzer.psd1).

A análise de compatibilidade compara um tipo utilizado tanto com um perfil de destino como com um perfil de «união» (contendo todos os tipos disponíveis em qualquer perfil no perfil dir). Se um tipo não estiver presente no perfil da união, presume-se que ele seja criado localmente e ignorado. Caso contrário, se um tipo estiver presente no perfil do sindicato, mas não estiver presente em um alvo, ele será considerado incompatível com esse alvo.

Definições de configuração

Chave de configuração	Significado	Valores aceites	Obrigatório	Exemplo
`Enable`	Ativa a regra	Bool (`$true`/`$false`)	Não (padrão: `$false`)	`$true`
`TargetProfiles`	A lista de perfis do PowerShell a serem direcionados	string[]: caminhos absolutos para arquivos de perfil ou nomes de perfis no diretório de perfis	Não (padrã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`	O local para pesquisar perfis por nome e usar para a geração de perfis de união	string: caminho absoluto para novo perfil dir	Não (padrão para `compatibility_profiles` diretório no módulo PSScriptAnalyzer	`C:\Users\me\Documents\pssaCompatProfiles`
`IgnoreTypes`	Nomes completos de tipos ou aceleradores de tipo para ignorar a compatibilidade de scripts	string[]: nomes de tipos a serem ignorados	Não (padrão: `@()`)	`@('System.Collections.ArrayList','string')`

Um exemplo de configuração pode ser parecido com:

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

Como alternativa, você pode fornecer um objeto de configurações da seguinte maneira:

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

O diagnóstico de compatibilidade de comandos pode ser suprimido com um atributo no bloco param de um scriptblock como acontece 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')]

Partilhar via

UseCompatibleTypes

Descrição

Definições de configuração

Supressão

Comentários

Recursos adicionais