UseConsistentParameterSetName

Nível de Gravidade: Aviso

Descrição

Os nomes dos conjuntos de parâmetros no PowerShell são diferenciados em maiúsculas e minúsculas, ao contrário da maioria dos outros elementos do PowerShell. Essa regra garante uma carcaça consistente e a configuração adequada dos conjuntos de parâmetros para evitar erros de execução e melhorar a clareza do código.

A regra realiza cinco testes diferentes:

1. Falta de DefaultParameterSetName - Avisa quando conjuntos de parâmetros são usados, mas nenhum padrão é especificado
2. Múltiplas declarações de parâmetros - Detecta quando um parâmetro é declarado várias vezes no mesmo conjunto de parâmetros. Isso é, no fim das contas, uma exceção em tempo de execução – essa verificação ajuda a detectar mais cedo.
3. Incompatibilidade de case entre DefaultParameterSetName e ParameterSetName - Garante a consistência do case
4. Incompatibilidade de casos entre diferentes valores ParameterSetName - Garante que todas as referências ao mesmo conjunto de parâmetros usem carcaças idênticas
5. Nomes de conjuntos de parâmetros contendo novas linhas - Alerta contra o uso de caracteres de nova linha nos nomes dos conjuntos de parâmetros

Observação

Essa regra não está ativada por padrão. O usuário precisa habilitá-lo pelas configurações.

Como

• Use a DefaultParameterSetName ao definir múltiplos conjuntos de parâmetros
• Garanta uma carcaça consistente entre DefaultParameterSetName valores e ParameterSetName
• Use carcaça idêntica para todas as referências ao mesmo nome de conjunto de parâmetros
• Evite declarar o mesmo parâmetro várias vezes em um único conjunto de parâmetros
• Não use caracteres de nova linha em nomes de conjuntos de parâmetros

Exemplo

Errado

# Missing DefaultParameterSetName
function Get-Data {
    [CmdletBinding()]
    param(
        [Parameter(ParameterSetName='ByName')]
        [string]$Name,

        [Parameter(ParameterSetName='ByID')]
        [int]$ID
    )
}

# Case mismatch between DefaultParameterSetName and ParameterSetName
function Get-Data {
    [CmdletBinding(DefaultParameterSetName='ByName')]
    param(
        [Parameter(ParameterSetName='byname')]
        [string]$Name,

        [Parameter(ParameterSetName='ByID')]
        [int]$ID
    )
}

# Inconsistent casing between ParameterSetName values
function Get-Data {
    [CmdletBinding(DefaultParameterSetName='ByName')]
    param(
        [Parameter(ParameterSetName='ByName')]
        [string]$Name,

        [Parameter(ParameterSetName='byname')]
        [string]$DisplayName
    )
}

# Multiple parameter declarations in same set
function Get-Data {
    param(
        [Parameter(ParameterSetName='ByName')]
        [Parameter(ParameterSetName='ByName')]
        [string]$Name
    )
}

# Parameter set name with newline
function Get-Data {
    param(
        [Parameter(ParameterSetName="Set`nOne")]
        [string]$Name
    )
}

Correto

# Proper parameter set configuration
function Get-Data {
    [CmdletBinding(DefaultParameterSetName='ByName')]
    param(
        [Parameter(ParameterSetName='ByName', Mandatory)]
        [string]$Name,

        [Parameter(ParameterSetName='ByName')]
        [Parameter(ParameterSetName='ByID')]
        [string]$ComputerName,

        [Parameter(ParameterSetName='ByID', Mandatory)]
        [int]$ID
    )
}

Configuração

Rules = @{
    PSUseConsistentParameterSetName  = @{
        Enable = $true
    }
}

Parâmetros

• Enable: bool (Valor padrão é $false)

  Habilite ou desabilite a regra durante a invocação de ScriptAnalyzer.

Observações

• Os nomes dos conjuntos de parâmetros são sensíveis a maiúsculas minúsculas no PowerShell, tornando isso diferente da maioria dos outros elementos do PowerShell
• A primeira ocorrência de um nome de conjunto de parâmetros no seu código é tratada como a carcaça canônica
• Parâmetros sem [Parameter()] atributos fazem automaticamente parte de todos os conjuntos de parâmetros
• É uma boa prática do PowerShell sempre especificar a DefaultParameterSetName ao usar conjuntos de parâmetros