about_Command_Syntax
Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
Insertar la introducción aquí.
TEMA
about_Command_Syntax
DESCRIPCIÓN BREVE
Describe los diagramas de sintaxis que se usan en Windows PowerShell®.
DESCRIPCIÓN LARGA
Los cmdlets Get-Help y Get-Command muestran diagramas de sintaxis que le permiten construir comandos correctamente. En este tema se explica cómo interpretar los diagramas de sintaxis.
DIAGRAMAS DE SINTAXIS
Cada párrafo de un diagrama de sintaxis del comando representa un formulario válido del comando.
Para construir un comando, siga el diagrama de sintaxis de izquierda a derecha. Seleccione entre los parámetros opcionales y proporcione valores para los marcadores de posición.
Windows PowerShell usa la siguiente notación para los diagramas de sintaxis.
<command-name> -<Required Parameter Name> <Required Parameter Value>
[-<Optional Parameter Name> <Optional Parameter Value>]
[-<Optional Switch Parameters>]
[-<Optional Parameter Name>] <Required Parameter Value>
A continuación se muestra la sintaxis para el cmdlet New-Alias.
New-Alias [-Name] <string> [-Value] <string> [-Description <string>]
[-Force] [-Option {None | ReadOnly | Constant | Private | AllScope}]
[-PassThru] [-Scope <string>] [-Confirm] [-WhatIf] [<CommonParameters>]
La sintaxis se escribe en mayúsculas para facilitar la lectura, pero Windows PowerShell no distingue las mayúsculas de las minúsculas.
El diagrama de sintaxis tiene los siguientes elementos.
NOMBRE DE COMANDO
------------
Los comandos siempre empiezan con un nombre de comando como, por ejemplo, New-Alias. Escriba el nombre del comando o su alias (por ejemplo, "gcm" para Get-Command).
PARÁMETROS
----------
Los parámetros de un comando son opciones que determinan lo que hace el comando. Algunos parámetros toman un "valor", que es la entrada del usuario en el comando.
Por ejemplo, el comando Get-Help tiene un parámetro Name que le permite especificar el nombre del tema del que se muestra la ayuda. El nombre del tema es el valor del parámetro Name.
En un comando de Windows PowerShell, los nombres de los parámetros siempre comienzan con un guion. El guion indica a Windows PowerShell que el elemento del comando es un nombre de parámetro.
Por ejemplo, para usar el parámetro Name de New-Alias, escriba lo siguiente:
-Name
Los parámetros pueden ser obligatorios u opcionales. En un diagrama de sintaxis, los elementos opcionales aparecen entre corchetes ([ ]).
Para más información sobre los parámetros, consulte about_Parameters.
VALORES DE PARÁMETRO
----------------
Un valor de parámetro es la entrada que toma el parámetro. Dado que Windows PowerShell se basa en Microsoft .NET Framework, los valores de parámetro se representan en el diagrama de sintaxis por su tipo .NET.
Por ejemplo, el parámetro Name de Get-Help toma el valor String, que es una cadena de texto (por ejemplo, una o varias palabras entrecomilladas).
[-Name] <string>
El tipo .NET de un valor de parámetro aparece entre corchetes angulares (< >) para indicar que se trata de un marcador de posición de un valor y no de un literal escrito en un comando.
Para usar el parámetro, reemplace el marcador de posición de tipo .NET por un objeto que tenga el tipo .NET especificado.
Por ejemplo, para usar el parámetro Name, escriba "-Name" seguido de una cadena, como la siguiente:
-Name MyAlias
PARÁMETROS SIN VALORES
-------------------------
Algunos parámetros no aceptan entradas, por lo que no tienen ningún valor de parámetro. Los parámetros que no tienen valores se denominan "parámetros de modificador" porque funcionan como modificadores de encendido y apagado. Puede incluirlos (encendido) u omitirlos (apagado) en un comando.
Para usar un parámetro de modificador, escriba el nombre del parámetro, precedido por un guion.
Por ejemplo, para usar el parámetro WhatIf del cmdlet New-Alias, escriba lo siguiente:
-WhatIf
CONJUNTOS DE PARÁMETROS
--------------
Se muestran los parámetros de un comando en conjuntos de parámetros. Los conjuntos de parámetros se parecen a los párrafos de un diagrama de sintaxis.
El cmdlet New-Alias tiene un conjunto de parámetros, pero hay muchos cmdlets que tienen varios. Algunos de los parámetros de cmdlet son exclusivos de un conjunto de parámetros, mientras que hay otros que aparecen en varios conjuntos de parámetros.
Cada conjunto de parámetros representa el formato de un comando válido. Un conjunto de parámetros incluye solo los parámetros que se pueden usar conjuntamente en un comando. Si los parámetros no se pueden usar en el mismo comando, aparecen en distintos conjuntos de parámetros.
Por ejemplo, el cmdlet Get-Random tiene los siguientes conjuntos de parámetros:
Get-Random [[-Maximum] <Object>] [-Minimum <Object>] [-SetSeed <int>]
[<CommonParameters>]
Get-Random [-InputObject] <Object[]> [-Count <int>] [-SetSeed <int>]
[<CommonParameters>]
El primer conjunto de parámetros, que devuelve un número aleatorio, tiene los parámetros Minimum y Maximum. El segundo conjunto de parámetros, que devuelve un objeto seleccionado al azar de un conjunto de objetos, incluye los parámetros InputObject y Count. Ambos conjuntos de parámetros tienen el parámetro Set-Seed y los parámetros comunes.
Estos conjuntos de parámetros indican que puede usar los parámetros InputObject y Count en el mismo comando, pero no puede usar los parámetros Count y Maximum en el mismo comando.
Puede indicar el conjunto de parámetros que desea usar mediante los parámetros de dicho conjunto de parámetros.
Sin embargo, todos los cmdlets también tienen un conjunto de parámetros predeterminado. El conjunto de parámetros predeterminado se usa cuando no se especifican los parámetros que son únicos de un conjunto de parámetros. Por ejemplo, si usa Get-Random sin ningún parámetro, Windows PowerShell da por supuesto que está usando el conjunto de parámetros Number y devuelve un número aleatorio.
En cada conjunto de parámetros, estos aparecen en orden de posición. El orden de los parámetros de un comando solo es relevante cuando se omite el nombre de los parámetros opcionales. Cuando se omite el nombre de los parámetros, Windows PowerShell asigna valores a los parámetros por posición y tipo. Para obtener más información sobre la posición de los parámetros, consulte about_Parameters.
SÍMBOLOS EN LOS DIAGRAMAS DE SINTAXIS
El diagrama de sintaxis muestra el nombre de los comandos, los parámetros de los comandos y los valores de parámetro. También usa símbolos para mostrar cómo construir un comando válido.
Los diagramas de sintaxis usan los siguientes símbolos:
-- El guion (-) indica un nombre de parámetro. En un comando, escriba el guion justo antes del nombre de parámetro sin ningún espacio intermedio, como se muestra en el diagrama de sintaxis.
Por ejemplo, para usar el parámetro Name del cmdlet New-Alias, escriba:
-Name
-- Los corchetes angulares (<>) indican el texto del marcador de posición. No escriba los corchetes angulares o el texto del marcador de posición en un comando. En su lugar, reemplácelo por el elemento que describe.
Los corchetes angulares se usan para identificar el tipo .NET del valor que toma un parámetro. Por ejemplo, para usar el parámetro Name del cmdlet New-Alias, reemplace <string> por una cadena, que es una palabra o un grupo de palabras entre comillas.
-- Los corchetes ([ ]) indican elementos opcionales. Un parámetro y su valor pueden ser opcionales, así como también el nombre de un parámetro necesario.
Por ejemplo, el parámetro Description del cmdlet New-Alias y su valor aparecen entre corchetes porque son opcionales.
[-Description <string>]
Los corchetes también indican que el valor del parámetro Name (<string>) es necesario, pero el nombre del parámetro, "Name", es opcional.
[-Name] <string>
-- Un corchete izquierdo y uno derecho ([]) junto a un tipo .NET indican que el parámetro puede aceptar uno o varios valores de ese tipo. Escriba los valores en una lista separada por comas.
Por ejemplo, el parámetro Name del cmdlet New-Alias toma solo una cadena, pero el parámetro Name de Get-Process puede tomar una o varias cadenas.
New-Alias [-Name] <string>
New-Alias -Name MyAlias
Get-Process [-Name] <string[]>
Get-Process -Name Explorer, Winlogon, Services
--Las llaves ({}) indican una "enumeración", que es un conjunto de valores válidos para un parámetro.
Los valores de las llaves se separan con barras verticales (|). Estas barras indican una elección "exclusivo o"; es decir, puede elegir un solo valor del conjunto de valores que aparecen dentro de las llaves.
Por ejemplo, la sintaxis del cmdlet New-Alias incluye la siguiente enumeración de valores para el parámetro Option:
-Option {None | ReadOnly | Constant | Private | AllScope}
Las llaves y las barras verticales indican que puede elegir cualquiera de los valores mostrados para el parámetro Option, como ReadOnly o AllScope.
-Option ReadOnly
ELEMENTOS OPCIONALES
Los corchetes ([]) envuelven los elementos opcionales. Por ejemplo, en la descripción de la sintaxis del cmdlet New-Alias, el parámetro Scope es opcional. Esto se indica en la sintaxis con los corchetes que encierran el nombre y el tipo del parámetro:
[-Scope <string>]
Los siguientes ejemplos representan usos correctos del cmdlet New-Alias:
New-Alias -Name utd -Value Update-TypeData
New-Alias -Name utd -Value Update-TypeData -Scope global
Un nombre de parámetro puede ser opcional, aunque el valor de dicho parámetro sea necesario. Esto se indica en la sintaxis con los corchetes que encierran el nombre del parámetro pero no el tipo de parámetro, como se muestra en este ejemplo del cmdlet New-Alias:
[-Name] <string> [-Value] <string>
Los siguientes comandos usan correctamente el cmdlet New-Alias. Los comandos producen el mismo resultado.
New-Alias -Name utd -Value Update-TypeData
New-Alias -Name utd Update-TypeData
New-Alias utd -Value Update-TypeData
New-Alias utd Update-TypeData
Si no se incluye el nombre del parámetro en la instrucción tal y como se escribe, Windows PowerShell trata de usar la posición de los argumentos para asignar los valores a los parámetros.
El siguiente ejemplo no está completo:
New-Alias utd
Este cmdlet necesita valores para los parámetros Name y Value.
En los ejemplos de la sintaxis, los corchetes también se usan para dar nombre y convertir los tipos de .NET Framework. En este contexto, los corchetes no indican que un elemento es opcional.
PALABRAS CLAVE
about_Symbols
about_Punctuation
about_Help_Syntax
VEA TAMBIÉN
about_Parameters
Get-Command
Get-Help