Capítulo 2: Sistema de ayudaChapter 2 - The Help System

Se proporcionó una prueba escrita sin acceso a un equipo a dos grupos de profesionales de TI para determinar su nivel de conocimientos de PowerShell.Two groups of IT pros were given a written test without access to a computer to determine their skill level with PowerShell. Los principiantes de PowerShell se ubicaron en un grupo y los expertos, en otro.PowerShell beginners were placed in one group and experts in another. Según los resultados de la prueba, no pareció haber mucha diferencia en el nivel de conocimientos entre ambos grupos.Based on the results of the test, there didn't seem to be much difference in the skill level between the two groups. A ambos grupos se les proporcionó una segunda prueba similar a la primera.Both groups were given a second test similar to the first one. En esta ocasión, se les dio acceso a un equipo con PowerShell que no tenía acceso a Internet.This time they were given access to a computer with PowerShell that didn't have access to the internet. Los resultados de la segunda prueba mostraron una gran diferencia en el nivel de conocimientos entre ambos grupos.The results of the second test showed a huge difference in the skill level between the two groups. Los expertos no siempre conocen las respuestas, pero saben cómo averiguarlas.Experts don't always know the answers, but they know how to figure out the answers.

¿Cuál fue la diferencia en los resultados de la primera y la segunda prueba entre estos dos grupos?What was the difference in the results of the first and second test between these two groups?

Las diferencias observadas en estas dos pruebas se debieron a que los expertos no memorizan cómo usar miles de comandos en PowerShell.The differences observed in these two tests were because experts don't memorize how to use thousands of commands in PowerShell. En cambio, aprenden a usar muy bien el sistema de ayuda de PowerShell.They learn how to use the help system within PowerShell extremely well. Esto les permite encontrar los comandos necesarios cuando los necesitan y cómo usarlos una vez que los han encontrado.This allows them to find the necessary commands when needed and how to use those commands once they've found them.

He escuchado a Jeffrey Snover, el inventor de PowerShell, referirse a casos similares en numerosas ocasiones.I've heard Jeffrey Snover, the inventor of PowerShell, tell a similar story a number of times.

Dominar el sistema de ayuda es la clave para utilizar PowerShell correctamente.Mastering the help system is the key to being successful with PowerShell.

DetectabilidadDiscoverability

Los comandos compilados en PowerShell se denominan cmdlets.Compiled commands in PowerShell are called cmdlets. Se pronuncia "command-let" (y no "CMD-let").Cmdlet is pronounced "command-let" (not CMD-let). Los nombres de los cmdlets tienen la forma de comandos "verbo-sustantivo" singulares para poder descubrirlos con facilidad.Cmdlets names have the form of singular "Verb-Noun" commands to make them easily discoverable. Por ejemplo, el cmdlet para determinar qué procesos se están ejecutando es Get-Process y el cmdlet para recuperar una lista de servicios y sus estados es Get-Service.For example, the cmdlet for determining what processes are running is Get-Process and the cmdlet for retrieving a list of services and their statuses is Get-Service. Hay otros tipos de comandos en PowerShell, tales como alias y funciones, que se tratarán más adelante en este libro.There are other types of commands in PowerShell such as aliases and functions that will be covered later in this book. El término comando de PowerShell es un término genérico que se suele usar para hacer referencia a cualquier tipo de comando de PowerShell, independientemente de si se trata de un cmdlet, una función o un alias.The term PowerShell command is a generic term that's often used to refer to any type of command in PowerShell, regardless of whether or not it's a cmdlet, function, or alias.

Los tres cmdlets principales de PowerShellThe Three Core Cmdlets in PowerShell

  • Get-Command
  • Get-Help
  • Get-Member (se aborda en el capítulo 3)Get-Member (covered in chapter 3)

Una pregunta que se me plantea con frecuencia es cómo se averigua qué son los comandos en PowerShell.One question I'm often asked is how do you figure out what the commands are in PowerShell? Tanto Get-Command como Get-Help se pueden usar para determinar los comandos.Both Get-Command and Get-Help can be used to determine the commands.

Get-HelpGet-Help

Get-Help es un comando multipropósito.Get-Help is a multipurpose command. Get-Help le ayuda a aprender a usar comandos una vez que los haya encontrado.Get-Help helps you learn how to use commands once you find them. Get-Help también se puede usar para facilitar la búsqueda de comandos, pero de una forma diferente y más indirecta en comparación con Get-Command.Get-Help can also be used to help locate commands, but in a different and more indirect way when compared to Get-Command.

Cuando Get-Help se usa para buscar comandos, primero busca coincidencias con caracteres comodín de los nombres de comando en función de la entrada proporcionada.When Get-Help is used to locate commands, it first searches for wildcard matches of command names based on the provided input. Si no encuentra ninguna coincidencia, busca en los temas de ayuda y, si tampoco se encuentra ninguna coincidencia, se devuelve un error.If it doesn't find a match, it searches through the help topics themselves, and if no match is found an error is returned. Al contrario de lo que la mayoría de usuarios creen, Get-Help se puede usar para buscar comandos que no tienen temas de ayuda.Contrary to popular belief, Get-Help can be used to find commands that don't have help topics.

Lo primero que necesita saber sobre el sistema de ayuda de PowerShell es cómo usar el cmdlet Get-Help.The first thing you need to know about the help system in PowerShell is how to use the Get-Help cmdlet. El siguiente comando se usa para mostrar el tema de ayuda de Get-Help.The following command is used to display the help topic for Get-Help.

Get-Help -Name Get-Help
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 http://go.microsoft.com/fwlink/?LinkId=210614.
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):

A partir de la versión 3 de PowerShell, la ayuda de PowerShell no se distribuye con el sistema operativo.Beginning with PowerShell version 3, PowerShell help doesn't ship with the operating system. La primera vez que se ejecuta Get-Help para buscar un comando, se muestra el mensaje anterior.The first time Get-Help is run for a command, the previous message is displayed. Si usa la función help o el alias man en lugar del cmdlet Get-Help, no recibirá este mensaje.If the help function or man alias is used instead of the Get-Help cmdlet, you don't receive this prompt.

Al responder afirmativamente presionando Y, se ejecuta el cmdlet Update-Help, que requiere acceso a Internet de forma predeterminada.Answering yes by pressing Y runs the Update-Help cmdlet, which requires internet access by default. Y se puede especificar en mayúsculas o en minúsculas.Y can be specified in either upper or lower case.

Una vez que se ha descargado la ayuda y se ha completado la actualización, se devuelve el tema de ayuda para el comando especificado:Once the help is downloaded and the update is complete, the help topic is returned for the specified command:

Get-Help -Name Get-Help

Dedique un momento a ejecutar ese ejemplo en el equipo, revise el resultado y tome nota del modo en que se agrupa la información:Take a moment to run that example on your computer, review the output, and take note of how the information is grouped:

  • NAMENAME
  • SINOPSISSYNOPSIS
  • SINTAXISSYNTAX
  • DESCRIPTIONDESCRIPTION
  • VÍNCULOS RELACIONADOSRELATED LINKS
  • COMENTARIOSREMARKS

Como puede ver, los temas de ayuda pueden contener una cantidad enorme de información, y esto no es ni siquiera el tema de ayuda completo.As you can see, help topics can contain an enormous amount of information and this isn't even the entire help topic.

Si bien no es específico de PowerShell, los parámetros son una forma de proporcionar la entrada a un comando.While not specific to PowerShell, a parameter is a way to provide input to a command. Get-Help tiene muchos parámetros que se pueden especificar para devolver el tema de ayuda completo o un subconjunto de él.Get-Help has many parameters that can be specified in order to return the entire help topic or a subset of it.

La sección sintaxis del tema de ayuda que se muestra en el conjunto anterior de resultados muestra todos los parámetros de Get-Help.The syntax section of the help topic shown in the previous set of results lists all of the parameters for Get-Help. A primera vista, parece que los mismos parámetros aparecen seis veces diferentes.At first glance, it appears the same parameters are listed six different times. Cada uno de esos bloques diferentes de la sección de sintaxis es un conjunto de parámetros.Each of those different blocks in the syntax section is a parameter set. Esto significa que el cmdlet Get-Help tiene seis conjuntos de parámetros diferentes.This means the Get-Help cmdlet has six different parameter sets. Si echa un vistazo con más detenimiento, observará que al menos un parámetro es diferente en cada uno de los conjuntos de parámetros.If you take a closer look, you'll notice that at least one parameter is different in each of the parameter sets.

Los conjuntos de parámetros se excluyen mutuamente.Parameter sets are mutually exclusive. Una vez que se usa un parámetro único que solo existe en uno de los conjuntos de parámetros, solo se pueden usar los parámetros incluidos en ese conjunto de parámetros.Once a unique parameter that only exists in one of the parameter sets is used, only parameters contained within that parameter set can be used. Por ejemplo, los parámetros Full y Detailed no se podrían especificar al mismo tiempo porque se encuentran en conjuntos de parámetros diferentes.For example, both the Full and Detailed parameters couldn't be specified at the same time because they are in different parameter sets.

Cada uno de los parámetros siguientes se encuentra en un conjunto de parámetros diferente:Each of the following parameters are in different parameter sets:

  • CompletoFull
  • DetalladoDetailed
  • EjemplosExamples
  • En líneaOnline
  • ParámetroParameter
  • ShowWindowShowWindow

Toda la sintaxis críptica, como, por ejemplo, los corchetes angulares y cuadrados de la sección de sintaxis, significa algo, pero se abordará en el Apéndice A de este libro.All of the cryptic syntax such as square and angle brackets in the syntax section means something but will be covered in Appendix A of this book. Si bien es importante, conocer cuál es la sintaxis críptica a menudo es difícil de recordar para un usuario que no está familiarizado con PowerShell y que puede que no lo utilice a diario.While important, learning the cryptic syntax is often difficult to retain for someone who is new to PowerShell and may not use it everyday.

Para obtener más información para comprender mejor la sintaxis críptica, consulte el Apéndice A.For more information to better understand the cryptic syntax, see Appendix A.

En el caso de los principiantes, hay una manera más fácil de averiguar la misma información, salvo en lenguaje sin formato.For beginners, there's an easier way to figure out the same information except in plain language.

Cuando se especifica el parámetro Full de Get-Help, se devuelve todo el tema de ayuda.When the Full parameter of Get-Help is specified, the entire help topic is returned.

Get-Help -Name Get-Help -Full

Dedique un momento a ejecutar ese ejemplo en el equipo, revise el resultado y tome nota del modo en que se agrupa la información:Take a moment to run that example on your computer, review the output, and take note of how the information is grouped:

  • NAMENAME
  • SINOPSISSYNOPSIS
  • SINTAXISSYNTAX
  • DESCRIPTIONDESCRIPTION
  • PARAMETERSPARAMETERS
  • ENTRADASINPUTS
  • SALIDASOUTPUTS
  • NOTASNOTES
  • EJEMPLOSEXAMPLES
  • VÍNCULOS RELACIONADOSRELATED LINKS

Tenga en cuenta que el uso del parámetro Full devolvió varias secciones adicionales, una de las cuales es la sección PARÁMETROS, que proporciona más información que la sección SINTAXIS críptica.Notice that using the Full parameter returned several additional sections, one of which is the PARAMETERS section that provides more information than the cryptic SYNTAX section.

El parámetro Full es un parámetro de modificador.The Full parameter is a switch parameter. Un parámetro que no requiere un valor se denomina parámetro de modificador.A parameter that doesn't require a value is called a switch parameter. Cuando se especifica un parámetro de modificador, su valor es true y, cuando no se especifica, su valor es false.When a switch parameter is specified, its value is true and when it's not, its value is false.

Si ha estado trabajando en este capítulo en la consola de PowerShell, habrá observado que el comando anterior para mostrar el tema de ayuda completo de Get-Help desapareció de la pantalla sin darle la oportunidad de leerlo.If you've been working through this chapter in the PowerShell console, you noticed that the previous command to display the full help topic for Get-Help flew by on the screen without giving you a chance to read it. Hay una forma mejor de realizar esto.There's a better way.

Help es una función que canaliza Get-Help en una función denominada more, que es un contenedor del archivo ejecutable more.com en Windows.Help is a function that pipes Get-Help to a function named more, which is a wrapper for the more.com executable file in Windows. En la consola de PowerShell, help proporciona las páginas de ayuda de una en una.In the PowerShell console, help provides one page of help at a time. En el ISE, funciona de la misma manera que Get-Help.In the ISE, it works the same way as Get-Help. Mi recomendación es usar la función help en lugar del cmdlet Get-Help, ya que proporciona una mejor experiencia y no requiere escribir tanto.My recommendation is to use the help function instead of the Get-Help cmdlet since it provides a better experience and it's less to type.

Sin embargo, escribir menos no siempre es bueno.Less typing isn't always a good thing, however. Si va a guardar los comandos como un script o va a compartirlos con otro usuario, asegúrese de usar los nombres de parámetro y cmdlet completos.If you're going to save your commands as a script or share them with someone else, be sure to use full cmdlet and parameter names. Los nombres completos se autodocumentan, lo que facilita su comprensión.The full names are self-documenting, which makes them easier to understand. Piense en la siguiente persona que va a tener que leer y entender los comandos.Think about the next person that has to read and understand your commands. Podría ser usted.It could be you. Sus compañeros de trabajo y usted mismo se lo agradecerán.Your coworkers and future self will thank you.

Intente ejecutar los siguientes comandos en la consola de PowerShell en el equipo del entorno de laboratorio de Windows 10.Try running the following commands in the PowerShell console on your Windows 10 lab environment computer.

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

¿Ha observado alguna diferencia en la salida de los comandos enumerados anteriormente al ejecutarlos en el equipo del entorno de laboratorio de Windows 10?Did you notice any differences in the output from the previously listed commands when you ran them on your Windows 10 lab environment computer?

No hay ninguna diferencia excepto el hecho que las dos últimas opciones devuelven los resultados en una página cada vez.There aren't any differences other than the last two options return the results one page at a time. La barra espaciadora se usa para mostrar la siguiente página de contenido al usar la función Help y Ctrl+C cancela los comandos que se están ejecutando en la consola de PowerShell.The spacebar is used to display the next page of content when using the Help function and Ctrl+C cancels commands that are running in the PowerShell console.

En el primer ejemplo, se usa el cmdlet Get-Help; en el segundo, se usa la función Help; y, en el tercero, se omite el parámetro Name al usar la función Help.The first example uses the Get-Help cmdlet, the second uses the Help function, and the third omits the Name parameter when using the Help function. Name es un parámetro posicional y se utiliza de forma posicional en ese ejemplo.Name is a positional parameter and it's being used positionally in that example. Esto significa que el valor se puede especificar sin especificar el nombre del parámetro, siempre que el valor se especifique en la posición correcta.This means the value can be specified without specifying the parameter name, as long as the value itself is specified in the correct position. ¿Cómo sé en qué posición se debe especificar el valor?How did I know what position to specify the value in? Leyendo la ayuda como se muestra en el ejemplo siguiente.By reading the help as shown in the following example.

help Get-Help -Parameter Name
-Name <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 a word that doesn't match any help article titles, Get-Help displays a list of
    articles that include that word 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

Tenga en cuenta que, en el ejemplo anterior, el parámetro Parameter se usó con la función Help para devolver únicamente información del tema de ayuda asociado con el parámetro Name.Notice that in the previous example, the Parameter parameter was used with the Help function to only return information from the help topic for the Name parameter. Esto es mucho más conciso que intentar examinar manualmente lo que a veces parece un tema de ayuda de cien páginas.This is much more concise than trying to manually sift through what sometimes seems like a hundred page help topic.

En función de esos resultados, puede ver que el parámetro Name es posicional y debe especificarse en la posición cero (la primera posición) cuando se usa de forma posicional.Based on those results, you can see that the Name parameter is positional and must be specified in position zero (the first position) when used positionally. El orden en que se especifican los parámetros no importa si se especifica el nombre del parámetro.The order that parameters are specified in doesn't matter if the parameter name is specified.

Otro dato importante es que el parámetro Name espera que el tipo de datos de su valor sea una sola cadena, que se indica mediante <String>.One other important piece of information is that the Name parameter expects the datatype for its value to be a single string, which is denoted by <String>. Si aceptase varias cadenas, el tipo de datos se enumeraría como <String[]>.If it accepted multiple strings, the datatype would be listed as <String[]>.

En ocasiones, puede que no desee mostrar el tema de ayuda completo de un comando.Sometimes you simply don't want to display the entire help topic for a command. Hay algunos otros parámetros además de Full que se pueden especificar con Get-Help o Help.There are a number of other parameters besides Full that can be specified with Get-Help or Help. Intente ejecutar los siguientes comandos en el equipo del entorno de laboratorio de Windows 10:Try running the following commands on your Windows 10 lab environment computer:

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, uso help <command name> con el parámetro Full u Online.I typically use help <command name> with the Full or Online parameter. Si solo me interesan los ejemplos, usaré el parámetro Examples y, si solo me interesa un parámetro específico, usaré el parámetro Parameter.If I'm only interested in the examples, I'll use the Examples parameter and if I'm only interested in a specific parameter, I'll use the Parameter parameter. El parámetro ShowWindow abre el tema de ayuda en una ventana independiente utilizable en búsquedas que se puede colocar en un monitor diferente si tiene varios monitores.The ShowWindow parameter opens the help topic in a separate searchable window that can be placed on a different monitor if you have multiple monitors. He evitado el parámetro ShowWindow porque existe un error conocido en el que no muestra el tema de ayuda completo.I've avoided the ShowWindow parameter because there's a known bug where it doesn't display the entire help topic.

Si desea obtener ayuda en una ventana independiente, mi recomendación es usar el parámetro Online o usar el parámetro Full y canalizar los resultados a Out-GridView, tal como se muestra en el ejemplo siguiente.If you want help in a separate window, my recommendation is to either use the Online parameter or use the Full parameter and pipe the results to Out-GridView, as shown in the following example.

help Get-Command -Full | Out-GridView

Tanto el cmdlet Out-GridView como el parámetro ShowWindow del cmdlet Get-Help requieren un sistema operativo con una GUI (interfaz gráfica de usuario).Both the Out-GridView cmdlet and the ShowWindow parameter of the Get-Help cmdlet require an operating system with a GUI (Graphical User Interface). Generarán un mensaje de error si intenta usarlos en una instancia de Windows Server que se instaló con la opción de instalación Server Core (no-GUI).They will generate an error message if you attempt to use either of them on Windows Server that's been installed using the server core (no-GUI) installation option.

Para usar Get-Help para buscar comandos, use el carácter comodín de asterisco (*) con el parámetro Name.To use Get-Help to find commands, use the asterisk (*) wildcard character with the Name parameter. Especifique un término para el que esté buscando comandos como valor para el parámetro Name , tal como se muestra en el ejemplo siguiente.Specify a term that you're searching for commands on as the value for the Name parameter as shown in the following example.

help *process*
Name                              Category  Module                    Synopsis
----                              --------  ------                    --------
Enter-PSHostProcess               Cmdlet    Microsoft.PowerShell.Core Connects to and ...
Exit-PSHostProcess                Cmdlet    Microsoft.PowerShell.Core Closes an intera...
Get-PSHostProcessInfo             Cmdlet    Microsoft.PowerShell.Core
Debug-Process                     Cmdlet    Microsoft.PowerShell.M... Debugs one or mo...
Get-Process                       Cmdlet    Microsoft.PowerShell.M... Gets the process...
Start-Process                     Cmdlet    Microsoft.PowerShell.M... Starts one or mo...
Stop-Process                      Cmdlet    Microsoft.PowerShell.M... Stops one or mor...
Wait-Process                      Cmdlet    Microsoft.PowerShell.M... Waits for the pr...
Get-AppvVirtualProcess            Function  AppvClient                ...
Start-AppvVirtualProcess          Function  AppvClient                ...

En el ejemplo anterior, los caracteres comodín * no son necesarios y, si se omiten, se produce el mismo resultado.In the previous example, the * wildcard characters are not required and omitting them produces the same result. Get-Help agrega automáticamente los caracteres comodín en segundo plano.Get-Help automatically adds the wildcard characters behind the scenes.

help process

El comando anterior produce los mismos resultados que si se especifica el carácter comodín * en cada extremo del proceso.The previous command produces the same results as specifying the * wildcard character on each end of process.

Prefiero agregarlos, ya que es la opción que siempre funciona de forma coherente.I prefer to add them since that's the option that always works consistently. De lo contrario, solo se requieren en determinados escenarios.Otherwise, they are required in certain scenarios and not others. En cuanto se agrega un carácter comodín en el centro del valor, ya no se agregan automáticamente en segundo plano al valor especificado.As soon as you add a wildcard character in the middle of the value, they're no longer automatically added behind the scenes to the value you specified.

help pr*cess

Ese comando no devuelve ningún resultado a menos que se agregue el carácter comodín * al principio, al final o al principio y al final de pr*cess.No results are returned by that command unless the * wildcard character is added to the beginning, end, or both the beginning and end of pr*cess.

Si el valor que especificó comienza con un guión, se genera un error porque PowerShell lo interpreta como un nombre de parámetro y no existe ese nombre de parámetro para el cmdlet Get-Help.If the value you specified begins with a dash, then an error is generated because PowerShell interprets it as a parameter name and no such parameter name exists for the Get-Help cmdlet.

help -process

Si lo que está intentando buscar son comandos que finalizan con -process, solo tiene que agregar el carácter comodín * al principio del valor.If what you're attempting to look for are commands that end with -process, you only need to add the * wildcard character to the beginning of the value.

help *-process

Al buscar comandos de PowerShell con Get-Help, querrá ser un poco más abstracto en lugar de ser demasiado específico con lo que está buscando.When searching for PowerShell commands with Get-Help, you want to be a little more vague instead of being too specific with what you're searching for.

La búsqueda de process antes solo encontró comandos que contenían process en el nombre del comando y devolvió solo esos resultados.Searching for process earlier found only commands that contained process in the name of the command and returned only those results. Cuando se usa Get-Help para buscar processes, no encuentra ninguna coincidencia con los nombres de comando, por lo que realiza una búsqueda de todos los temas de ayuda de PowerShell en el sistema y devuelve todas las coincidencias que encuentra.When Get-Help is used to search for processes, it doesn't find any matches for command names, so it performs a search of every help topic in PowerShell on your system and returns any matches it finds. Esto hace que devuelva un número enorme de resultados.This causes it to return an enormous number of results.

Get-Help processes
Name                              Category  Module                    Synopsis
----                              --------  ------                    --------
Disconnect-PSSession              Cmdlet    Microsoft.PowerShell.Core Disconnects from...
Enter-PSHostProcess               Cmdlet    Microsoft.PowerShell.Core Connects to and ...
ForEach-Object                    Cmdlet    Microsoft.PowerShell.Core Performs an oper...
Get-PSSessionConfiguration        Cmdlet    Microsoft.PowerShell.Core Gets the registe...
New-PSTransportOption             Cmdlet    Microsoft.PowerShell.Core Creates an objec...
Out-Host                          Cmdlet    Microsoft.PowerShell.Core Sends output to ...
Where-Object                      Cmdlet    Microsoft.PowerShell.Core Selects objects ...
Clear-Variable                    Cmdlet    Microsoft.PowerShell.U... Deletes the valu...
Compare-Object                    Cmdlet    Microsoft.PowerShell.U... Compares two set...
Convert-String                    Cmdlet    Microsoft.PowerShell.U... Formats a string...
ConvertFrom-Csv                   Cmdlet    Microsoft.PowerShell.U... Converts object ...
ConvertTo-Html                    Cmdlet    Microsoft.PowerShell.U... Converts Microso...
ConvertTo-Xml                     Cmdlet    Microsoft.PowerShell.U... Creates an XML-b...
Debug-Runspace                    Cmdlet    Microsoft.PowerShell.U... Starts an intera...
Export-Csv                        Cmdlet    Microsoft.PowerShell.U... Converts objects...
Export-FormatData                 Cmdlet    Microsoft.PowerShell.U... Saves formatting...
Format-List                       Cmdlet    Microsoft.PowerShell.U... Formats the outp...
Format-Table                      Cmdlet    Microsoft.PowerShell.U... Formats the outp...
Get-Random                        Cmdlet    Microsoft.PowerShell.U... Gets a random nu...
Get-Unique                        Cmdlet    Microsoft.PowerShell.U... Returns unique i...
Group-Object                      Cmdlet    Microsoft.PowerShell.U... Groups objects t...
Import-Clixml                     Cmdlet    Microsoft.PowerShell.U... Imports a CLIXML...
Import-Csv                        Cmdlet    Microsoft.PowerShell.U... Creates table-li...
Measure-Object                    Cmdlet    Microsoft.PowerShell.U... Calculates the n...
Out-File                          Cmdlet    Microsoft.PowerShell.U... Sends output to ...
Out-GridView                      Cmdlet    Microsoft.PowerShell.U... Sends output to ...
Select-Object                     Cmdlet    Microsoft.PowerShell.U... Selects objects ...
Set-Variable                      Cmdlet    Microsoft.PowerShell.U... Sets the value o...
Sort-Object                       Cmdlet    Microsoft.PowerShell.U... Sorts objects by...
Tee-Object                        Cmdlet    Microsoft.PowerShell.U... Saves command ou...
Trace-Command                     Cmdlet    Microsoft.PowerShell.U... Configures and s...
Write-Output                      Cmdlet    Microsoft.PowerShell.U... Sends the specif...
Debug-Process                     Cmdlet    Microsoft.PowerShell.M... Debugs one or mo...
Get-Process                       Cmdlet    Microsoft.PowerShell.M... Gets the process...
Get-WmiObject                     Cmdlet    Microsoft.PowerShell.M... Gets instances o...
Start-Process                     Cmdlet    Microsoft.PowerShell.M... Starts one or mo...
Stop-Process                      Cmdlet    Microsoft.PowerShell.M... Stops one or mor...
Wait-Process                      Cmdlet    Microsoft.PowerShell.M... Waits for the pr...
Get-Counter                       Cmdlet    Microsoft.PowerShell.D... Gets performance...
Invoke-WSManAction                Cmdlet    Microsoft.WSMan.Manage... Invokes an actio...
Remove-WSManInstance              Cmdlet    Microsoft.WSMan.Manage... Deletes a manage...
Get-WSManInstance                 Cmdlet    Microsoft.WSMan.Manage... Displays managem...
New-WSManInstance                 Cmdlet    Microsoft.WSMan.Manage... Creates a new in...
Set-WSManInstance                 Cmdlet    Microsoft.WSMan.Manage... Modifies the man...
about_Arithmetic_Operators        HelpFile                            Describes the op...
about_Arrays                      HelpFile                            Describes arrays...
about_Debuggers                   HelpFile                            Describes the Wi...
about_Execution_Policies          HelpFile                            Describes the Wi...
about_ForEach-Parallel            HelpFile                            Describes the Fo...
about_Foreach                     HelpFile                            Describes a lang...
about_Functions                   HelpFile                            Describes how to...
about_Language_Keywords           HelpFile                            Describes the ke...
about_Methods                     HelpFile                            Describes how to...
about_Objects                     HelpFile                            Provides essenti...
about_Parallel                    HelpFile                            Describes the Pa...
about_Pipelines                   HelpFile                            Combining comman...
about_Preference_Variables        HelpFile                            Variables that c...
about_Remote                      HelpFile                            Describes how to...
about_Remote_Output               HelpFile                            Describes how to...
about_Sequence                    HelpFile                            Describes the Se...
about_Session_Configuration_Files HelpFile                            Describes sessio...
about_Variables                   HelpFile                            Describes how va...
about_Windows_PowerShell_5.0      HelpFile                            Describes new fe...
about_WQL                         HelpFile                            Describes WMI Qu...
about_WS-Management_Cmdlets       HelpFile                            Provides an over...
about_ForEach-Parallel            HelpFile                            Describes the Fo...
about_Parallel                    HelpFile                            Describes the Pa...
about_Sequence                    HelpFile                            Describes the Se...

El uso de Help para buscar process devolvió 10 resultados y su uso para buscar processes devolvió 68 resultados.Using Help to search for process returned 10 results and using it to search for processes returned 68 results. Si solo se encuentra un resultado, se mostrará el tema de ayuda en lugar de una lista de comandos.If only one result is found, the help topic itself will be displayed instead of a list of commands.

get-help *hotfix*
NAME
    Get-HotFix

SYNOPSIS
    Gets the hotfixes that have been applied to the local and remote computers.


SYNTAX
    Get-HotFix [-ComputerName <String[]>] [-Credential <PSCredential>] [-Description
    <String[]>] [<CommonParameters>]

    Get-HotFix [[-Id] <String[]>] [-ComputerName <String[]>] [-Credential
    <PSCredential>] [<CommonParameters>]


DESCRIPTION
    The Get-Hotfix cmdlet gets hotfixes (also called updates) that have been installed
    on either the local computer (or on specified remote computers) by Windows Update,
    Microsoft Update, or Windows Server Update Services; the cmdlet also gets hotfixes
    or updates that have been installed manually by users.


RELATED LINKS
    Online Version: http://go.microsoft.com/fwlink/?LinkId=821586
    Win32_QuickFixEngineering http://go.microsoft.com/fwlink/?LinkID=145071
    Get-ComputerRestorePoint
    Add-Content

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"

Ahora vamos a derribar el mito que Help de PowerShell solo puede encontrar comandos que tienen temas de ayuda.Now to debunk the myth that Help in PowerShell can only find commands that have help topics.

help *more*
NAME
    more

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


ALIASES
    None


REMARKS
    None

Observe en el ejemplo anterior que more no tiene un tema de ayuda, pero el sistema Help de PowerShell fue capaz de encontrarlo.Notice in the previous example that more doesn't have a help topic, yet the Help system in PowerShell was able to find it. Solo encontró una coincidencia y devolvió la información de sintaxis básica que verá cuando un comando no tenga un tema de ayuda.It only found one match and returned the basic syntax information that you'll see when a command doesn't have a help topic.

PowerShell contiene numerosos temas de ayuda conceptuales (acerca de).PowerShell contains numerous conceptual (About) help topics. El siguiente comando se puede usar para devolver una lista de todos los temas de ayuda Acerca de del sistema.The following command can be used to return a list of all About help topics on your system.

help About_*

Limitar los resultados a un único tema de ayuda Acerca de muestra el tema de ayuda en lugar de devolver una lista.Limiting the results to one single About help topic displays the actual help topic instead of returning a list.

help about_Updatable_Help

El sistema de ayuda de PowerShell debe actualizarse para que los temas de ayuda Acerca de estén presentes.The help system in PowerShell has to be updated in order for the About help topics to be present. Si, por alguna razón, se produjo un error en la actualización inicial del sistema de ayuda en el equipo, los archivos no estarán disponibles hasta que el cmdlet Update-Help se haya ejecutado correctamente.If for some reason the initial update of the help system failed on your computer, the files will not be available until the Update-Help cmdlet has been run successfully.

Get-CommandGet-Command

Get-Command está diseñado para ayudarle a localizar comandos.Get-Command is designed to help you locate commands. Al ejecutar Get-Command sin ningún parámetro, se devuelve una lista de todos los comandos del sistema.Running Get-Command without any parameters returns a list of all the commands on your system. En el ejemplo siguiente se muestra cómo usar el cmdlet Get-Command para determinar qué comandos existen para trabajar con procesos:The following example demonstrates using the Get-Command cmdlet to determine what commands exist for working with processes:

Get-Command -Noun Process
CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Cmdlet          Debug-Process                                      3.1.0.0    Microsof...
Cmdlet          Get-Process                                        3.1.0.0    Microsof...
Cmdlet          Start-Process                                      3.1.0.0    Microsof...
Cmdlet          Stop-Process                                       3.1.0.0    Microsof...
Cmdlet          Wait-Process                                       3.1.0.0    Microsof...

Observe que, en el ejemplo anterior, en el que se ejecutó Get-Command, se usa el parámetro Noun y se especifica Process como el valor del parámetro Noun.Notice in the previous example where Get-Command was run, the Noun parameter is used and Process is specified as the value for the Noun parameter. ¿Qué ocurre si no sabe cómo usar el cmdlet Get-Command?What if you didn't know how to use the Get-Command cmdlet? Puede usar Get-Help para mostrar el tema de ayuda de Get-Command.You could use Get-Help to display the help topic for Get-Command.

Los parámetros Name , Noun y Verb aceptan caracteres comodín.The Name , Noun , and Verb parameters accept wildcards. En el ejemplo siguiente se muestran los caracteres comodín que se usan con el parámetro Name :The following example shows wildcards being used with the Name parameter:

Get-Command -Name *service*
CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Get-NetFirewallServiceFilter                       2.0.0.0    NetSecurity
Function        Set-NetFirewallServiceFilter                       2.0.0.0    NetSecurity
Cmdlet          Get-Service                                        3.1.0.0    Microsof...
Cmdlet          New-Service                                        3.1.0.0    Microsof...
Cmdlet          New-WebServiceProxy                                3.1.0.0    Microsof...
Cmdlet          Restart-Service                                    3.1.0.0    Microsof...
Cmdlet          Resume-Service                                     3.1.0.0    Microsof...
Cmdlet          Set-Service                                        3.1.0.0    Microsof...
Cmdlet          Start-Service                                      3.1.0.0    Microsof...
Cmdlet          Stop-Service                                       3.1.0.0    Microsof...
Cmdlet          Suspend-Service                                    3.1.0.0    Microsof...
Application     AgentService.exe                                   10.0.14... C:\Windo...
Application     SensorDataService.exe                              10.0.14... C:\Windo...
Application     services.exe                                       10.0.14... C:\Windo...
Application     services.msc                                       0.0.0.0    C:\Windo...
Application     TieringEngineService.exe                           10.0.14... C:\Windo...

No me gusta mucho usar caracteres comodín con el parámetro Name de Get-Command, ya que también devuelve archivos ejecutables que no son comandos nativos de PowerShell.I'm not a fan of using wildcards with the Name parameter of Get-Command since it also returns executable files that are not native PowerShell commands.

Si va a utilizar caracteres comodín con el parámetro Name , recomiendo limitar los resultados con el parámetro CommandType.If you are going to use wildcard characters with the Name parameter, I recommend limiting the results with the CommandType parameter.

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

Una opción mejor es usar el parámetro Verb o Noun o ambos, ya que solo los comandos de PowerShell tienen tanto verbos como sustantivos.A better option is to use either the Verb or Noun parameter or both of them since only PowerShell commands have both verbs and nouns.

¿Ha encontrado algún problema con un tema de ayuda?Found something wrong with a help topic? La buena noticia es que los temas de ayuda de PowerShell son de código abierto y están disponibles en el repositorio PowerShell-Docs de GitHub.The good news is the help topics for PowerShell have been open-sourced and available in the PowerShell-Docs repository on GitHub. Puede compensarlo no solo corrigiendo la información incorrecta para usted, sino también para todos los demás usuarios.Pay it forward by not only fixing the incorrect information for yourself, but everyone else as well. Solo tiene que bifurcar el repositorio de documentación de PowerShell de GitHub, actualizar el tema de ayuda y enviar una solicitud de incorporación de cambios.Simply fork the PowerShell documentation repository on GitHub, update the help topic, and submit a pull request. Una vez aceptada la solicitud de incorporación de cambios, la documentación corregida estará disponible para todo el mundo.Once the pull request is accepted, the corrected documentation is available for everyone.

Actualización de la AyudaUpdating Help

La actualización anterior de la copia local de los temas de ayuda de PowerShell se produjo la primera vez que se solicitó ayuda en relación con un comando.The local copy of the PowerShell help topics was previously updated the first-time help on a command was requested. Se recomienda actualizar periódicamente el sistema de ayuda, ya que de vez en cuando puede haber actualizaciones en el contenido de la ayuda.It's recommended to periodically update the help system because there can be updates to the help content from time to time. El cmdlet Update-Help se usa para actualizar los temas de ayuda.The Update-Help cmdlet is used to update the help topics. Requiere acceso a Internet de forma predeterminada y que se ejecute PowerShell con privilegios elevados como administrador.It requires internet access by default and for you to be running PowerShell elevated as an administrator.

Update-Help
Update-Help : Failed to update Help for the module(s) 'BitsTransfer' with UI culture(s)
{en-US} : The value of the HelpInfoUri key in the module manifest must resolve to a
container or root URL on a website where the help files are stored. The HelpInfoUri
'https://technet.microsoft.com/en-us/library/dd819413.aspx' does not resolve to a
container.
At line:1 char:1
+ Update-Help
+
    + CategoryInfo          : InvalidOperation: (:) [Update-Help], Exception
    + FullyQualifiedErrorId : InvalidHelpInfoUri,Microsoft.PowerShell.Commands.UpdateHel
   pCommand

Update-Help : Failed to update Help for the module(s) 'NetworkControllerDiagnostics,
StorageReplica' 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], Exception
    + FullyQualifiedErrorId : UnableToRetrieveHelpInfoXml,Microsoft.PowerShell.Commands.
   UpdateHelpCommand

Un par de módulos devolvieron errores, lo que no es raro.A couple of the modules returned errors, which is not uncommon. Si el equipo no tiene acceso a Internet, puede usar el cmdlet Save-Help en otro equipo que tenga acceso a Internet para guardar primero la información de ayuda actualizada en un recurso compartido de archivos de la red y, a continuación, usar el parámetro SourcePath de Update-Help para especificar esta ubicación de red para los temas de ayuda.If the machine didn't have internet access, you could use the Save-Help cmdlet on another machine that does have internet access to first save the updated help information to a file share on your network and then use the SourcePath parameter of Update-Help to specify this network location for the help topics.

Considere la posibilidad de configurar una tarea programada o de agregar lógica a su script de perfil de PowerShell para actualizar periódicamente el contenido de la ayuda en el equipo.Consider setting up a scheduled task or adding some logic to your profile script in PowerShell to periodically update the help content on your computer. Los scripts de perfil se abordarán en un capítulo disponible próximamente.Profile scripts will be discussed in an upcoming chapter.

ResumenSummary

En este capítulo ha aprendido a buscar comandos con Get-Help y Get-Command.In this chapter you've learned how to find commands with both Get-Help and Get-Command. Ha aprendido a usar el sistema de ayuda para averiguar cómo usar los comandos una vez que los encuentra.You've learned how to use the help system to figure out how to use commands once you find them. También ha aprendido a actualizar el contenido de los temas de ayuda cuando hay actualizaciones disponibles.You've also learned how to update the content of the help topics when updates are available.

Le reto a que aprenda un comando de PowerShell cada día.My challenge to you is to learn a PowerShell command a day.

Get-Command | Get-Random | Get-Help -Full

RevisarReview

  1. ¿El parámetro DisplayName de Get-Service es posicional?Is the DisplayName parameter of Get-Service positional?
  2. ¿Cuántos conjuntos de parámetros tiene el cmdlet Get-Process?How many parameter sets does the Get-Process cmdlet have?
  3. ¿Qué comandos de PowerShell existen para trabajar con registros de eventos?What PowerShell commands exist for working with event logs?
  4. ¿Qué comando de PowerShell se debe usar para devolver una lista de los procesos de PowerShell que se ejecutan en el equipo?What is the PowerShell command for returning a list of PowerShell processes running on your computer?
  5. ¿Cómo actualiza el contenido de la ayuda de PowerShell que está almacenado en el equipo?How do you update the PowerShell help content that's stored on your computer?

Si desea obtener más información acerca de los temas que se abordan en este capítulo, recomiendo leer los siguientes temas de ayuda de PowerShell.If you want to know more information about the topics covered in this chapter, I recommend reading the following PowerShell help topics.

En el siguiente capítulo, obtendrá información sobre el cmdlet Get-Member, así como los objetos, las propiedades y los métodos.In the next chapter, you'll learn about the Get-Member cmdlet as well as objects, properties, and methods.