Diretrizes para desenvolvimento de consultoria

Esta seção descreve as diretrizes que você deve considerar para garantir um bom desenvolvimento e experiências do usuário. Às vezes eles podem se aplicar, e às vezes eles podem não.

Diretrizes de design

As diretrizes a seguir devem ser consideradas ao projetar cmdlets. Ao encontrar uma diretriz de Design que se aplique à sua situação, examine as diretrizes de código para obter diretrizes semelhantes.

Suporte a um parâmetro InputObject (AD01)

Como o Windows PowerShell funciona diretamente com objetos do Microsoft .NET Framework, um objeto .NET Framework geralmente está disponível que corresponde exatamente ao tipo que o usuário precisa para executar uma operação específica. InputObject é o nome padrão de um parâmetro que usa um objeto como entrada. Por exemplo, o cmdlet de exemplo Stop-Proc no Tutorial do StopProc define um InputObject parâmetro do tipo Processo que dá suporte à entrada do pipeline. O usuário pode obter um conjunto de objetos de processo, manipulá-los para selecionar os objetos exatos a serem interrompidos e, em seguida, passá-los diretamente para o Stop-Proc cmdlet.

Suporte ao parâmetro Force (AD02)

Ocasionalmente, um cmdlet precisa proteger o usuário de executar uma operação solicitada. Esse cmdlet deve dar suporte a um parâmetro Force para permitir que o usuário substitua essa proteção se o usuário tiver permissões para executar a operação.

Por exemplo, o cmdlet Remove-Item normalmente não remove um arquivo somente leitura. No entanto, esse cmdlet dá suporte a um parâmetro Force para que um usuário possa forçar a remoção de um arquivo somente leitura. Se o usuário já tiver permissão para modificar o atributo somente leitura e o usuário remover o arquivo, o uso do parâmetro Force simplifica a operação. No entanto, se o usuário não tiver permissão para remover o arquivo, o parâmetro Force não terá efeito.

Manipular credenciais por meio do Windows PowerShell (AD03)

Um cmdlet deve definir um Credential parâmetro para representar as credenciais. Esse parâmetro deve ser do tipo System.Management.Automation.PSCredential e deve ser definido usando uma declaração de atributo credential. Esse suporte solicita automaticamente ao usuário o nome de usuário, a senha ou para ambos quando uma credencial completa não é fornecida diretamente. Para obter mais informações sobre o atributo Credential, consulte a Declaração de Atributo de Credencial.

Parâmetros de codificação de suporte (AD04)

Se o cmdlet ler ou gravar texto de ou para um formulário binário, como gravar ou ler de um arquivo em um sistema de arquivos, o cmdlet precisará ter um parâmetro de codificação que especifique como o texto é codificado no formulário binário.

Os cmdlets de teste devem retornar um booliano (AD05)

Os cmdlets que executam testes em seus recursos devem retornar um tipo System.Boolean para o pipeline para que possam ser usados em expressões condicionais.

Diretrizes de código

As diretrizes a seguir devem ser consideradas ao escrever código de cmdlet. Ao encontrar uma diretriz que se aplique à sua situação, examine as diretrizes de Design para obter diretrizes semelhantes.

Siga as Convenções de Nomenclatura de Classe de Cmdlet (AC01)

Seguindo as convenções de nomenclatura padrão, você torna seus cmdlets mais detectáveis e ajuda o usuário a entender exatamente o que os cmdlets fazem. Essa prática é particularmente importante para outros desenvolvedores que usam o Windows PowerShell porque os cmdlets são tipos públicos.

Definir um cmdlet no namespace correto

Normalmente, você define a classe para um cmdlet em um namespace do .NET Framework que acrescenta .Commands ao namespace que representa o produto no qual o cmdlet é executado. Por exemplo, os cmdlets incluídos no Windows PowerShell são definidos no Microsoft.PowerShell.Commands namespace.

Nomeie a classe cmdlet para corresponder ao nome do cmdlet

Quando você nomear a classe .NET Framework que implementa um cmdlet, nomeie a classe<Verb><Noun>Command, em que você substitui os espaços reservados e <Verb> o <Noun> verbo e o substantivo usados para o nome do cmdlet. Por exemplo, o cmdlet Get-Process é implementado por uma classe chamada GetProcessCommand.

Se nenhuma entrada de pipeline substituir o método BeginProcessing (AC02)

Se o cmdlet não aceitar a entrada do pipeline, o processamento deverá ser implementado no método System.Management.Automation.Cmdlet.BeginProcessing . O uso desse método permite que o Windows PowerShell mantenha a ordenação entre cmdlets. O primeiro cmdlet no pipeline sempre retorna seus objetos antes que os cmdlets restantes no pipeline obtenham a chance de iniciar o processamento.

Para lidar com solicitações de parada, substitua o método StopProcessing (AC03)

Substitua o método System.Management.Automation.Cmdlet.StopProcessing para que seu cmdlet possa lidar com o sinal de parada. Alguns cmdlets levam muito tempo para concluir a operação e permitem que um longo tempo passe entre chamadas para o runtime do Windows PowerShell, como quando o cmdlet bloqueia o thread em chamadas RPC de execução prolongada. Isso inclui cmdlets que fazem chamadas para o método System.Management.Automation.Cmdlet.WriteObject , para o método System.Management.Automation.Cmdlet.WriteError e para outros mecanismos de comentários que podem levar muito tempo para serem concluídos. Para esses casos, talvez o usuário precise enviar um sinal de interrupção para esses cmdlets.

Implementar a INTERFACE IDisposable (AC04)

Se o cmdlet tiver objetos que não são descartados (gravados no pipeline) pelo método System.Management.Automation.Cmdlet.ProcessRecord , seu cmdlet poderá exigir descarte adicional de objetos. Por exemplo, se o cmdlet abrir um identificador de arquivo em seu método System.Management.Automation.Cmdlet.BeginProcessing e mantiver o identificador aberto para uso pelo método System.Management.Automation.Cmdlet.ProcessRecord , esse identificador deverá ser fechado no final do processamento.

O runtime do Windows PowerShell nem sempre chama o método System.Management.Automation.Cmdlet.EndProcessing . Por exemplo, o método System.Management.Automation.Cmdlet.EndProcessing pode não ser chamado se o cmdlet for cancelado no meio da operação ou se ocorrer um erro de encerramento em qualquer parte do cmdlet. Portanto, a classe .NET Framework para um cmdlet que requer limpeza de objeto deve implementar o padrão de interface System.IDisposable completo, incluindo o finalizador, para que o runtime do Windows PowerShell possa chamar os métodos System.Management.Automation.Cmdlet.EndProcessing e System.IDisposable.Dispose* no final do processamento.

Usar tipos de parâmetros amigáveis à serialização (AC05)

Para dar suporte à execução do cmdlet em computadores remotos, use tipos que podem ser serializados no computador cliente e reidratados no computador do servidor. Os tipos a seguir são amigáveis para serialização.

Tipos primitivos:

• Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 e UInt64.
• Boolean, Guid, Byte[], TimeSpan, DateTime, Uri e Version.
• Char, String, XmlDocument.

Tipos rehidratáveis internos:

• PSPrimitiveDictionary
• SwitchParameter
• PSListModifier
• PSCredential
• IPAddress, MailAddress
• CultureInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Outros tipos:

• SecureString
• Contêineres (listas e dicionários do tipo acima)

Usar SecureString para dados confidenciais (AC06)

Ao lidar com dados confidenciais, sempre use o tipo de dados System.Security.SecureString . Isso pode incluir a entrada de pipeline para parâmetros, bem como o retorno de dados confidenciais para o pipeline.

Embora o .NET recomende não usar SecureString para novo desenvolvimento, o PowerShell continua a dar suporte à classe SecureString para compatibilidade com versões anteriores. Usar a classe SecureString ainda é mais seguro do que usar uma cadeia de texto sem formatação. O PowerShell ainda depende do tipo SecureString para evitar expor acidentalmente o conteúdo ao console ou nos logs. Use SecureString com cuidado, pois ele pode ser facilmente convertido em uma cadeia de caracteres de texto sem formatação. Para saber detalhes completos sobre como usar a SecureString, consulte a documentação da classe System.Security.SecureString.

Consulte Também

diretrizes de desenvolvimento necessárias

diretrizes de desenvolvimento altamente incentivadas

gravando um cmdlet do Windows PowerShell