Diretrizes para desenvolvimento necessárias

  • Artigo

As diretrizes a seguir devem ser seguidas quando você escreve seus cmdlets. Eles são separados em diretrizes para criar cmdlets e diretrizes para escrever seu código de cmdlet. Se você não seguir essas diretrizes, seus cmdlets poderão falhar e os 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 criar cmdlets para garantir uma experiência de usuário consistente entre o uso de seus cmdlets e outros cmdlets. Ao encontrar uma diretriz de Design que se aplica à sua situação, não se esqueça de ver as Diretrizes de código para diretrizes semelhantes.

Usar somente verbos aprovados (RD01)

O verbo especificado no atributo Cmdlet deve vir do conjunto reconhecido de verbos fornecido por Windows PowerShell. Ele 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 verbo aprovados, consulte Verbos do cmdlet.

Os usuários precisam de um conjunto de nomes de cmdlets que podem ser descobertos 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 comando de linha de comando a seguir 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 diferenciar seus cmdlets de outros cmdlets. O substantivo indica o recurso no qual a operação será executada. A própria operação é 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.

Caractere Nome
# sinal de número
, vírgula
() parênteses
{} Chaves
[] colchetes
& Comercial
- Hífen Observação: 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.
/ Barra
\ backslash
$ cifrão
^ sinal de interpolação
; ponto e vírgula
: Cólon
" aspas duplas
' aspas simples
<> colchetes angulares
| barra vertical
? ponto de interrogação
@ no sinal
` tique para trás (acento grave)
* asterisco
% sinal de porcentagem
+ Sinal
= sinal de igual
~ Til

Nomes de parâmetros que não podem ser usados (RD03)

Windows PowerShell fornece um conjunto comum de parâmetros para todos os cmdlets mais parâmetros adicionais que são adicionados em situações específicas. Ao criar 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 Nomes de parâmetro comuns.

Solicitações 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 método System.Management.Automation.Cmdlet.ShouldContinue*. (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 ele dá suporte a solicitações de confirmação definindo a SupportsShouldProcess palavra-chave do atributo Cmdlet. Para obter mais informações sobre como definir esse atributo, consulte Declaração de atributo de cmdlet.

Observação

Se o atributo Cmdlet da classe cmdlet indicar que o cmdlet dá 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 método System.Management.Automation.Cmdlet.ShouldProcess* para qualquer modificação do sistema. Uma preferência do usuário e o WhatIf parâmetro controlam o método System.Management.Automation.Cmdlet.ShouldProcess*. Por outro lado, a chamada System.Management.Automation.Cmdlet.ShouldContinue* executa uma verificação adicional para modificações potencialmente perigosas. Esse método não é controlado por nenhuma preferência do usuário ou pelo WhatIf parâmetro . Se o cmdlet chamar o método System.Management.Automation.Cmdlet.ShouldContinue*, ele deverá ter um parâmetro que ignore as chamadas para esses dois métodos e que continue com a Force operação. Isso é importante porque permite que o cmdlet seja usado em scripts e hosts não interativos.

Se os cmdlets deem 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 interromper 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 o cmdlet seja usado em scripts e hosts não interativos. Os métodos a seguir podem ser implementados por um host interativo.

Objetos de saída de documento (RD06)

Windows PowerShell usa os objetos que são gravados no pipeline. Para que os usuários tirem proveito dos objetos que são retornados por cada cmdlet, você deve documentar os objetos que são retornados e deve documentar de que forma os membros desses objetos retornados são usados.

Diretrizes de código

As diretrizes a seguir devem ser seguidas durante a gravação do código de cmdlet. Quando você encontrar uma diretriz de código que se aplica à sua situação, certifique-se de examinar as diretrizes de design para obter diretrizes semelhantes.

Derive das classes cmdlet ou PSCmdlet (RC01)

Um cmdlet deve ser derivado da classe base System. Management. Automation. cmdlet ou System. Management. Automation. PSCmdlet . os cmdlets que derivam da classe System. Management. Automation. Cmdlet não dependem do tempo de execução Windows PowerShell. eles podem ser chamados diretamente de qualquer linguagem de .NET Framework da Microsoft. os cmdlets que derivam da classe System. Management. Automation. PSCmdlet dependem do tempo de execução Windows PowerShell. Portanto, eles são executados em um runspace.

Todas as classes de cmdlet implementadas devem ser classes públicas. Para obter mais informações sobre essas classes de cmdlet, consulte visão geral do cmdlet.

Especificar o atributo de cmdlet (RC02)

para que um cmdlet seja reconhecido pelo Windows PowerShell, sua classe .NET Framework deve ser decorada com o atributo cmdlet. Esse 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 Windows PowerShell não tem informações suficientes para determinar qual conjunto de parâmetros usar.

  • Indica se o cmdlet dá 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 a severidade) 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 para o usuário, consulte solicitando confirmação.

Para obter mais informações sobre como declarar o atributo de cmdlet, consulte declaração de CmdletAttribute.

Substituir um método de processamento de entrada (RC03)

para que o cmdlet participe do ambiente de 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 de registro por registro.

System. Management. Automation. cmdlet. Endprocessando esse método é chamado uma vez e é usado para fornecer funcionalidade de pós-processamento.

Especificar o atributo OutputType (RC04)

o atributo outputtype (introduzido no Windows PowerShell 2,0) especifica o tipo de .NET Framework que seu cmdlet retorna para o pipeline. Ao especificar o tipo de saída de seus cmdlets, você torna os objetos retornados por seu cmdlet mais detectáveis por outros cmdlets. Para obter mais informações sobre como decorar a classe cmdlet com esse atributo, consulte declaração de atributo OutputType.

Não manter identificadores para objetos de saída (RC05)

O cmdlet não deve reter nenhum identificador para os objetos passados para o método System. Management. Automation. cmdlet. WriteObject * . Esses objetos são passados para o próximo cmdlet no pipeline ou são usados por um script. Se você mantiver os identificadores para os objetos, duas entidades serão proprietárias de cada objeto, o que causará erros.

Tratar erros robustamente (RC06)

Um ambiente de administração detecta inerentemente e faz alterações importantes no sistema que você está administrando. Portanto, é vital que os cmdlets manipulem erros corretamente. para obter mais informações sobre registros de erro, consulte Windows PowerShell relatório de erros.

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 $ErrorView variável shell como CategoryView. As categorias possíveis são definidas pela enumeração System. Management. Automation. ErrorCategory .

  • se um cmdlet criar um novo thread e se o código que está sendo executado nesse thread lançar uma exceção sem tratamento, Windows PowerShell não irá capturar o erro e encerrará o processo.

  • se um objeto tiver código em seu destruidor que causa uma exceção sem tratamento, Windows PowerShell não irá capturar o erro e encerrará o processo. Isso também ocorrerá se um objeto chamar métodos Dispose que causam uma exceção sem tratamento.

usar um módulo Windows PowerShell para implantar seus cmdlets (RC07)

crie um módulo 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 as classes de cmdlet diretamente como arquivos de módulo binário (isso é muito útil ao testar seus cmdlets), ou você pode criar um manifesto de módulo que referencie os 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 Windows PowerShell.

Consulte Também

Diretrizes de desenvolvimento altamente recomendadas

Diretrizes para desenvolvimento de consultoria

Writing a Windows PowerShell Cmdlet (Escrevendo um Cmdlet do Windows PowerShell)