Compartilhar via

Capítulo 2 – O sistema de Ajuda

Em um experimento projetado para avaliar a proficiência no PowerShell, dois grupos distintos de profissionais de TI — iniciantes e especialistas — receberam primeiro um exame escrito sem acesso a um computador. Surpreendentemente, as pontuações de teste indicaram habilidades comparáveis em ambos os grupos. Um teste subsequente foi então administrado, espelhando o primeiro, mas com uma diferença fundamental: os participantes tinham acesso a um computador offline equipado com o PowerShell. Os resultados revelaram uma diferença significativa de habilidades entre os dois grupos desta vez.

Quais fatores contribuíram para os resultados observados entre as duas avaliações?

Especialistas nem sempre sabem as respostas, mas sabem como descobrir as respostas.

Os resultados observados nos resultados dos dois testes foram porque os especialistas não memorizam milhares de comandos do PowerShell. Em vez disso, eles se destacam em usar o sistema de Ajuda no PowerShell, permitindo que eles descubram e aprendam a usar comandos quando necessário.

Tornar-se proficiente com o sistema de Ajuda é a chave para o sucesso com o PowerShell.

Ouvi jeffrey Snover, o criador do PowerShell, compartilhar uma história semelhante em várias ocasiões.

Detectabilidade

Os comandos compilados no PowerShell são conhecidos como cmdlets, pronunciados como "command-let", não "CMD-let". A convenção de nomenclatura para cmdlets segue um formato singular de verbo-substantivo para torná-los facilmente detectáveis. Por exemplo, Get-Process é o cmdlet para determinar quais processos estão em execução e Get-Service é o cmdlet para recuperar uma lista de serviços. As funções, também conhecidas como cmdlets de script e aliases, são outros tipos de comandos do PowerShell que são discutidos posteriormente neste livro. O termo "comando do PowerShell" descreve qualquer comando no PowerShell, independentemente de ser um cmdlet, uma função ou um alias.

Você também pode executar comandos nativos do sistema operacional do PowerShell, como programas de linha de comando tradicionais, como ping.exe e ipconfig.exe.

Os três cmdlets principais do PowerShell

  • Get-Help
  • Get-Command
  • Get-Member (abordado no capítulo 3)

Muitas vezes me perguntam: "Como você descobre quais são os comandos no PowerShell?". Tanto Get-Help quanto Get-Command são recursos inestimáveis para descobrir e entender comandos no PowerShell.

Obter Ajuda

A primeira coisa que você precisa saber sobre o sistema de Ajuda no PowerShell é como usar o cmdlet Get-Help.

Get-Help é um comando multiuso que ajuda você a aprender a usar comandos depois de encontrá-los. Você também pode usar Get-Help para localizar comandos, mas de uma maneira diferente e mais indireta quando comparado a Get-Command.

Ao usar Get-Help para localizar comandos, ele inicialmente executa uma pesquisa curinga por nomes de comando com base em sua entrada. Se isso não encontrar correspondências, ele realizará uma pesquisa abrangente de texto completo em todos os artigos de ajuda do PowerShell em seu sistema. Caso isso também não encontre resultados, ele retornará um erro.

Veja como usar Get-Help para exibir o conteúdo da ajuda do cmdlet Get-Help.

Get-Help -Name Get-Help

A partir da versão 3.0 do PowerShell, o conteúdo de ajuda não vem pré-instalado com o sistema operacional. Quando você executa Get-Help pela primeira vez, uma mensagem pergunta se você deseja baixar os arquivos de ajuda do PowerShell para seu computador.

Responder Sim pressionando Y executa o cmdlet Update-Help para baixar o conteúdo de ajuda.

Do you want to run Update-Help?
The Update-Help cmdlet downloads the most current Help files for Windows
PowerShell modules, and installs them on your computer. For more information
about the Update-Help cmdlet, see
https:/go.microsoft.com/fwlink/?LinkId=210614.
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):

Se você não receber essa mensagem, execute Update-Help de uma sessão elevada do PowerShell executada como administrador.

Depois que a atualização for concluída, o artigo de ajuda será exibido.

Reserve um momento para executar o exemplo em seu computador, examinar a saída e observar como o sistema de ajuda organiza as informações.

  • NOME
  • SINOPSE
  • SINTAXE
  • DESCRIÇÃO
  • LINKS RELACIONADOS
  • COMENTÁRIOS

Ao examinar o resultado, tenha em mente que os artigos de ajuda geralmente contêm uma grande quantidade de informações, e o que aparece por padrão não é todo o artigo de ajuda.

Parâmetros

Ao executar um comando no PowerShell, talvez seja necessário fornecer informações adicionais ou entrada para o comando. Os parâmetros permitem especificar opções e argumentos que alteram o comportamento de um comando. A seção SYNTAX de cada artigo de ajuda descreve os parâmetros disponíveis para o comando.

Get-Help tem vários parâmetros que você pode especificar para retornar todo o artigo de ajuda ou um subconjunto para um comando. Para exibir todos os parâmetros disponíveis para Get-Help, consulte a seção SYNTAX de seu artigo de ajuda, conforme mostrado no exemplo a seguir.

...
SYNTAX
    Get-Help [[-Name] <System.String>] [-Category {Alias | Cmdlet | Provider
    | General | FAQ | Glossary | HelpFile | ScriptCommand | Function |
    Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource |
    Class | Configuration}] [-Component <System.String[]>] [-Full]
    [-Functionality <System.String[]>] [-Path <System.String>] [-Role
    <System.String[]>] [<CommonParameters>]

    Get-Help [[-Name] <System.String>] [-Category {Alias | Cmdlet | Provider
    | General | FAQ | Glossary | HelpFile | ScriptCommand | Function |
    Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource |
    Class | Configuration}] [-Component <System.String[]>] -Detailed
    [-Functionality <System.String[]>] [-Path <System.String>] [-Role
    <System.String[]>] [<CommonParameters>]

    Get-Help [[-Name] <System.String>] [-Category {Alias | Cmdlet | Provider
    | General | FAQ | Glossary | HelpFile | ScriptCommand | Function |
    Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource |
    Class | Configuration}] [-Component <System.String[]>] -Examples
    [-Functionality <System.String[]>] [-Path <System.String>] [-Role
    <System.String[]>] [<CommonParameters>]

    Get-Help [[-Name] <System.String>] [-Category {Alias | Cmdlet | Provider
    | General | FAQ | Glossary | HelpFile | ScriptCommand | Function |
    Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource |
    Class | Configuration}] [-Component <System.String[]>] [-Functionality
    <System.String[]>] -Online [-Path <System.String>] [-Role
    <System.String[]>] [<CommonParameters>]

    Get-Help [[-Name] <System.String>] [-Category {Alias | Cmdlet | Provider
    | General | FAQ | Glossary | HelpFile | ScriptCommand | Function |
    Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource |
    Class | Configuration}] [-Component <System.String[]>] [-Functionality
    <System.String[]>] -Parameter <System.String> [-Path <System.String>]
    [-Role <System.String[]>] [<CommonParameters>]

    Get-Help [[-Name] <System.String>] [-Category {Alias | Cmdlet | Provider
    | General | FAQ | Glossary | HelpFile | ScriptCommand | Function |
    Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource |
    Class | Configuration}] [-Component <System.String[]>] [-Functionality
    <System.String[]>] [-Path <System.String>] [-Role <System.String[]>]
    -ShowWindow [<CommonParameters>]
...

Conjuntos de parâmetros

Ao examinar a seção SYNTAX para Get-Help, observe que as informações parecem se repetir seis vezes. Cada um desses blocos é um conjunto de parâmetros individual, indicando que o cmdlet Get-Help apresenta seis conjuntos distintos de parâmetros. Uma visão mais detalhada revela que cada conjunto de parâmetros contém pelo menos um parâmetro exclusivo, tornando-o diferente dos outros.

Os conjuntos de parâmetros são mutuamente exclusivos. Depois de especificar um parâmetro exclusivo que existe apenas em um conjunto de parâmetros, o PowerShell limitará você a usar os parâmetros contidos nesse conjunto de parâmetros. Por exemplo, você não pode usar os parâmetros Completo e Detalhados de Get-Help juntos, pois pertencem a conjuntos de parâmetros diferentes.

Cada um dos parâmetros a seguir pertence a um conjunto de parâmetros diferente para o cmdlet Get-Help.

  • Completo
  • Detalhado
  • Exemplos
  • Online
  • Parâmetro
  • ShowWindow

A sintaxe de comando

Se você está começando a usar o PowerShell, compreender as informações enigmáticas — caracterizadas por colchetes e parênteses angulares — na seção SINTAXE pode parecer difícil. No entanto, aprender esses elementos de sintaxe é essencial para se tornar proficiente com o PowerShell. Quanto mais freqüentemente você usa o sistema de Ajuda do PowerShell, mais fácil fica lembrar de todas as nuances.

Exiba a sintaxe do cmdlet Get-EventLog.

Get-Help Get-EventLog

A saída abaixo mostra o trecho relevante do artigo de ajuda.

...
SYNTAX
    Get-EventLog [-LogName] <System.String> [[-InstanceId]
    <System.Int64[]>] [-After <System.DateTime>] [-AsBaseObject] [-Before
    <System.DateTime>] [-ComputerName <System.String[]>] [-EntryType {Error
    | Information | FailureAudit | SuccessAudit | Warning}] [-Index
    <System.Int32[]>] [-Message <System.String>] [-Newest <System.Int32>]
    [-Source <System.String[]>] [-UserName <System.String[]>]
    [<CommonParameters>]

    Get-EventLog [-AsString] [-ComputerName <System.String[]>] [-List]
    [<CommonParameters>]
...

As informações de sintaxe incluem pares de colchetes ([]). Dependendo do uso, esses colchetes têm duas finalidades diferentes.

  • Elementos entre colchetes são opcionais.
  • Um conjunto vazio de colchetes seguindo um tipo de dados, como <string[]>, indica que o parâmetro pode aceitar vários valores passados como uma matriz ou um objeto de coleção.

Parâmetros posicionais

Alguns cmdlets são projetados para aceitar parâmetros posicionais. Os parâmetros posicionais permitem que você forneça um valor sem especificar o nome do parâmetro. Ao usar um parâmetro posicionalmente, você deve especificar seu valor na posição correta na linha de comando. Você pode encontrar as informações posicionais de um parâmetro na seção PARAMETERS do artigo de ajuda de um comando. Quando você especifica explicitamente os nomes de parâmetro, pode usar os parâmetros em qualquer ordem.

Para o cmdlet Get-EventLog, o primeiro parâmetro no primeiro conjunto de parâmetros é LogName. LogName está entre colchetes, indicando que é um parâmetro posicional.

Get-EventLog [-LogName] <System.String>

Como LogName é um parâmetro posicional, você pode especificá-lo por nome ou posição. De acordo com os colchetes angulares após o nome do parâmetro, o valor de LogName deve ser uma única cadeia de caracteres. A ausência de colchetes que incluem o nome do parâmetro e o tipo de dados indica que logName é um parâmetro necessário dentro desse conjunto de parâmetros específico.

O segundo parâmetro nesse conjunto de parâmetros é InstanceId. Tanto o nome do parâmetro quanto o tipo de dados estão totalmente entre colchetes, significando que InstanceId é um parâmetro opcional.

[[-InstanceId] <System.Int64[]>]

Além disso, InstanceId tem seu próprio par de colchetes, indicando que ele é um parâmetro posicional semelhante ao parâmetro LogName. Seguindo o tipo de dados, um conjunto vazio de colchetes implica que InstanceId pode aceitar vários valores.

Alternar parâmetros

Um parâmetro que não requer um valor é chamado de parâmetro switch. Você pode identificar facilmente parâmetros de comutador porque não existe um tipo de dado seguindo o nome do parâmetro. Quando você especifica um parâmetro de comutador, seu valor é true. Quando você não especifica um parâmetro de comutador, o valor é false.

O segundo conjunto de parâmetros inclui um parâmetro List, que é um parâmetro de comutador. Quando você especifica o parâmetro List, ele retorna uma lista de logs de eventos no computador local.

[-List]

Uma abordagem simplificada para sintaxe

Há um método mais amigável para obter as mesmas informações que a sintaxe de comando enigmática, mas apresentadas de forma clara em inglês simples. O PowerShell retorna o artigo de ajuda completo ao usar Get-Help com o parâmetro Full, facilitando a compreensão do uso de um comando.

Get-Help -Name Get-Help -Full

Reserve um momento para executar o exemplo em seu computador, examinar a saída e observar como o sistema de ajuda organiza as informações.

  • NOME
  • SINOPSE
  • SINTAXE
  • DESCRIÇÃO
  • PARÂMETROS
  • ENTRADAS
  • SAÍDAS
  • ANOTAÇÕES
  • EXEMPLOS
  • LINKS RELACIONADOS

Ao especificar o parâmetro Full com o cmdlet Get-Help, a saída inclui várias seções extras. Entre essas seções, PARAMETERS geralmente fornece uma explicação detalhada para cada parâmetro. No entanto, a extensão dessas informações varia dependendo do comando específico que você está investigando.

...
    -Detailed <System.Management.Automation.SwitchParameter>
        Adds parameter descriptions and examples to the basic help display.
        This parameter is effective only when the help files are installed
        on the computer. It has no effect on displays of conceptual ( About_
        ) help.

        Required?                    true
        Position?                    named
        Default value                False
        Accept pipeline input?       False
        Accept wildcard characters?  false

    -Examples <System.Management.Automation.SwitchParameter>
        Displays only the name, synopsis, and examples. This parameter is
        effective only when the help files are installed on the computer. It
        has no effect on displays of conceptual ( About_ ) help.

        Required?                    true
        Position?                    named
        Default value                False
        Accept pipeline input?       False
        Accept wildcard characters?  false

    -Full <System.Management.Automation.SwitchParameter>
        Displays the entire help article for a cmdlet. Full includes
        parameter descriptions and attributes, examples, input and output
        object types, and additional notes.

        This parameter is effective only when the help files are installed
        on the computer. It has no effect on displays of conceptual ( About_
        ) help.

        Required?                    false
        Position?                    named
        Default value                False
        Accept pipeline input?       False
        Accept wildcard characters?  false
...

Quando você executou o comando anterior para exibir a ajuda do comando Get-Help, provavelmente notou que a saída passou rápido demais para ler.

Se você estiver usando o console do PowerShell, o Terminal do Windows ou o VS Code e precisar exibir um artigo de ajuda, a função help poderá ser útil. Ele redireciona a saída de Get-Help para more.com, exibindo uma página de conteúdo de ajuda de cada vez. É recomendável usar a função help em vez do cmdlet Get-Help porque ele fornece uma melhor experiência do usuário e é menos para digitar.

Observação

O ISE não dá suporte ao uso de more.com, portanto, executar help funciona da mesma maneira que Get-Help.

Execute cada um dos comandos a seguir no PowerShell em seu computador.

Get-Help -Name Get-Help -Full
help -Name Get-Help -Full
help Get-Help -Full

Você observou alguma variação na saída quando executou os comandos anteriores?

No exemplo anterior, a primeira linha usa o cmdlet Get-Help, a segunda usa a função help e a terceira linha omite o parâmetro Nome ao usar a função help. Como Name é um parâmetro posicional, o terceiro exemplo aproveita sua posição em vez de indicar explicitamente o nome do parâmetro.

A diferença é que os dois últimos comandos exibem a saída uma página de cada vez. Ao usar a função help, pressione a barra de espaços para exibir a próxima página de conteúdo ou Q para encerrar. Se você precisar encerrar qualquer comando em execução interativamente no PowerShell, pressione Ctrl+C.

Para localizar rapidamente informações sobre um parâmetro específico, use o parâmetro . Essa abordagem retorna conteúdo que contém apenas as informações específicas do parâmetro, em vez de todo o artigo de ajuda. Essa é a maneira mais fácil de encontrar informações sobre um parâmetro específico.

O exemplo a seguir usa a função help com o parâmetro Parameter para retornar informações do artigo de ajuda do parâmetro Name de Get-Help.

help Get-Help -Parameter Name

As informações de ajuda mostram que o parâmetro Name é posicional e deve ser especificado na primeira posição (posição zero) quando usado posicionalmente.

-Name <System.String>
    Gets help about the specified command or concept. Enter the name of a
    cmdlet, function, provider, script, or workflow, such as `Get-Member`,
    a conceptual article name, such as `about_Objects`, or an alias, such
    as `ls`. Wildcard characters are permitted in cmdlet and provider
    names, but you can't use wildcard characters to find the names of
    function help and script help articles.

    To get help for a script that isn't located in a path that's listed in
    the `$env:Path` environment variable, type the script's path and file
    name.

    If you enter the exact name of a help article, `Get-Help` displays the
    article contents.

    If you enter a word or word pattern that appears in several help
    article titles, `Get-Help` displays a list of the matching titles.

    If you enter any text that doesn't match any help article titles,
    `Get-Help` displays a list of articles that include that text in their
    contents.

    The names of conceptual articles, such as `about_Objects`, must be
    entered in English, even in non-English versions of PowerShell.

    Required?                    false
    Position?                    0
    Default value                None
    Accept pipeline input?       True (ByPropertyName)
    Accept wildcard characters?  true

O parâmetro Name espera um valor de cadeia de caracteres, conforme identificado pelo tipo de dados <String> ao lado do nome do parâmetro.

Há vários outros parâmetros que você pode especificar com Get-Help para retornar um subconjunto de um artigo de ajuda. Para ver como eles funcionam, execute os comandos a seguir em seu computador.

Get-Help -Name Get-Command -Full
Get-Help -Name Get-Command -Detailed
Get-Help -Name Get-Command -Examples
Get-Help -Name Get-Command -Online
Get-Help -Name Get-Command -Parameter Noun
Get-Help -Name Get-Command -ShowWindow

Normalmente, use help <command name> com o parâmetro Full ou Online. Se você tiver apenas interesse nos exemplos, use o parâmetro Exemplos. Se você tiver apenas interesse em um parâmetro específico, use o parâmetro Parameter.

Quando você usa o parâmetro ShowWindow, ele exibe o conteúdo da ajuda em uma janela pesquisável separada. Você pode mover essa janela para um monitor diferente se tiver vários monitores. No entanto, o parâmetro ShowWindow tem um bug conhecido que pode impedi-lo de exibir todo o artigo de ajuda. O parâmetro ShowWindow também requer um sistema operacional com uma GUI (Interface Gráfica do Usuário). Ele retorna um erro quando você tenta usá-lo no Windows Server Core.

Se você tiver acesso à internet, poderá usar o parâmetro Online. O parâmetro Online abre o artigo de ajuda no navegador da Web padrão. O conteúdo online é o conteúdo mais atualizado. O navegador permite que você pesquise o conteúdo da ajuda e exiba outros artigos de ajuda relacionados.

Observação

Não há suporte para o parâmetro Online para artigos Sobre.

help Get-Command -Online

Localizando comandos com Get-Help

Para encontrar comandos com Get-Help, especifique um termo de pesquisa cercado por asteriscos (*) como caracteres curinga para o valor do parâmetro Name. O exemplo a seguir usa o parâmetro Name posicionalmente.

help *process*

Name                              Category  Module                    Synops
----                              --------  ------                    ------
Enter-PSHostProcess               Cmdlet    Microsoft.PowerShell.Core Con...
Exit-PSHostProcess                Cmdlet    Microsoft.PowerShell.Core Clo...
Get-PSHostProcessInfo             Cmdlet    Microsoft.PowerShell.Core Get...
Debug-Process                     Cmdlet    Microsoft.PowerShell.M... Deb...
Get-Process                       Cmdlet    Microsoft.PowerShell.M... Get...
Start-Process                     Cmdlet    Microsoft.PowerShell.M... Sta...
Stop-Process                      Cmdlet    Microsoft.PowerShell.M... Sto...
Wait-Process                      Cmdlet    Microsoft.PowerShell.M... Wai...
Invoke-LapsPolicyProcessing       Cmdlet    LAPS                      Inv...
ConvertTo-ProcessMitigationPolicy Cmdlet    ProcessMitigations        Con...
Get-ProcessMitigation             Cmdlet    ProcessMitigations        Get...
Set-ProcessMitigation             Cmdlet    ProcessMitigations        Set...

Nesse cenário, você não precisa adicionar os caracteres curinga *. Se Get-Help não conseguir encontrar um comando que corresponda ao valor fornecido, ele fará uma pesquisa de texto completo para esse valor. O exemplo a seguir produz os mesmos resultados que especificar o caractere curinga * nas duas extremidades de process.

help process

Quando você especifica um caractere curinga dentro do valor, Get-Help pesquisa apenas os comandos que correspondem ao padrão fornecido. Ele não executa uma pesquisa de texto completo. O comando a seguir não retorna nenhum resultado.

help pr*cess

O PowerShell gerará um erro se você especificar um valor que começa com um traço sem colocá-lo entre aspas porque ele o interpreta como um nome de parâmetro. Não existe nenhum nome de parâmetro para o cmdlet Get-Help.

help -process

Se você estiver tentando pesquisar comandos que terminam com -process, adicione um * ao início do valor.

help *-process

Quando você procura comandos do PowerShell com Get-Help, é melhor ser vago em vez de muito específico.

Quando você pesquisou process anteriormente, os resultados retornaram apenas comandos que incluíam process em seu nome. Mas se você procurar processes, ele não encontrará correspondências para nomes de comando. Como indicado anteriormente, quando a ajuda não encontra correspondências, ela executa uma pesquisa abrangente de texto completo de cada artigo de ajuda em seu sistema e retorna esses resultados. Esse tipo de pesquisa geralmente produz mais resultados do que o esperado, incluindo informações não relevantes para você.

help processes

Name                              Category  Module                    Synops
----                              --------  ------                    ------
Disconnect-PSSession              Cmdlet    Microsoft.PowerShell.Core Dis...
Enter-PSHostProcess               Cmdlet    Microsoft.PowerShell.Core Con...
ForEach-Object                    Cmdlet    Microsoft.PowerShell.Core Per...
Get-PSHostProcessInfo             Cmdlet    Microsoft.PowerShell.Core Get...
Get-PSSessionConfiguration        Cmdlet    Microsoft.PowerShell.Core Get...
New-PSSessionOption               Cmdlet    Microsoft.PowerShell.Core Cre...
New-PSTransportOption             Cmdlet    Microsoft.PowerShell.Core Cre...
Out-Host                          Cmdlet    Microsoft.PowerShell.Core Sen...
Start-Job                         Cmdlet    Microsoft.PowerShell.Core Sta...
Where-Object                      Cmdlet    Microsoft.PowerShell.Core Sel...
Debug-Process                     Cmdlet    Microsoft.PowerShell.M... Deb...
Get-Process                       Cmdlet    Microsoft.PowerShell.M... Get...
Get-WmiObject                     Cmdlet    Microsoft.PowerShell.M... Get...
Start-Process                     Cmdlet    Microsoft.PowerShell.M... Sta...
Stop-Process                      Cmdlet    Microsoft.PowerShell.M... Sto...
Wait-Process                      Cmdlet    Microsoft.PowerShell.M... Wai...
Clear-Variable                    Cmdlet    Microsoft.PowerShell.U... Del...
Convert-String                    Cmdlet    Microsoft.PowerShell.U... For...
ConvertFrom-Csv                   Cmdlet    Microsoft.PowerShell.U... Con...
ConvertFrom-Json                  Cmdlet    Microsoft.PowerShell.U... Con...
ConvertTo-Html                    Cmdlet    Microsoft.PowerShell.U... Con...
ConvertTo-Xml                     Cmdlet    Microsoft.PowerShell.U... Cre...
Debug-Runspace                    Cmdlet    Microsoft.PowerShell.U... Sta...
Export-Csv                        Cmdlet    Microsoft.PowerShell.U... Con...
Export-FormatData                 Cmdlet    Microsoft.PowerShell.U... Sav...
Format-List                       Cmdlet    Microsoft.PowerShell.U... For...
Format-Table                      Cmdlet    Microsoft.PowerShell.U... For...
Get-Unique                        Cmdlet    Microsoft.PowerShell.U... Ret...
Group-Object                      Cmdlet    Microsoft.PowerShell.U... Gro...
Import-Clixml                     Cmdlet    Microsoft.PowerShell.U... Imp...
Import-Csv                        Cmdlet    Microsoft.PowerShell.U... Cre...
Measure-Object                    Cmdlet    Microsoft.PowerShell.U... Cal...
Out-File                          Cmdlet    Microsoft.PowerShell.U... Sen...
Out-GridView                      Cmdlet    Microsoft.PowerShell.U... Sen...
Select-Object                     Cmdlet    Microsoft.PowerShell.U... Sel...
Set-Variable                      Cmdlet    Microsoft.PowerShell.U... Set...
Sort-Object                       Cmdlet    Microsoft.PowerShell.U... Sor...
Tee-Object                        Cmdlet    Microsoft.PowerShell.U... Sav...
Trace-Command                     Cmdlet    Microsoft.PowerShell.U... Con...
Write-Information                 Cmdlet    Microsoft.PowerShell.U... Spe...
Export-BinaryMiLog                Cmdlet    CimCmdlets                Cre...
Get-CimAssociatedInstance         Cmdlet    CimCmdlets                Ret...
Get-CimInstance                   Cmdlet    CimCmdlets                Get...
Import-BinaryMiLog                Cmdlet    CimCmdlets                Use...
Invoke-CimMethod                  Cmdlet    CimCmdlets                Inv...
New-CimInstance                   Cmdlet    CimCmdlets                Cre...
Remove-CimInstance                Cmdlet    CimCmdlets                Rem...
Set-CimInstance                   Cmdlet    CimCmdlets                Mod...
Compress-Archive                  Function  Microsoft.PowerShell.A... Cre...
Get-Counter                       Cmdlet    Microsoft.PowerShell.D... Get...
Invoke-WSManAction                Cmdlet    Microsoft.WSMan.Manage... Inv...
Remove-WSManInstance              Cmdlet    Microsoft.WSMan.Manage... Del...
Get-WSManInstance                 Cmdlet    Microsoft.WSMan.Manage... Dis...
New-WSManInstance                 Cmdlet    Microsoft.WSMan.Manage... Cre...
Set-WSManInstance                 Cmdlet    Microsoft.WSMan.Manage... Mod...
about_Arithmetic_Operators        HelpFile
about_Arrays                      HelpFile
about_Environment_Variables       HelpFile
about_Execution_Policies          HelpFile
about_Functions                   HelpFile
about_Jobs                        HelpFile
about_Logging                     HelpFile
about_Methods                     HelpFile
about_Objects                     HelpFile
about_Pipelines                   HelpFile
about_Preference_Variables        HelpFile
about_Remote                      HelpFile
about_Remote_Jobs                 HelpFile
about_Session_Configuration_Files HelpFile
about_Simplified_Syntax           HelpFile
about_Switch                      HelpFile
about_Variables                   HelpFile
about_Variable_Provider           HelpFile
about_Windows_PowerShell_5.1      HelpFile
about_WQL                         HelpFile
about_WS-Management_Cmdlets       HelpFile
about_Foreach-Parallel            HelpFile
about_Parallel                    HelpFile
about_Sequence                    HelpFile

Quando você pesquisou process, ele retornou 12 resultados. No entanto, ao pesquisar processes, produziu 78 resultados. Se a pesquisa encontrar apenas uma correspondência, Get-Help exibirá o conteúdo da ajuda em vez de listar os resultados da pesquisa.

help *hotfix*

NAME
    Get-HotFix

SYNOPSIS
    Gets the hotfixes that are installed on local or remote computers.


SYNTAX
    Get-HotFix [-ComputerName <System.String[]>] [-Credential
    <System.Management.Automation.PSCredential>] [-Description
    <System.String[]>] [<CommonParameters>]

    Get-HotFix [[-Id] <System.String[]>] [-ComputerName <System.String[]>]
    [-Credential <System.Management.Automation.PSCredential>]
    [<CommonParameters>]


DESCRIPTION
    > This cmdlet is only available on the Windows platform. The
    `Get-HotFix` cmdlet uses the Win32_QuickFixEngineering WMI class to
    list hotfixes that are installed on the local computer or specified
    remote computers.


RELATED LINKS
    Online Version: https://learn.microsoft.com/powershell/module/microsoft.
    powershell.management/get-hotfix?view=powershell-5.1&WT.mc_id=ps-gethelp
    about_Arrays
    Add-Content
    Get-ComputerRestorePoint
    Get-Credential
    Win32_QuickFixEngineering class

REMARKS
    To see the examples, type: "Get-Help Get-HotFix -Examples".
    For more information, type: "Get-Help Get-HotFix -Detailed".
    For technical information, type: "Get-Help Get-HotFix -Full".
    For online help, type: "Get-Help Get-HotFix -Online"

Você também pode encontrar comandos que não têm artigos de ajuda com Get-Help, embora essa funcionalidade não seja comumente conhecida. A função more é um dos comandos que não tem um artigo de ajuda. Para confirmar se você pode encontrar comandos com Get-Help que não incluem artigos de ajuda, use a função help para localizar more.

help *more*

A pesquisa encontrou apenas uma correspondência, portanto, retornou as informações básicas de sintaxe que você vê quando um comando não tem um artigo de ajuda.

NAME
    more

SYNTAX
    more [[-paths] <string[]>]

ALIASES
    None

REMARKS
    None

O sistema de ajuda do PowerShell também contém artigos de ajuda conceitual Sobre. Você deve atualizar o conteúdo da ajuda em seu sistema para obter os artigos Sobre. Para obter mais informações, consulte a seção Atualização de ajuda deste capítulo.

Use o comando a seguir para retornar uma lista de todos os artigos de ajuda Sobre no seu sistema.

help About_*

Se você limita os resultados a um artigo de ajuda sobre, Get-Help exibe o conteúdo desse artigo.

help about_Updatable_Help

Atualizando a Ajuda

Anteriormente neste capítulo, você atualizou os artigos de ajuda do PowerShell em seu computador na primeira vez em que executou o cmdlet Get-Help. Você deve executar periodicamente o cmdlet Update-Help em seu computador para obter atualizações para o conteúdo da ajuda.

Importante

No Windows PowerShell 5.1, você deve executar Update-Help como administrador em uma sessão elevada do PowerShell.

No exemplo a seguir, Update-Help baixa o conteúdo de ajuda do PowerShell para todos os módulos instalados em seu computador. Você deve usar o parâmetro Force para garantir que você baixe a versão mais recente do conteúdo da ajuda.

Update-Help -Force

Conforme mostrado nos resultados a seguir, um módulo retornou um erro. Erros não são incomuns e geralmente ocorrem quando o autor do módulo não configura a ajuda atualizável corretamente.

Update-Help : Failed to update Help for the module(s) 'BitsTransfer' with UI
culture(s) {en-US} : Unable to retrieve the HelpInfo XML file for UI culture
en-US. Make sure the HelpInfoUri property in the module manifest is valid or
check your network connection and then try the command again.
At line:1 char:1
+ Update-Help
+ ~~~~~~~~~~~
    + CategoryInfo          : ResourceUnavailable: (:) [Update-Help], Except
   ion
    + FullyQualifiedErrorId : UnableToRetrieveHelpInfoXml,Microsoft.PowerShe
   ll.Commands.UpdateHelpCommand

Update-Help requer acesso à Internet para baixar o conteúdo da ajuda. Se o computador não tiver acesso à Internet, use o cmdlet Save-Help em um computador com acesso à Internet para baixar e salvar o conteúdo de ajuda atualizado. Em seguida, use o parâmetro SourcePath de Update-Help para especificar o local do conteúdo de ajuda atualizado salvo.

Get-Command

Get-Command é outro comando multiuso que ajuda você a encontrar comandos. Quando você executa Get-Command sem parâmetros, ele retorna uma lista de todos os comandos do PowerShell em seu sistema. Você também pode usar Get-Command para obter sintaxe de comando semelhante a Get-Help.

Como você determina a sintaxe para Get-Command? Você pode usar Get-Help para exibir o artigo de ajuda para Get-Command, conforme mostrado na seção Get-Help deste capítulo. Você também pode usar Get-Command com o parâmetro Syntax para exibir a sintaxe de qualquer comando. Esse atalho ajuda você a determinar rapidamente como usar um comando sem navegar pelo conteúdo de ajuda.

Get-Command -Name Get-Command -Syntax

Usar Get-Command com o parâmetro de sintaxe fornece uma exibição mais concisa da sintaxe que mostra os parâmetros e seus tipos de valor, sem listar os valores permitidos específicos, como mostra Get-Help.

Get-Command [[-ArgumentList] <Object[]>] [-Verb <string[]>]
[-Noun <string[]>] [-Module <string[]>]
[-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <int>]
[-Syntax] [-ShowCommandInfo] [-All] [-ListImported]
[-ParameterName <string[]>] [-ParameterType <PSTypeName[]>]
[<CommonParameters>]

Get-Command [[-Name] <string[]>] [[-ArgumentList] <Object[]>]
[-Module <string[]>] [-FullyQualifiedModule <ModuleSpecification[]>]
[-CommandType <CommandTypes>] [-TotalCount <int>] [-Syntax]
[-ShowCommandInfo] [-All] [-ListImported] [-ParameterName <string[]>]
[-ParameterType <PSTypeName[]>] [<CommonParameters>]

Se você precisar de informações mais detalhadas sobre como usar um comando, use Get-Help.

help Get-Command -Full

A seção SYNTAX de Get-Help fornece uma exibição mais amigável expandindo valores enumerados para parâmetros. Ele mostra os valores reais que você pode usar, facilitando a compreensão das opções disponíveis.

...
    Get-Command [[-Name] <System.String[]>] [[-ArgumentList]
    <System.Object[]>] [-All] [-CommandType {Alias | Function | Filter |
    Cmdlet | ExternalScript | Application | Script | Workflow |
    Configuration | All}] [-FullyQualifiedModule
    <Microsoft.PowerShell.Commands.ModuleSpecification[]>] [-ListImported]
    [-Module <System.String[]>] [-ParameterName <System.String[]>]
    [-ParameterType <System.Management.Automation.PSTypeName[]>]
    [-ShowCommandInfo] [-Syntax] [-TotalCount <System.Int32>]
    [<CommonParameters>]

    Get-Command [[-ArgumentList] <System.Object[]>] [-All]
    [-FullyQualifiedModule
    <Microsoft.PowerShell.Commands.ModuleSpecification[]>] [-ListImported]
    [-Module <System.String[]>] [-Noun <System.String[]>] [-ParameterName
    <System.String[]>] [-ParameterType
    <System.Management.Automation.PSTypeName[]>] [-ShowCommandInfo]
    [-Syntax] [-TotalCount <System.Int32>] [-Verb <System.String[]>]
    [<CommonParameters>]
...

A seção PARÂMETROS da ajuda para Get-Command revela que os parâmetros Nome, Substantivoe Verbo aceitam caracteres curinga.

...
    -Name <System.String[]>
        Specifies an array of names. This cmdlet gets only commands that
        have the specified name. Enter a name or name pattern. Wildcard
        characters are permitted.

        To get commands that have the same name, use the All parameter. When
        two commands have the same name, by default, `Get-Command` gets the
        command that runs when you type the command name.

        Required?                    false
        Position?                    0
        Default value                None
        Accept pipeline input?       True (ByPropertyName, ByValue)
        Accept wildcard characters?  true

    -Noun <System.String[]>
        Specifies an array of command nouns. This cmdlet gets commands,
        which include cmdlets, functions, and aliases, that have names that
        include the specified noun. Enter one or more nouns or noun
        patterns. Wildcard characters are permitted.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?       True (ByPropertyName)
        Accept wildcard characters?  true
    -Verb <System.String[]>
        Specifies an array of command verbs. This cmdlet gets commands,
        which include cmdlets, functions, and aliases, that have names that
        include the specified verb. Enter one or more verbs or verb
        patterns. Wildcard characters are permitted.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?       True (ByPropertyName)
        Accept wildcard characters?  true
...

O exemplo a seguir usa o caractere curinga * com o valor do parâmetro Name de Get-Command.

Get-Command -Name *service*

Quando você usa caracteres curinga com o parâmetro Name de Get-Command, ele retorna comandos do PowerShell e comandos nativos, conforme mostrado nos resultados a seguir.


CommandType     Name                                               Version
-----------     ----                                               -------
Function        Get-NetFirewallServiceFilter                       2.0.0.0
Function        Set-NetFirewallServiceFilter                       2.0.0.0
Cmdlet          Get-Service                                        3.1.0.0
Cmdlet          New-Service                                        3.1.0.0
Cmdlet          New-WebServiceProxy                                3.1.0.0
Cmdlet          Restart-Service                                    3.1.0.0
Cmdlet          Resume-Service                                     3.1.0.0
Cmdlet          Set-Service                                        3.1.0.0
Cmdlet          Start-Service                                      3.1.0.0
Cmdlet          Stop-Service                                       3.1.0.0
Cmdlet          Suspend-Service                                    3.1.0.0
Application     SecurityHealthService.exe                          10.0.2...
Application     SensorDataService.exe                              10.0.2...
Application     services.exe                                       10.0.2...
Application     services.msc                                       0.0.0.0
Application     TieringEngineService.exe                           10.0.2...
Application     Windows.WARP.JITService.exe                        10.0.2...

Você pode limitar os resultados de Get-Command a comandos do PowerShell usando o parâmetro commandType.

Get-Command -Name *service* -CommandType Cmdlet, Function, Alias, Script

Outra opção pode ser usar o parâmetro verbo ou substantivo ou ambos, já que apenas os comandos do PowerShell têm verbos e substantivos.

O exemplo a seguir usa Get-Command para localizar comandos em seu computador que funcionam com processos. Use o parâmetro Noun e especifique Process como valor.

Get-Command -Noun Process

CommandType     Name                                               Version
-----------     ----                                               -------
Cmdlet          Debug-Process                                      3.1.0.0
Cmdlet          Get-Process                                        3.1.0.0
Cmdlet          Start-Process                                      3.1.0.0
Cmdlet          Stop-Process                                       3.1.0.0
Cmdlet          Wait-Process                                       3.1.0.0

Resumo

Neste capítulo, você aprendeu a encontrar comandos com Get-Help e Get-Command. Você também aprendeu a usar o sistema de ajuda para entender como usar comandos depois de encontrá-los. Além disso, você aprendeu a atualizar o sistema de ajuda em seu computador quando o novo conteúdo de ajuda estiver disponível.

Revisão

  1. O parâmetro DisplayName de Get-Service é posicional?
  2. Quantos conjuntos de parâmetros o cmdlet Get-Process tem?
  3. Quais comandos do PowerShell existem para trabalhar com logs de eventos?
  4. Qual é o comando do PowerShell para retornar uma lista de processos do PowerShell em execução em seu computador?
  5. Como você atualiza o conteúdo da ajuda do PowerShell armazenado em seu computador?

Referências

Para saber mais sobre os conceitos abordados neste capítulo, leia os seguintes artigos de ajuda do PowerShell.

Próximas etapas

No próximo capítulo, você aprenderá sobre objetos, propriedades, métodos e o cmdlet Get-Member.

  • Last updated on