Diretrizes de desenvolvimento altamente recomendadas

Esta seção descreve as diretrizes que você deve seguir ao escrever seus cmdlets. Eles são separados em diretrizes para criar cmdlets e diretrizes para escrever o código do cmdlet. Você pode achar que essas diretrizes não são aplicáveis a todos os cenários. No entanto, se elas se aplicarem e você não seguir essas diretrizes, os usuários poderão ter uma experiência ruim quando usarem seus cmdlets.

Diretrizes de design

As diretrizes a seguir devem ser seguidas ao criar cmdlets para garantir uma experiência consistente do usuário entre o uso de seus cmdlets e outros cmdlets. Ao encontrar uma diretriz de Design que se aplique à sua situação, examine as diretrizes de código para obter diretrizes semelhantes.

Usar um substantivo específico para um nome de cmdlet (SD01)

Os substantivos usados na nomenclatura de cmdlet precisam ser muito específicos para que o usuário possa descobrir seus cmdlets. Prefixe substantivos genéricos, como "servidor" com uma versão abreviada do nome do produto. Por exemplo, se um substantivo se referir a um servidor que está executando uma instância de Microsoft SQL Server, use um substantivo como "SQLServer". A combinação de substantivos específicos e a breve lista de verbos aprovados permitem que o usuário descubra e preveja rapidamente a funcionalidade, evitando a duplicação entre nomes de cmdlet.

Para aprimorar a experiência do usuário, o substantivo escolhido para um nome de cmdlet deve ser singular. Por exemplo, use o nome Get-Process em vez de Get-Processes. É melhor seguir essa regra para todos os nomes de cmdlet, mesmo quando é provável que um cmdlet atue em mais de um item.

Use o Pascal Case para nomes de cmdlets (SD02)

Use o caso Pascal para nomes de parâmetro. Em outras palavras, capitalize a primeira letra de verbo e todos os termos usados no substantivo. Por exemplo, "Clear-ItemProperty".

Diretrizes de design de parâmetros (SD03)

Um cmdlet precisa de parâmetros que recebam os dados nos quais ele deve operar e parâmetros que indicam informações usadas para determinar as características da operação. Por exemplo, um cmdlet pode ter um Name parâmetro que recebe dados do pipeline e o cmdlet pode ter um Force parâmetro para indicar que o cmdlet pode ser forçado a executar sua operação. Não há limite para o número de parâmetros que um cmdlet pode definir.

Usar nomes de parâmetro padrão

Seu cmdlet deve usar nomes de parâmetro padrão para que o usuário possa determinar rapidamente o que significa um parâmetro específico. Se um nome mais específico for necessário, use um nome de parâmetro padrão e especifique um nome mais específico como um alias. Por exemplo, o Get-Service cmdlet tem um parâmetro que tem um nome genérico (Name) e um alias mais específico (ServiceName). Ambos os termos podem ser usados para especificar o parâmetro.

Para obter mais informações sobre nomes de parâmetros e seus tipos de dados, consulte o nome do parâmetro cmdlet e as diretrizes de funcionalidade.

Usar nomes singulares para parâmetros

Evite usar nomes plurales para parâmetros cujo valor é um único elemento. Isso inclui parâmetros que aceitam arrays ou listas porque o usuário pode fornecer um array ou lista com um único elemento.

Os nomes de parâmetro plural devem ser usados somente nos casos em que o valor do parâmetro é sempre um valor de vários elementos. Nesses casos, o cmdlet deve verificar se vários elementos são fornecidos e o cmdlet deve exibir um aviso ao usuário se vários elementos não forem fornecidos.

Use o Caso Pascal para nomes de parâmetros

Use o caso Pascal para nomes de parâmetro. Em outras palavras, capitalize a primeira letra de cada palavra no nome do parâmetro, incluindo a primeira letra do nome. Por exemplo, o nome ErrorAction do parâmetro usa a capitalização correta. Os seguintes nomes de parâmetro usam a capitalização incorreta:

• errorAction
• erroraction

Parâmetros que aceitam uma lista de opções

Há duas maneiras de criar um parâmetro cujo valor pode ser selecionado em um conjunto de opções.

• Defina um tipo de enumeração (ou use um tipo de enumeração existente) que especifica os valores válidos. Em seguida, use o tipo de enumeração para criar um parâmetro desse tipo.

• Adicione o atributo ValidateSet à declaração de parâmetro. Para obter mais informações sobre esse atributo, consulte a Declaração de Atributo ValidateSet.

Usar tipos padrão para parâmetros

Para garantir a consistência com outros cmdlets, use tipos padrão para parâmetros sempre que possível. Para obter mais informações sobre os tipos que devem ser usados para parâmetros diferentes, consulte Nomes e Tipos de Parâmetros de Cmdlet Padrão. Este tópico fornece links para vários tópicos que descrevem os nomes e tipos de estrutura .NET para grupos de parâmetros padrão, como os "parâmetros de atividade".

Usar tipos fortemente tipados do .NET Framework

Os parâmetros devem ser definidos como tipos .NET Framework para fornecer melhor validação de parâmetro. Por exemplo, parâmetros restritos a um valor de um conjunto de valores devem ser definidos como um tipo de enumeração. Para dar suporte a um valor de URI (Uniform Resource Identifier), defina o parâmetro como um tipo System.Uri . Evite parâmetros básicos de cadeia de caracteres para todas as propriedades de texto de forma livre.

Usar tipos de parâmetro consistentes

Quando o mesmo parâmetro é usado por vários cmdlets, sempre use o mesmo tipo de parâmetro. Por exemplo, se o Process parâmetro for do tipo System.Int16 para um cmdlet, não faça o Process parâmetro para outro cmdlet do tipo System.Uint16.

Parâmetros que aceitam verdadeiro e falso

Se o parâmetro usar apenas true e false, defina o parâmetro como o tipo System.Management.Automation.SwitchParameter. Um [switch] parâmetro é tratado como true quando é especificado em um comando. Se o parâmetro não estiver incluído em um comando, Windows PowerShell considerará o valor do parâmetro como false. Não defina parâmetros boolianos.

Se o parâmetro precisar diferenciar entre 3 valores: $true, $false e "não especificado", defina um parâmetro do tipo Nullable<bool>. A necessidade de um terceiro valor "não especificado" normalmente ocorre quando o cmdlet pode modificar uma propriedade booliana de um objeto. Nesse caso, "não especificado" significa não alterar o valor atual da propriedade.

Matrizes de suporte para parâmetros

Com frequência, os usuários devem executar a mesma operação em relação a vários argumentos. Para esses usuários, um cmdlet deve aceitar uma matriz como entrada de parâmetro para que um usuário possa passar os argumentos para o parâmetro como uma variável do Windows PowerShell. Por exemplo, o cmdlet Get-Process usa uma matriz para as cadeias de caracteres que identificam os nomes dos processos a serem recuperados.

Suporte ao parâmetro PassThru

Por padrão, muitos cmdlets que modificam o sistema, como o cmdlet Stop-Process, atuam como "sinks" para objetos e não retornam um resultado. Esse cmdlet deve implementar o PassThru parâmetro para forçar o cmdlet a retornar um objeto. Quando o PassThru parâmetro é especificado, o cmdlet retorna um objeto usando uma chamada para o método System.Management.Automation.Cmdlet.WriteObject . Por exemplo, o comando a seguir interrompe o Calc (CalculatorApp.exe) e passa o processo resultante para o pipeline.

Stop-Process -Name CalculatorApp -PassThru

Na maioria dos casos, os cmdlets Add, Set e New devem dar suporte a um PassThru parâmetro.

Conjuntos de parâmetros de suporte

Um cmdlet destina-se a realizar uma única finalidade. No entanto, há frequentemente mais de uma maneira de descrever a operação ou o destino da operação. Por exemplo, um processo pode ser identificado por seu nome, por seu identificador ou por um objeto de processo. O cmdlet deve dar suporte a todas as representações possíveis de seus alvos. Normalmente, o cmdlet atende a esse requisito especificando conjuntos de parâmetros (conhecidos como conjuntos de parâmetros) que operam juntos. Um único parâmetro pode pertencer a qualquer número de conjuntos de parâmetros. Para obter mais informações sobre conjuntos de parâmetros, consulte Conjuntos de Parâmetros do Cmdlet.

Quando você especificar conjuntos de parâmetros, defina apenas um parâmetro no conjunto como ValueFromPipeline. Para obter mais informações sobre como declarar o atributo Parameter , consulte ParameterAttribute Declaration.

Quando conjuntos de parâmetros são usados, o conjunto de parâmetros padrão é definido pelo atributo Cmdlet . O conjunto de parâmetros padrão deve incluir os parâmetros mais propensos a serem usados em uma sessão interativa do PowerShell Windows. Para obter mais informações sobre como declarar o atributo Cmdlet , consulte a Declaração CmdletAttribute.

Fornecer comentários ao usuário (SD04)

Use as diretrizes nesta seção para fornecer comentários ao usuário. Esses comentários permitem que o usuário esteja ciente do que está ocorrendo no sistema e tome melhores decisões administrativas.

O Windows runtime do PowerShell permite que um usuário especifique como lidar com a saída de cada chamada para o método Write definindo uma variável de preferência. O usuário pode definir várias variáveis de preferência, incluindo uma variável que determina se o sistema deve exibir informações e uma variável que determina se o sistema deve consultar o usuário antes de tomar outras medidas.

Suporte aos métodos WriteWarning, WriteVerbose e WriteDebug

Um cmdlet deve chamar o método System.Management.Automation.Cmdlet.WriteWarning quando o cmdlet está prestes a executar uma operação que pode ter um resultado não intencional. Por exemplo, um cmdlet deve chamar esse método se o cmdlet estiver prestes a substituir um arquivo somente leitura.

Um cmdlet deve chamar o método System.Management.Automation.Cmdlet.WriteVerbose quando o usuário exigir alguns detalhes sobre o que o cmdlet está fazendo. Por exemplo, um cmdlet deve chamar essas informações se o autor do cmdlet achar que há cenários que podem exigir mais informações sobre o que o cmdlet está fazendo.

O cmdlet deve chamar o método System.Management.Automation.Cmdlet.WriteDebug quando um desenvolvedor ou engenheiro de suporte ao produto deve entender o que corrompeu a operação de cmdlet. Não é necessário que o cmdlet chame o método System.Management.Automation.Cmdlet.WriteDebug no mesmo código que chama o método System.Management.Automation.Cmdlet.WriteVerbose porque o Debug parâmetro apresenta ambos os conjuntos de informações.

Suporte a WriteProgress for Operations que levam muito tempo

As operações de cmdlet que levam muito tempo para serem concluídas e que não podem ser executadas em segundo plano devem dar suporte a relatórios de progresso por meio de chamadas periódicas para o método System.Management.Automation.Cmdlet.WriteProgress .

Usar as interfaces de host

Ocasionalmente, um cmdlet deve se comunicar diretamente com o usuário em vez de usar os vários métodos Write ou Should compatíveis com a classe System.Management.Automation.Cmdlet . Nesse caso, o cmdlet deve derivar da classe System.Management.Automation.PSCmdlet e usar a propriedade System.Management.Automation.PSCmdlet.Host* . Essa propriedade dá suporte a diferentes níveis de tipo de comunicação, incluindo os tipos PromptForChoice, Prompt e WriteLine/ReadLine. No nível mais específico, ele também fornece maneiras de ler e gravar chaves individuais e lidar com buffers.

A menos que um cmdlet seja projetado especificamente para gerar uma GUI (interface gráfica do usuário), ele não deve ignorar o host usando a propriedade System.Management.Automation.PSCmdlet.Host* . Um exemplo de um cmdlet projetado para gerar uma GUI é o cmdlet Out-GridView.

Criar um arquivo de ajuda do cmdlet (SD05)

Para cada assembly de cmdlet, crie um arquivo Help.xml que contenha informações sobre o cmdlet. Essas informações incluem uma descrição do cmdlet, descrições dos parâmetros do cmdlet, exemplos de uso do cmdlet e muito mais.

Diretrizes de código

As diretrizes a seguir devem ser seguidas ao codificar cmdlets para garantir uma experiência consistente do usuário entre o uso de seus cmdlets e outros cmdlets. Quando encontrar uma diretriz de código que se aplique à sua situação, examine as diretrizes de Design para obter diretrizes semelhantes.

Parâmetros de codificação (SC01)

Defina um parâmetro declarando uma propriedade pública da classe cmdlet decorada com o atributo Parameter . Os parâmetros não precisam ser membros estáticos da classe .NET Framework derivada para o cmdlet. Para obter mais informações sobre como declarar o atributo Parameter , consulte a Declaração de Atributo de Parâmetro.

Supporte os caminhos do Windows PowerShell

O caminho do Windows PowerShell é o mecanismo para normalizar o acesso aos namespaces. Quando você atribui um caminho do Windows PowerShell a um parâmetro no cmdlet, o usuário pode definir uma "unidade de disco" personalizada que funciona como um atalho para um caminho específico. Quando um usuário designa essa unidade, os dados armazenados, como dados no Registro, podem ser usados de maneira consistente.

Se o cmdlet permitir que o usuário especifique um arquivo ou uma fonte de dados, ele deverá definir um parâmetro do tipo System.String. Se houver suporte para mais de uma unidade, o tipo deverá ser uma matriz. O nome do parâmetro deve ser Path, com um alias de PSPath. Além disso, o Path parâmetro deve dar suporte a caracteres curinga. Se o suporte para caracteres curinga não for necessário, defina um LiteralPath parâmetro.

Se os dados que o cmdlet lê ou grava tiverem que ser um arquivo, o cmdlet deverá aceitar a entrada de caminho do Windows PowerShell, e o cmdlet deverá usar a propriedade System.Management.Automation.SessionState.Path para converter os caminhos do Windows PowerShell em caminhos reconhecidos pelo sistema de arquivos. Os mecanismos específicos incluem os seguintes métodos:

• System.Management.Automation.PSCmdlet.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PSCmdlet.GetUnresolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetUnresolvedProviderPathFromPSPath

Se os dados que o cmdlet lê ou grava for apenas um conjunto de cadeias de caracteres em vez de um arquivo, o cmdlet deverá usar as informações de conteúdo do provedor (Content membro) para ler e gravar. Essas informações são obtidas da propriedade System.Management.Automation.Provider.CmdletProvider.InvokeProvider . Esses mecanismos permitem que outros armazenamentos de dados participem da leitura e gravação de dados.

Dar suporte a caracteres curinga

Um cmdlet deve dar suporte a caracteres curinga, se possível. O suporte para caracteres curinga ocorre em muitos lugares em um cmdlet (especialmente quando um parâmetro usa uma cadeia de caracteres para identificar um objeto de um conjunto de objetos). Por exemplo, o cmdlet de exemplo Stop-Proc do Tutorial do StopProc define um Name parâmetro para manipular cadeias de caracteres que representam nomes de processo. Esse parâmetro dá suporte a caracteres curinga para que o usuário possa especificar facilmente os processos a serem interrompidos.

Quando o suporte para caracteres curinga está disponível, uma operação de cmdlet geralmente produz uma matriz. Ocasionalmente, não faz sentido dar suporte a uma matriz porque o usuário pode usar apenas um único item de cada vez. Por exemplo, o cmdlet Set-Location não precisa dar suporte a uma matriz porque o usuário está definindo apenas um único local. Nesse caso, o cmdlet ainda dá suporte a caracteres curinga, mas força a resolução a um único local.

Para obter mais informações sobre padrões de caractere curinga, consulte Suporte a caracteres curinga em parâmetros de cmdlet.

Definindo objetos

Esta seção contém diretrizes para definir objetos para cmdlets e para estender objetos existentes.

Definir membros padrão

Defina membros padrão para estender um tipo de objeto em um arquivo Types.ps1xml personalizado (use o arquivo Windows PowerShell Types.ps1xml como um modelo). Os membros padrão são definidos por um nó com o nome PSStandardMembers. Essas definições permitem que outros cmdlets e o tempo de execução do Windows PowerShell interajam com seu objeto de forma consistente.

Definir ObjectMembers a serem usados como parâmetros

Se você estiver projetando um objeto para um cmdlet, verifique se seus membros são mapeados diretamente para os parâmetros dos cmdlets que o utilizarão. Esse mapeamento permite que o objeto seja enviado facilmente ao pipeline e passado de um cmdlet para outro.

Objetos preexistentes do .NET Framework que são retornados por cmdlets frequentemente estão em falta de alguns membros importantes ou convenientes necessários para o desenvolvedor ou usuário de script. Esses membros ausentes podem ser particularmente importantes para exibição e para criar os nomes de membro corretos para que o objeto possa ser passado corretamente para o pipeline. Crie um arquivo Types.ps1xml personalizado para documentar esses membros necessários. Ao criar esse arquivo, recomendamos a seguinte convenção de nomenclatura: <Your_Product_Name>. Types.ps1xml.

Por exemplo, você pode adicionar uma Mode propriedade de script ao tipo System.IO.FileInfo para exibir os atributos de um arquivo com mais clareza. Além disso, você pode adicionar uma Count propriedade de alias ao tipo System.Array para permitir o uso consistente desse nome de propriedade (em vez de Length).

Implementar a interface IComparable

Implemente uma interface System.IComparable em todos os objetos de saída. Isso permite que os objetos de saída sejam canalizados de forma fácil para diversos cmdlets de classificação e análise.

Atualizar informações de exibição

Se a exibição de um objeto não fornecer os resultados esperados, crie um arquivo de formato Format.ps1xml personalizado para esse objeto.

Suporte à entrada de pipeline bem definida (SC02)

Implementar para a etapa intermediária de um pipeline

Implemente um cmdlet supondo que ele será chamado do meio de um pipeline (ou seja, outros cmdlets produzirão sua entrada ou consumirão sua saída). Por exemplo, você pode assumir que o Get-Process cmdlet, porque ele gera dados, é usado apenas como o primeiro cmdlet em um pipeline. No entanto, como esse cmdlet foi projetado para o meio de um pipeline, esse cmdlet permite que os cmdlets ou dados anteriores no pipeline especifiquem os processos a serem recuperados.

Entrada de suporte do pipeline

Em cada conjunto de parâmetros para um cmdlet, inclua pelo menos um parâmetro que dá suporte à entrada pelo pipeline. O suporte para entrada de pipeline permite que o usuário recupere dados ou objetos, envie-os para o conjunto de parâmetros correto e passe os resultados diretamente para um cmdlet.

Um parâmetro aceita a entrada do pipeline se o atributo Parameter incluir a ValueFromPipeline palavra-chave, o atributo de ValueFromPipelineByPropertyName palavra-chave ou ambas as palavras-chave em sua declaração. Se nenhum dos parâmetros em um conjunto de parâmetros suportar as ValueFromPipeline ou ValueFromPipelineByPropertyName palavras-chave, o cmdlet não poderá ser usado após outro cmdlet, pois ele ignorará qualquer entrada de pipeline.

Suporte ao método ProcessRecord

Para aceitar todos os registros do cmdlet anterior no pipeline, seu cmdlet deve implementar o método System.Management.Automation.Cmdlet.ProcessRecord . Windows PowerShell chama esse método várias vezes, uma vez para cada registro enviado ao cmdlet.

Gravar registros únicos no Pipeline (SC03)

Quando um cmdlet retorna objetos, o cmdlet deve gravar os objetos imediatamente conforme eles são gerados. O cmdlet não deve mantê-los em buffer em uma matriz combinada. Os cmdlets que recebem os objetos como entrada poderão processar, exibir ou processar e exibir os objetos de saída sem demora. Um cmdlet que gera objetos de saída um de cada vez deve chamar o método System.Management.Automation.Cmdlet.WriteObject . Um cmdlet que gera objetos de saída em lotes (por exemplo, porque uma API subjacente retorna uma matriz de objetos de saída) deve chamar o Método System.Management.Automation.Cmdlet.WriteObject com seu segundo parâmetro definido como true.

Tornar cmdlets Case-Insensitive e Case-Preserving (SC04)

Por padrão, o Windows PowerShell é insensível a maiúsculas. No entanto, como ele lida com muitos sistemas pré-existentes, o Windows PowerShell preserva o caso para facilitar a operação e a compatibilidade. Em outras palavras, se um caractere for fornecido em letras maiúsculas, Windows PowerShell o manterá em letras maiúsculas. Para que os sistemas funcionem bem, um cmdlet precisa seguir essa convenção. Se possível, ele deve operar de maneira que não diferencia maiúsculas de minúsculas. No entanto, ele deve preservar o caso original para cmdlets que ocorrem posteriormente em um comando ou na linha de comando.

Consulte Também

Diretrizes de desenvolvimento necessárias

Diretrizes de desenvolvimento de consultoria

Escritando um cmdlet do PowerShell Windows