Visão geral do cmdlet
Um cmdlet é um comando leve usado no ambiente do PowerShell. O runtime do PowerShell invoca esses cmdlets no contexto de scripts de automação fornecidos na linha de comando. O runtime do PowerShell também os invoca programaticamente por meio de APIs do PowerShell.
Os cmdlets executam uma ação e normalmente retornam um objeto .NET da Microsoft para o próximo comando no pipeline. Um cmdlet é um único comando que participa da semântica de pipeline do PowerShell. Isso inclui cmdlets binários (C#), funções de script avançadas, CDXML e fluxos de trabalho.
Esta documentação do SDK descreve como criar cmdlets binários escritos em C#. Para obter informações sobre cmdlets baseados em script, consulte:
Para criar um cmdlet binário, você deve implementar uma classe de cmdlet que deriva de uma das duas classes base de cmdlet especializadas. A classe derivada deve:
- Declare um atributo que identifica a classe derivada como um cmdlet.
- Defina propriedades públicas decoradas com atributos que identificam as propriedades públicas como parâmetros de cmdlet.
- Substitua um ou mais dos métodos de processamento de entrada para processar registros.
Você pode carregar o assembly que contém a classe diretamente usando o cmdlet Import-Module ou criar um aplicativo host que carregue o assembly usando a API System.Management.Automation.Runspaces.InitialSessionState. Ambos os métodos fornecem acesso programático e de linha de comando à funcionalidade do cmdlet.
Os seguintes termos são usados com frequência na documentação do cmdlet do PowerShell:
Um atributo .NET usado para declarar uma classe de cmdlet como um cmdlet. Embora o PowerShell use vários outros atributos opcionais, o atributo Cmdlet é necessário. Para obter mais informações sobre esse atributo, consulte de Declaração de Atributo do Cmdlet.
As propriedades públicas que definem os parâmetros que estão disponíveis para o usuário ou para o aplicativo que está executando o cmdlet. Os cmdlets podem ter parâmetros de obrigatórios, nomeados, posicionais e. Os parâmetros de alternância permitem definir parâmetros que são avaliados somente se os parâmetros forem especificados na chamada. Para obter mais informações sobre os diferentes tipos de parâmetros, consulte parâmetros de cmdlet.
Um grupo de parâmetros que pode ser usado no mesmo comando para executar uma ação específica. Um cmdlet pode ter vários conjuntos de parâmetros, mas cada conjunto de parâmetros deve ter pelo menos um parâmetro exclusivo. Um bom design de cmdlet sugere fortemente que o parâmetro exclusivo também seja um parâmetro necessário. Para obter mais informações sobre conjuntos de parâmetros, consulte Conjuntos de Parâmetros do Cmdlet.
Um parâmetro que é adicionado ao cmdlet em runtime. Normalmente, os parâmetros dinâmicos são adicionados ao cmdlet quando outro parâmetro é definido como um valor específico. Para obter mais informações sobre parâmetros dinâmicos, consulte Parâmetros Dinâmicos do Cmdlet.
A classe System.Management.Automation.Cmdlet fornece os seguintes métodos virtuais usados para processar registros. Todas as classes de cmdlet derivadas devem substituir um ou mais dos três primeiros métodos:
- System.Management.Automation.Cmdlet.BeginProcessing: usado para fornecer funcionalidade opcional de pré-processamento único para o cmdlet.
- System.Management.Automation.Cmdlet.ProcessRecord: usado para fornecer funcionalidade de processamento de registro por registro para o cmdlet. O método System.Management.Automation.Cmdlet.ProcessRecord pode ser chamado várias vezes, ou não, dependendo da entrada do cmdlet.
- System.Management.Automation.Cmdlet.EndProcessing: usado para fornecer funcionalidade opcional de pós-processamento único para o cmdlet.
- System.Management.Automation.Cmdlet.StopProcessing: usado para interromper o processamento quando o usuário interrompe o cmdlet de forma assíncrona (por exemplo, pressionando CTRL+C).
Para obter mais informações sobre esses métodos, consulte métodos de processamento de entrada de cmdlet.
Ao implementar um cmdlet, você deve substituir pelo menos um desses métodos de processamento de entrada. Normalmente, o ProcessRecord() é o método que você substitui porque é chamado para cada registro que o cmdlet processa. Por outro lado, o método BeginProcessing() e o método EndProcessing() são chamados uma vez para executar o pré-processamento ou pós-processamento dos registros. Para obter mais informações sobre esses métodos, consulte métodos de processamento de entrada.
O PowerShell permite que você crie cmdlets que solicitam comentários ao usuário antes que o cmdlet faça uma alteração no sistema. Para usar esse recurso, o cmdlet deve declarar que dá suporte ao recurso ShouldProcess quando você declara o atributo Cmdlet e o cmdlet deve chamar os métodos System.Management.Automation.Cmdlet.ShouldProcess e System.Management.Automation.Cmdlet.ShouldContinue métodos de processamento de entrada. Para obter mais informações sobre como dar suporte à funcionalidade de ShouldProcess, consulte Solicitandode Confirmação.
Um grupo lógico de comandos que são tratados como uma única tarefa. A tarefa falhará automaticamente se algum comando no grupo falhar e o usuário tiver a opção de aceitar ou rejeitar as ações executadas na transação. Para participar de uma transação, o cmdlet deve declarar que dá suporte a transações quando o atributo Cmdlet é declarado. O suporte para transações foi introduzido no Windows PowerShell 2.0. Para obter mais informações sobre transações, consulte How to Support Transactions.
Os cmdlets diferem dos comandos em outros ambientes de shell de comando das seguintes maneiras:
- Cmdlets são instâncias de classes .NET; eles não são executáveis autônomos.
- Os cmdlets podem ser criados a partir de apenas uma dúzia de linhas de código.
- Os cmdlets geralmente não fazem sua própria análise, apresentação de erro ou formatação de saída. A análise, a apresentação de erro e a formatação de saída são tratadas pelo runtime do PowerShell.
- Os cmdlets processam objetos de entrada do pipeline, em vez de fluxos de texto, e os cmdlets normalmente entregam objetos como saída para o pipeline.
- Os cmdlets são orientados para registro porque processam um único objeto de cada vez.
O Windows PowerShell dá suporte a cmdlets derivados das duas classes base a seguir.
A maioria dos cmdlets baseia-se em classes .NET derivadas da classe base System.Management.Automation.Cmdlet. Derivar dessa classe permite que um cmdlet use o conjunto mínimo de dependências no runtime do Windows PowerShell. Isso oferece dois benefícios. O primeiro benefício é que os objetos cmdlet são menores e é menos provável que você seja afetado por alterações no runtime do PowerShell. O segundo benefício é que, se for necessário, você pode criar diretamente uma instância do objeto cmdlet e invocá-la diretamente em vez de invocá-la por meio do runtime do PowerShell.
Os cmdlets mais complexos são baseados em classes .NET que derivam da classe base System.Management.Automation.PSCmdlet. Derivar dessa classe oferece muito mais acesso ao runtime do PowerShell. Esse acesso permite que seu cmdlet chame scripts, acesse provedores e acesse o estado atual da sessão. (Para acessar o estado da sessão atual, você obtém e define variáveis e preferências de sessão.) No entanto, derivar dessa classe aumenta o tamanho do objeto cmdlet e significa que o cmdlet está mais firmemente acoplado à versão atual do runtime do PowerShell.
Em geral, a menos que você precise do acesso estendido ao runtime do PowerShell, deverá derivar da classe System.Management.Automation.Cmdlet. No entanto, o runtime do PowerShell tem amplos recursos de log para a execução de cmdlets. Se o modelo de auditoria depender desse log, você poderá impedir a execução do cmdlet de dentro de outro cmdlet derivando da classe System.Management.Automation.PSCmdlet.
O PowerShell define vários atributos .NET que são usados para gerenciar cmdlets e especificar a funcionalidade comum fornecida pelo PowerShell e que pode ser exigida pelo cmdlet. Por exemplo, os atributos são usados para designar uma classe como um cmdlet, especificar os parâmetros do cmdlet e solicitar a validação de entrada para que os desenvolvedores de cmdlet não precisem implementar essa funcionalidade em seu código cmdlet. Para obter mais informações sobre atributos, consulte atributos do PowerShell.
O PowerShell usa um par de nomes verbo e substantivo para nomear cmdlets. Por exemplo, o cmdlet Get-Command incluído no PowerShell é usado para obter todos os cmdlets registrados no shell de comando. O verbo identifica a ação executada pelo cmdlet e o substantivo identifica o recurso no qual o cmdlet executa sua ação.
Esses nomes são especificados quando a classe .NET é declarada como um cmdlet. Para obter mais informações sobre como declarar uma classe .NET como um cmdlet, consulte Declaração de Atributo do Cmdlet.
Este documento fornece duas maneiras de descobrir como o código do cmdlet é escrito. Se você preferir ver o código sem muita explicação, consulte Exemplos dede Código do Cmdlet. Se você preferir mais explicação sobre o código, consulte os tópicos Tutorial getproc, de Tutorial do StopProc ou tópicos do Tutorial SelectStr.
Para obter mais informações sobre as diretrizes para escrever cmdlets, consulte de Diretrizes de Desenvolvimento do Cmdlet.
conceitos de cmdlet do PowerShell
Comentários do PowerShell
O PowerShell é um projeto código aberto. Selecione um link para fornecer comentários: