Diretrizes de Desenvolvimento Consultivas

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

Diretrizes de design

As diretrizes a seguir devem ser consideradas ao projetar 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.

Suporte a um parâmetro InputObject (AD01)

Como o Windows PowerShell funciona diretamente com objetos do Microsoft .NET Framework, geralmente está disponível um objeto do .NET Framework que corresponde exatamente ao tipo que o usuário precisa para executar uma operação específica. InputObject é o nome padrão para um parâmetro que usa tal objeto como entrada. Por exemplo, o cmdlet de exemplo Stop-Proc no Tutorial StopProc define um InputObject parâmetro do tipo Process que suporta a 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 oferecer 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 oferece 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 remover o arquivo, o uso do parâmetro Force simplificará 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 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 ambos quando uma credencial completa não é fornecida diretamente. Para obter mais informações sobre o atributo Credential, consulte Declaração de atributo de credencial.

Suporte a parâmetros de codificação (AD04)

Se o cmdlet ler ou gravar texto em ou a partir de um formulário binário, como gravar ou ler de um arquivo em um sistema de arquivos, o cmdlet deverá ter um parâmetro Encoding que especifique como o texto é codificado no formato binário.

Cmdlets de teste devem retornar um booleano (AD05)

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

Diretrizes de código

As diretrizes a seguir devem ser consideradas ao escrever o código do cmdlet. Quando você encontrar uma diretriz que se aplique à sua situação, certifique-se de olhar para as diretrizes de design para diretrizes semelhantes.

Siga as convenções de nomenclatura de classe de cmdlet (AC01)

Seguindo convenções de nomenclatura padrão, você torna seus cmdlets mais detetá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 do cmdlet para corresponder ao nome do cmdlet

Quando você nomeia a classe do .NET Framework que implementa um cmdlet, nomeie a classe <Verb><Noun>Command, onde você substitui os espaços reservados e <Verb> pelo <Noun> verbo e 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 entradas 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 tenham a chance de iniciar seu processamento.

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

Substitua o método System.Management.Automation.Cmdlet.StopProcessing para que seu cmdlet possa manipular o sinal de parada. Alguns cmdlets levam muito tempo para concluir sua operação e permitem que um longo tempo passe entre chamadas para o tempo de execução do Windows PowerShell, como quando o cmdlet bloqueia o thread em chamadas RPC de longa execução. 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 feedback que podem levar muito tempo para serem concluídos. Para esses casos, talvez seja necessário enviar um sinal de parada 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 , talvez seja necessário eliminar objetos adicionais. 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 tempo de execução 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 de sua 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 tempo de execução 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, em seguida, reidratados no computador servidor. Os tipos a seguir são amigáveis à 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 reidratáveis integrados:

• PSPrimitiveDictionary
• Parâmetro de Comutação
• PSListModifier
• PSCredential
• IPAddress, MailAddress
• CulturaInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Outros tipos:

• SecureString
• Contentores (listas e dicionários do tipo acima)

Usar SecureString para dados confidenciais (AC06)

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

Embora o .NET não recomende o uso do SecureString para novos desenvolvimentos, o PowerShell continua a oferecer suporte à classe SecureString para compatibilidade com versões anteriores. Usar um SecureString ainda é mais seguro do que usar uma cadeia de caracteres de texto simples. O PowerShell ainda depende do tipo SecureString para evitar a exposição acidental do conteúdo ao console ou em logs. Use o SecureString com cuidado, porque ele pode ser facilmente convertido em uma cadeia de texto simples. Para obter uma discussão completa sobre como usar SecureString, consulte a documentação da classe System.Security.SecureString.

Ver também

Diretrizes de desenvolvimento necessárias

Orientações de desenvolvimento fortemente encorajadas

Escrevendo um cmdlet do Windows PowerShell