Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
As diretrizes a seguir devem ser seguidas quando você escreve seus cmdlets. Eles são separados em diretrizes para projetar cmdlets e diretrizes para escrever seu código de cmdlet. Se você não seguir essas diretrizes, seus cmdlets poderão falhar e seus usuários poderão ter uma experiência ruim quando usarem seus cmdlets.
Neste tópico
Diretrizes de design
Diretrizes de código
Diretrizes de design
As diretrizes a seguir devem ser seguidas ao projetar 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 Design que se aplique à sua situação, certifique-se de examinar as diretrizes do Código para obter diretrizes semelhantes.
Usar apenas verbos aprovados (RD01)
O verbo especificado no atributo Cmdlet deve vir do conjunto reconhecido de verbos fornecido pelo Windows PowerShell. Não deve ser um dos sinónimos proibidos. Use as cadeias de caracteres constantes definidas pelas enumerações a seguir para especificar verbos de cmdlet:
Para obter mais informações sobre os nomes de verbos aprovados, consulte Cmdlet Verbs.
Os usuários precisam de um conjunto de nomes de cmdlets detetáveis e esperados. Use o verbo apropriado para que o usuário possa fazer uma avaliação rápida do que um cmdlet faz e descobrir facilmente os recursos do sistema. Por exemplo, o seguinte comando de linha de comando obtém uma lista de todos os comandos no sistema cujos nomes começam com "Start": Get-Command Start-*. Use os substantivos em seus cmdlets para diferenciá-los de outros cmdlets. O substantivo indica o recurso no qual a operação será executada. A operação em si é representada pelo verbo.
Nomes de cmdlet: caracteres que não podem ser usados (RD02)
Ao nomear cmdlets, não use nenhum dos seguintes caracteres especiais.
| Personagem | Nome |
|---|---|
| # | sinal numérico |
| , | vírgula |
| () | parênteses |
| {} | aparelhos ortodônticos |
| [] | parênteses |
| & | E comercial |
| - | hífen Nota: O hífen pode ser usado para separar o verbo do substantivo, mas não pode ser usado dentro do substantivo ou dentro do verbo. |
| / | marca de barra |
| \ | barra invertida |
| $ | cifrão |
| ^ | caret |
| ; | ponto e vírgula |
| : | cólon |
| " | aspas duplas |
| ' | aspas simples |
| <> | colchetes angulares |
| | | barra vertical |
| ? | ponto de interrogação |
| @ | no sinal |
| ` | carrapato de volta (acento grave) |
| * | asterisco |
| % | sinal de percentagem |
| + | sinal de mais |
| = | sinal de igual |
| ~ | til |
Nomes de parâmetros que não podem ser usados (RD03)
O Windows PowerShell fornece um conjunto comum de parâmetros para todos os cmdlets, além de parâmetros adicionais que são adicionados em situações específicas. Ao projetar seus próprios cmdlets, você não pode usar os seguintes nomes: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction e Verbose. Para obter mais informações sobre esses parâmetros, consulte Common Parameter Names.
Pedidos de confirmação de suporte (RD04)
Para cmdlets que executam uma operação que modifica o sistema, eles devem chamar o método System.Management.Automation.Cmdlet.ShouldProcess* para solicitar confirmação e, em casos especiais, chamar o System.Management.Automation.Cmdlet.ShouldContinue* método. (O método System.Management.Automation.Cmdlet.ShouldContinue* deve ser chamado somente depois que o método System.Management.Automation.Cmdlet.ShouldProcess* for chamado.)
Para fazer essas chamadas, o cmdlet deve especificar que dá suporte a solicitações de confirmação definindo a palavra-chave SupportsShouldProcess do atributo Cmdlet. Para obter mais informações sobre como definir esse atributo, consulte Cmdlet Attribute Declaration.
Observação
Se o atributo Cmdlet da classe de cmdlet indicar que o cmdlet oferece suporte a chamadas para o método System.Management.Automation.Cmdlet.ShouldProcess* e o cmdlet não conseguir fazer a chamada para o método System.Management.Automation.Cmdlet.ShouldProcess*, o usuário poderá modificar o sistema inesperadamente.
Use o System.Management.Automation.Cmdlet.ShouldProcess* método para qualquer modificação do sistema. Uma preferência do usuário e o parâmetro WhatIf controlam o método System.Management.Automation.Cmdlet.ShouldProcess*. Por outro lado, a chamada de System.Management.Automation.Cmdlet.ShouldContinue* do executa uma verificação adicional de modificações potencialmente perigosas. Este método não é controlado por qualquer preferência do usuário ou o parâmetro WhatIf. Se o cmdlet chamar o System.Management.Automation.Cmdlet.ShouldContinue* método, ele deverá ter um parâmetro Force que ignore as chamadas para esses dois métodos e que prossiga com a operação. Isso é importante porque permite que seu cmdlet seja usado em hosts e scripts não interativos.
Se seus cmdlets oferecerem suporte a essas chamadas, o usuário poderá determinar se a ação deve realmente ser executada. Por exemplo, o cmdlet Stop-Process chama o método System.Management.Automation.Cmdlet.ShouldContinue* antes de parar um conjunto de processos críticos, incluindo os processos System, Winlogon e Spoolsv.
Para obter mais informações sobre como dar suporte a esses métodos, consulte Solicitando confirmação.
Parâmetro de força de suporte para sessões interativas (RD05)
Se o cmdlet for usado interativamente, sempre forneça um parâmetro Force para substituir as ações interativas, como prompts ou linhas de entrada de leitura). Isso é importante porque permite que seu cmdlet seja usado em hosts e scripts não interativos. Os seguintes métodos podem ser implementados por um host interativo.
System.Management.Automation.Host.PSHostUserInterface.Prompt*
System.Management.Automation.Host.PSHostUserInterface.PromptForChoice
System.Management.Automation.Host.IHostUISupportsMultipleChoiceSelection.PromptForChoice
System.Management.Automation.Host.PSHostUserInterface.PromptForCredential*
System.Management.Automation.Host.PSHostUserInterface.ReadLine*
System.Management.Automation.Host.PSHostUserInterface.ReadLineAsSecureString*
Objetos de saída de documento (RD06)
O Windows PowerShell usa os objetos que são gravados no pipeline. Para que os usuários aproveitem os objetos retornados por cada cmdlet, você deve documentar os objetos retornados e para que os membros desses objetos retornados são usados.
Diretrizes de código
As diretrizes a seguir devem ser seguidas ao escrever o código do cmdlet. 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.
Derivar das classes Cmdlet ou PSCmdlet (RC01)
Um cmdlet deve derivar do System.Management.Automation.Cmdlet ou System.Management.Automation.PSCmdlet classe base. Os cmdlets derivados da classe System.Management.Automation.Cmdlet não dependem do tempo de execução do Windows PowerShell. Eles podem ser chamados diretamente de qualquer linguagem do Microsoft .NET Framework. Os cmdlets derivados da classe System.Management.Automation.PSCmdlet dependem do tempo de execução do Windows PowerShell. Portanto, eles são executados dentro de um espaço de execução.
Todas as classes de cmdlet que você implementar devem ser classes públicas. Para obter mais informações sobre essas classes de cmdlet, consulte Visão geral do cmdlet .
Especificar o atributo do cmdlet (RC02)
Para que um cmdlet seja reconhecido pelo Windows PowerShell, sua classe .NET Framework deve ser decorada com o atributo Cmdlet. Este atributo especifica os seguintes recursos do cmdlet.
O par verbo-e-substantivo que identifica o cmdlet.
O conjunto de parâmetros padrão que é usado quando vários conjuntos de parâmetros são especificados. O conjunto de parâmetros padrão é usado quando o Windows PowerShell não tem informações suficientes para determinar qual conjunto de parâmetros usar.
Indica se o cmdlet oferece suporte a chamadas para o método System.Management.Automation.Cmdlet.ShouldProcess*. Esse método exibe uma mensagem de confirmação para o usuário antes que o cmdlet faça uma alteração no sistema. Para obter mais informações sobre como as solicitações de confirmação são feitas, consulte Solicitando confirmação.
Indique o nível de impacto (ou gravidade) da ação associada à mensagem de confirmação. Na maioria dos casos, o valor padrão de Medium deve ser usado. Para obter mais informações sobre como o nível de impacto afeta as solicitações de confirmação exibidas ao usuário, consulte Solicitando confirmação.
Para obter mais informações sobre como declarar o atributo cmdlet, consulte CmdletAttribute Declaration.
Substituir um método de processamento de entrada (RC03)
Para que o cmdlet participe do ambiente do Windows PowerShell, ele deve substituir pelo menos um dos seguintes métodos de processamento de entrada .
System.Management.Automation.Cmdlet.BeginProcessing Esse método é chamado uma vez e é usado para fornecer funcionalidade de pré-processamento.
System.Management.Automation.Cmdlet.ProcessRecord Esse método é chamado várias vezes e é usado para fornecer funcionalidade registro a registro.
System.Management.Automation.Cmdlet.EndProcessing Esse método é chamado uma vez e é usado para fornecer funcionalidade de pós-processamento.
Especifique o atributo OutputType (RC04)
O atributo OutputType (introduzido no Windows PowerShell 2.0) especifica o tipo .NET Framework que seu cmdlet retorna ao pipeline. Ao especificar o tipo de saída de seus cmdlets, você torna os objetos retornados pelo cmdlet mais detetáveis por outros cmdlets. Para obter mais informações sobre como decorar a classe de cmdlet com esse atributo, consulte OutputType Attribute Declaration.
Não reter identificadores para objetos de saída (RC05)
Seu cmdlet não deve reter nenhum identificador para os objetos que são passados para o System.Management.Automation.Cmdlet.WriteObject* método. Esses objetos são passados para o próximo cmdlet no pipeline ou são usados por um script. Se você retiver as alças para os objetos, duas entidades serão proprietárias de cada objeto, o que causa erros.
Manipular erros de forma robusta (RC06)
Um ambiente de administração deteta inerentemente e faz alterações importantes no sistema que você está administrando. Portanto, é vital que os cmdlets manipulem os erros corretamente. Para obter mais informações sobre registros de erros, consulte Relatório de Erros do Windows PowerShell.
Quando um erro impede que um cmdlet continue a processar mais registros, trata-se de um erro de encerramento. O cmdlet deve chamar o System.Management.Automation.Cmdlet.ThrowTerminatingError* método que faz referência a um objeto System.Management.Automation.ErrorRecord. Se uma exceção não for detetada pelo cmdlet, o próprio tempo de execução do Windows PowerShell lançará um erro de encerramento que contém menos informações.
Para um erro não terminativo que não interrompa a operação no próximo registro proveniente do pipeline (por exemplo, um registro produzido por um processo diferente), o cmdlet deve chamar o System.Management.Automation.Cmdlet.WriteError* método que faz referência a um objeto System.Management.Automation.ErrorRecord. Um exemplo de um erro não terminativo é o erro que ocorre se um determinado processo não for interrompido. Chamar o System.Management.Automation.Cmdlet.WriteError* método permite que o usuário execute consistentemente as ações solicitadas e retenha as informações para ações específicas que falham. Seu cmdlet deve lidar com cada registro da forma mais independente possível.
O objeto System.Management.Automation.ErrorRecord referenciado pelos System.Management.Automation.Cmdlet.ThrowTerminatingError* e métodos de System.Management.Automation.Cmdlet.WriteError* requer uma exceção em seu núcleo. Siga as diretrizes de design do .NET Framework ao determinar a exceção a ser usada. Se o erro for semanticamente igual a uma exceção existente, use essa exceção ou derive dessa exceção. Caso contrário, derive uma nova hierarquia de exceção ou exceção diretamente do tipo de System.Exception.
Um objeto System.Management.Automation.ErrorRecord também requer uma categoria de erro que agrupa erros para o usuário. O usuário pode exibir erros com base na categoria definindo o valor da variável de shell $ErrorView como CategoryView. As categorias possíveis são definidas pelo System.Management.Automation.ErrorCategory enumeração.
Se um cmdlet criar um novo thread e se o código em execução nesse thread gerar uma exceção sem tratamento, o Windows PowerShell não detetará o erro e encerrará o processo.
Se um objeto tiver código em seu destruidor que cause uma exceção sem tratamento, o Windows PowerShell não detetará o erro e encerrará o processo. Isso também ocorre se um objeto chama métodos Dispose que causam uma exceção não tratada.
Usar um módulo do Windows PowerShell para implantar seus cmdlets (RC07)
Crie um módulo do Windows PowerShell para empacotar e implantar seus cmdlets. O suporte para módulos é introduzido no Windows PowerShell 2.0. Você pode usar os assemblies que contêm suas classes de cmdlet diretamente como arquivos de módulo binário (isso é muito útil ao testar seus cmdlets) ou pode criar um manifesto de módulo que faça referência aos assemblies de cmdlet. (Você também pode adicionar assemblies de snap-in existentes ao usar módulos.) Para obter mais informações sobre módulos, consulte Escrevendo um módulo do Windows PowerShell.
Ver também
Orientações de desenvolvimento fortemente encorajadas
Colabore connosco no GitHub
A origem deste conteúdo pode ser encontrada no GitHub, onde também pode criar e rever problemas e pedidos Pull. Para mais informações, consulte o nosso guia do contribuidor.
