Acerca de la sintaxis del comando
DESCRIPCIÓN BREVE
Describe los diagramas de sintaxis que se usan en PowerShell.
DESCRIPCIÓN LARGA
Los cmdlets Get-Help y Get-Command muestran diagramas de sintaxis para ayudarle a 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 de comandos representa una forma válida 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.
PowerShell usa la notación siguiente 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 del 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 mejorar la legibilidad, pero PowerShell no distingue mayúsculas de minúsculas.
El diagrama de sintaxis tiene los siguientes elementos.
Nombre de comando
Los comandos siempre comienzan con un nombre de comando, como New-Alias. Escriba el nombre del comando o su alias, como "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 Get-Help comando tiene un parámetro Name que le permite especificar el nombre del tema para el que se muestra la ayuda. El nombre del tema es el valor del parámetro Name .
En un comando de PowerShell, los nombres de parámetro siempre comienzan con un guión. El guión indica a 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 o opcionales. En un diagrama de sintaxis, los elementos opcionales se incluyen entre corchetes [ ].
Para obtener más información sobre los parámetros, consulte about_Parameters.
Valores de parámetros
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 de .NET.
Por ejemplo, el parámetro Name de Get-Help toma un valor "String", que es una cadena de texto, como una sola palabra o varias palabras entre comillas.
[-Name] <string>
El tipo de .NET de un valor de parámetro se incluye entre corchetes angulares < > para indicar que es un marcador de posición para un valor y no un literal que escriba en un comando.
Para usar el parámetro , reemplace el marcador de posición de tipo .NET por un objeto que tenga el tipo de .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 un valor de parámetro. Los parámetros sin valores se denominan "parámetros de conmutador" porque funcionan como los conmutadores activados o desactivados. Los incluye (activado) o los omite (desactivado) de un comando.
Para usar un parámetro switch, simplemente escriba el nombre del parámetro, precedido por un guión.
Por ejemplo, para usar el parámetro WhatIf del New-Alias cmdlet, escriba lo siguiente:
-WhatIf
Conjuntos de parámetros
Los parámetros de un comando se enumeran en conjuntos de parámetros. Los conjuntos de parámetros son similares a los párrafos de un diagrama de sintaxis.
El New-Alias cmdlet tiene un conjunto de parámetros, pero muchos cmdlets tienen varios conjuntos de parámetros. Algunos de los parámetros del cmdlet son únicos para un conjunto de parámetros y otros 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 parámetros que se pueden usar juntos en un comando. Si no se pueden usar parámetros en el mismo comando, aparecen en conjuntos de parámetros independientes.
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 aleatoriamente de un conjunto de objetos, incluye los parámetros InputObject y Count . Ambos conjuntos de parámetros tienen el parámetro SetSeed 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 Maximum y Count en el mismo comando.
Indica qué conjunto de parámetros desea usar mediante los parámetros de ese conjunto de parámetros.
Sin embargo, cada cmdlet también tiene un conjunto de parámetros predeterminado. El conjunto de parámetros predeterminado se usa cuando no se especifican parámetros únicos para un conjunto de parámetros. Por ejemplo, si usa Get-Random sin parámetros, Windows PowerShell supone que usa el conjunto de parámetros Number y devuelve un número aleatorio.
En cada conjunto de parámetros, los parámetros aparecen en orden de posición. El orden de los parámetros de un comando solo importa cuando se omiten los nombres de parámetro opcionales. Cuando se omiten los nombres de parámetro, PowerShell asigna valores a parámetros por posición y tipo. Para obtener más información sobre la posición del parámetro, vea about_Parameters.
Símbolos en diagramas de sintaxis
En el diagrama de sintaxis se muestra el nombre del comando, los parámetros de comando 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 símbolos siguientes:
Un guión
-indica un nombre de parámetro. En un comando, escriba el guión inmediatamente antes del nombre del parámetro sin espacios intermedios, como se muestra en el diagrama de sintaxis.Por ejemplo, para usar el parámetro Name de
New-Alias, escriba:-NameLos corchetes angulares
<>indican texto de marcador de posición. No escriba los corchetes angulares ni el texto del marcador de posición en un comando. En su lugar, lo reemplaza por el elemento que describe.Los corchetes angulares se usan para identificar el tipo de .NET del valor que toma un parámetro. Por ejemplo, para usar el parámetro Name del
New-Aliascmdlet, reemplace por<string>una cadena, que es una sola palabra o un grupo de palabras que se incluyen entre comillas.Los corchetes indican elementos opcionales
[ ]. Un parámetro y su valor pueden ser opcionales o el nombre de un parámetro necesario puede ser opcional.Por ejemplo, el parámetro Description de
New-Aliasy su valor se incluyen entre corchetes porque ambos son opcionales.[-Description <string>]Los corchetes también indican que se requiere el valor
<string>del parámetro Name, pero el nombre del parámetro, "Name", es opcional.[-Name] <string>Un corchete
[]derecho e izquierdo anexado a un tipo .NET indica 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
New-Aliascmdlet 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 MyAliasGet-Process [-Name] <string[]> Get-Process -Name Explorer, Winlogon, ServicesLas llaves
{}indican una "enumeración", que es un conjunto de valores válidos para un parámetro.Los valores de las llaves están separados por barras verticales
|. Estas barras indican una opción "OR exclusiva", lo que significa que solo puede elegir un valor del conjunto de valores que se enumeran dentro de las llaves.Por ejemplo, la sintaxis del
New-Aliascmdlet incluye la enumeración de valores siguiente 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 enumerados para el parámetro Option , como "ReadOnly" o "AllScope".
-Option ReadOnly
Elementos opcionales
Los corchetes rodean los elementos opcionales [] . Por ejemplo, en la descripción de la sintaxis del New-Alias cmdlet, el parámetro Scope es opcional. Esto se indica en la sintaxis entre corchetes alrededor del nombre y el tipo del parámetro:
[-Scope <string>]
Ambos ejemplos son usos correctos del New-Alias cmdlet:
New-Alias -Name utd -Value Update-TypeData
New-Alias -Name utd -Value Update-TypeData -Scope Global
Un nombre de parámetro puede ser opcional incluso si se requiere el valor de ese parámetro. Esto se indica en la sintaxis entre corchetes alrededor del nombre del parámetro, pero no el tipo de parámetro, como en este ejemplo del New-Alias cmdlet:
[-Name] <string> [-Value] <string>
Los siguientes comandos usan correctamente el New-Alias cmdlet . Los comandos generan 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 el nombre del parámetro no se incluye en la instrucción como escrito, Windows PowerShell intenta usar la posición de los argumentos para asignar los valores a los parámetros.
El ejemplo siguiente no está completo:
New-Alias utd
Este cmdlet requiere valores para los parámetros Name y Value .
En los ejemplos de sintaxis, los corchetes también se usan en la nomenclatura y conversión a tipos de .NET Framework. En este contexto, los corchetes no indican que un elemento es opcional.