Compartilhar via

Diretrizes de Desenvolvimento Fortemente Recomendadas

Esta seção descreve as diretrizes que você deve seguir ao escrever seus cmdlets. As diretrizes estão divididas em diretrizes para desenvolver cmdlets e diretrizes para escrever o código do seu cmdlet. Você pode achar que essas diretrizes não são aplicáveis a todos os cenários. No entanto, se estas diretrizes se aplicarem e o utilizador não as seguir, os seus utilizadores poderão ter uma experiência ruim ao utilizarem os seus cmdlets.

Diretrizes de design

As diretrizes a seguir devem ser seguidas ao conceber cmdlets para garantir uma experiência de utilizador consistente no uso dos seus cmdlets e dos outros. Quando você encontrar uma diretriz de Design que se aplique à sua situação, certifique-se de examinar as diretrizes do Código para obter diretrizes semelhantes.

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

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

Para melhorar 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 cmdlets, mesmo quando é provável que um cmdlet atue sobre mais de um item.

Usar Caso Pascal para nomes de Cmdlet (SD02)

Use a convenção Pascal Case para nomes de parâmetros. Em outras palavras, coloque em maiúscula a primeira letra do verbo e todos os termos usados no substantivo. Por exemplo, "Clear-ItemProperty".

Diretrizes de projeto de parâmetros (SD03)

Um cmdlet precisa de parâmetros que recebam os dados nos quais ele deve operar e parâmetros que indiquem informações que são 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âmetros padrão

Seu cmdlet deve usar nomes de parâmetros padrão para que o usuário possa determinar rapidamente o que um determinado parâmetro significa. Se for necessário um nome mais específico, 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 Cmdlet Parameter Name and Functionality Guidelines.

Usar nomes de parâmetros singulares

Evite usar nomes plurais para parâmetros cujo valor é um único elemento. Isso inclui parâmetros que usam matrizes ou listas porque o usuário pode fornecer uma matriz ou lista com apenas um elemento.

Nomes de parâmetros plurais devem ser usados apenas 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.

Usar Pascal Case para nomes de parâmetros

Use Pascal Case para os nomes de parâmetros. Em outras palavras, coloque em maiúscula 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 maiúscula correta. Os seguintes nomes de parâmetros usam maiúsculas incorretas:

  • errorAction
  • erroraction

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

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

  • Defina um tipo de enumeração (ou use um tipo de enumeração existente) que especifique 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 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 do .NET Framework para grupos de parâmetros padrão, como os "parâmetros de atividade".

Usar Strongly-Typed tipos do .NET Framework

Os parâmetros devem ser definidos como tipos do .NET Framework para fornecer uma melhor validação de parâmetros. Por exemplo, os parâmetros que são 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, exceto as de texto de forma livre.

Usar tipos de parâmetros 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 um tipo System.Int16 para um cmdlet, não torne o Process parâmetro para outro cmdlet um tipo System.Uint16 .

Parâmetros que levam verdadeiro e falso

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

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 3º valor "não especificado" normalmente ocorre quando o cmdlet pode modificar uma propriedade booleana de um objeto. Neste caso, "não especificado" significa não alterar o valor atual do imóvel.

Matrizes de suporte para parâmetros

Freqüentemente, os usuários devem executar a mesma operação contra 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 "sumidouros" para objetos e não retornam um resultado. Esses cmdlets devem 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 oferecer suporte a um PassThru parâmetro.

Conjuntos de parâmetros de suporte

Um cmdlet destina-se a realizar uma única finalidade. No entanto, freqüentemente há 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 oferecer suporte a todas as representações razoáveis de seus destinos. Normalmente, o cmdlet satisfaz esse requisito especificando conjuntos de parâmetros (referidos 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 Cmdlet Parameter Sets.

Ao 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 com maior probabilidade de serem usados em uma sessão interativa do Windows PowerShell. Para obter mais informações sobre como declarar o atributo Cmdlet , consulte Declaração CmdletAttribute.

Fornecer feedback ao usuário (SD04)

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

O tempo de execução do Windows PowerShell permite que um usuário especifique como manipular a saída de cada chamada para o Write método 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 estiver prestes a executar uma operação que pode ter um resultado não intencional. Por exemplo, um cmdlet deve chamar esse método se estiver prestes a substituir um arquivo somente leitura.

Um cmdlet deve chamar o método System.Management.Automation.Cmdlet.WriteVerbose quando o usuário precisar de algum detalhe 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 precisa entender o que corrompeu a operação do 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 WriteProgress para operações 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 oferecer suporte a relatórios de progresso por meio de chamadas periódicas para o método System.Management.Automation.Cmdlet.WriteProgress .

Usar as interfaces do anfitrião

Ocasionalmente, um cmdlet deve se comunicar diretamente com o usuário em vez de usar os vários métodos Write ou Should suportados pela 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* . Esta propriedade suporta 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 interface gráfica do usuário (GUI), ele não deve ignorar o host usando a propriedade System.Management.Automation.PSCmdlet.Host* . Um exemplo de cmdlet projetado para gerar uma GUI é o cmdlet Out-GridView .

Observação

Os cmdlets não devem usar a API System.Console .

Criar um arquivo de ajuda do cmdlet (SD05)

Para cada assemblage de cmdlet, crie um ficheiro 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 do 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 de usuário consistente entre o uso de seus cmdlets e outros cmdlets. Quando você encontrar uma diretriz de código que se aplique à sua situação, certifique-se de examinar 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 de cmdlet decorada com o atributo Parameter . Os parâmetros não precisam ser membros estáticos da classe derivada do .NET Framework para o cmdlet. Para obter mais informações sobre como declarar o atributo Parameter , consulte Parameter Attribute Declaration.

Suporte para Caminhos do Windows PowerShell

O caminho do Windows PowerShell é o mecanismo para normalizar o acesso a namespaces. Ao atribuir um caminho do Windows PowerShell a um parâmetro no cmdlet, o utilizador pode definir uma "unidade" personalizada que funciona como um atalho para um caminho específico. Quando um utilizador designa essa unidade, os dados armazenados, tais como os dados no Registo, podem ser utilizados de forma 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. Caso haja suporte para mais de uma unidade, o tipo deverá ser um array. O nome do parâmetro deve ser Path, com um alias de PSPath. Além disso, o parâmetro Path deve suportar 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 deve aceitar a entrada de caminho do Windows PowerShell e o cmdlet deve usar a propriedade System.Management.Automation.SessionState.Path para converter os caminhos do Windows PowerShell em caminhos que o sistema de arquivos reconhece. Os mecanismos específicos incluem os seguintes métodos:

Se os dados que o cmdlet lê ou grava forem 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 . Estes mecanismos permitem que outros armazenamentos de dados participem na leitura e escrita de dados.

Suporte a caracteres curinga

Um cmdlet deve oferecer 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 StopProc define um Name parâmetro para manipular cadeias de caracteres que representam nomes de processos. Este parâmetro suporta 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 oferecer 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 oferecer suporte a uma matriz porque o usuário está definindo apenas um único local. Nesse caso, o cmdlet ainda oferece suporte a caracteres curinga, mas força a resolução para um único local.

Para obter mais informações sobre padrões de caracteres curinga, consulte Suportando 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 Types.ps1xml do Windows PowerShell como 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 trabalhem com seu objeto de maneira consistente.

Definir ObjectMembers a serem usados como parâmetros

Se estiveres a criar um objeto para um cmdlet, assegura-te de que os seus membros sejam mapeados diretamente para os parâmetros dos cmdlets que o usarão. Esse mapeamento permite que o objeto seja facilmente enviado para o pipeline e seja passado de um cmdlet para outro.

Objetos pré-existentes da .NET Framework que são devolvidos por cmdlets frequentemente carecem de alguns membros importantes ou convenientes necessários para o desenvolvedor de scripts ou usuário. Esses membros ausentes podem ser particularmente importantes para exibição e para criar os nomes de membros 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>. Tipos.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 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 facilmente canalizados para vários 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 ficheiro <YourProductName>.Format.ps1xml personalizado para esse objeto.

Suporte à entrada de um pipeline bem definido (SC02)

Implementar para o meio de um pipeline

Implemente um cmdlet assumindo 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 supor que o Get-Process cmdlet, porque gera dados, é usado apenas como o primeiro cmdlet em um pipeline. No entanto, como este cmdlet foi projetado para o meio de uma linha de comando, ele permite que cmdlets ou dados anteriores na linha de comando especificarem os processos a recuperar.

Entrada de suporte do pipeline

Em cada conjunto de parâmetros para um cmdlet, inclua pelo menos um parâmetro que ofereça suporte à entrada a partir do 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 entrada do pipeline se o atributo Parameter incluir a palavra-chave ValueFromPipeline, o atributo ValueFromPipelineByPropertyName palavra-chave, ou ambas as palavras-chave na sua declaração. Se nenhum dos parâmetros num conjunto de parâmetros suportar as palavras-chave ValueFromPipeline ou ValueFromPipelineByPropertyName, o cmdlet não poderá ser colocado de forma significativa após outro cmdlet porque 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 . O Windows PowerShell chama esse método várias vezes, uma para cada registro enviado ao seu cmdlet.

Gravar os Registos Únicos no Pipeline (SC03)

Quando um cmdlet retorna objetos, ele deve gravar os objetos imediatamente como eles são gerados. O cmdlet não deve mantê-los para armazená-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.

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

Por padrão, o próprio Windows PowerShell não diferencia maiúsculas de minúsculas. No entanto, como lida com muitos sistemas preexistentes, o Windows PowerShell preserva casos para facilidade de operação e compatibilidade. Em outras palavras, se um caractere for fornecido em letras maiúsculas, o Windows PowerShell o manterá em letras maiúsculas. Para que os sistemas funcionem bem, um cmdlet precisa seguir essa convenção. Se possível, deve funcionar sem distinção entre maiúsculas e minúsculas. No entanto, ele deve preservar o caso original para cmdlets que ocorrem posteriormente em um comando ou no pipeline.

Ver também

Diretrizes de desenvolvimento necessárias

Diretrizes de Desenvolvimento Consultivo

Escrevendo um cmdlet do Windows PowerShell

  • Last updated on