Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Descripción breve
Describe cómo ejecutar y escribir scripts en PowerShell.
Descripción larga
Un script es un archivo de texto sin formato que contiene uno o varios comandos de PowerShell.
Los scripts de PowerShell tienen una extensión de archivo .ps1.
Ejecutar un script es muy parecido a ejecutar un cmdlet. Escriba la ruta de acceso y el nombre de archivo del script y use parámetros para enviar datos y establecer opciones. Puede ejecutar scripts en su equipo o en una sesión remota en otro equipo.
Escribir un script guarda un comando para su uso posterior y facilita el uso compartido con otros usuarios. Lo más importante es que le permite ejecutar los comandos simplemente escribiendo la ruta de acceso del script y el nombre de archivo. Los scripts pueden ser tan simples como un solo comando en un archivo o tan extenso como un programa complejo.
Los scripts tienen características adicionales, como el #Requires comentario especial, el uso de parámetros, compatibilidad con secciones de datos y firma digital para la seguridad.
También puede escribir temas de Ayuda para scripts y para cualquier función del script.
Ejecución de un script
Para poder ejecutar un script en Windows, debe cambiar la directiva de ejecución predeterminada de PowerShell. La directiva de ejecución no se aplica a PowerShell que se ejecuta en plataformas que no son de Windows.
La directiva de ejecución predeterminada, Restricted, impide que se ejecuten todos los scripts, incluidos los scripts que escriba en el equipo local. Para obtener más información, vea about_Execution_Policies.
La directiva de ejecución se guarda en el Registro, por lo que debe cambiarla solo una vez en cada equipo.
Para cambiar la directiva de ejecución, use el procedimiento siguiente.
En el símbolo del sistema, escriba:
Set-ExecutionPolicy AllSigned
o
Set-ExecutionPolicy RemoteSigned
El cambio es efectivo inmediatamente.
Para ejecutar un script, escriba el nombre completo y la ruta de acceso completa al archivo de script.
Por ejemplo, para ejecutar el script de Get-ServiceLog.ps1 en el directorio C:\Scripts, escriba:
C:\Scripts\Get-ServiceLog.ps1
Para ejecutar un script en el directorio actual, escriba la ruta de acceso al directorio actual o use un punto para representar el directorio actual, seguido de una barra invertida (.\).
Por ejemplo, para ejecutar el script de ServicesLog.ps1 en el directorio local, escriba:
.\Get-ServiceLog.ps1
Si el script tiene parámetros, escriba los parámetros y los valores de parámetro después del nombre de archivo del script.
Por ejemplo, el siguiente comando usa el parámetro ServiceName del script de Get-ServiceLog para solicitar un registro de la actividad del servicio WinRM.
.\Get-ServiceLog.ps1 -ServiceName WinRM
Como característica de seguridad, PowerShell no ejecuta scripts al hacer doble clic en el icono de script en el Explorador de archivos o al escribir el nombre del script sin una ruta de acceso completa, incluso cuando el script está en el directorio actual. Para obtener más información sobre la ejecución de comandos y scripts en PowerShell, consulte about_Command_Precedence.
Ejecución con PowerShell
A partir de PowerShell 3.0, puede ejecutar scripts desde el Explorador de archivos.
Para usar la característica "Ejecutar con PowerShell":
Ejecute el Explorador de archivos, haga clic con el botón derecho en el nombre de archivo del script y seleccione "Ejecutar con PowerShell".
La característica "Ejecutar con PowerShell" está diseñada para ejecutar scripts que no tienen parámetros necesarios y no devuelven la salida al símbolo del sistema.
Para más información, consulte about_Run_With_PowerShell.
Ejecución de scripts en otros equipos
Para ejecutar un script en uno o varios equipos remotos, use el parámetro FilePath del cmdlet Invoke-Command.
Escriba la ruta de acceso y el nombre de archivo del script como valor del parámetro FilePath. El script debe residir en el equipo local o en un directorio al que pueda acceder el equipo local.
El siguiente comando ejecuta el script Get-ServiceLog.ps1 en los equipos remotos denominados Server01 y Server02.
Invoke-Command -ComputerName Server01,Server02 -FilePath `
C:\Scripts\Get-ServiceLog.ps1
Obtención de ayuda para scripts
El cmdlet Get-Help obtiene los temas de ayuda para scripts, así como para cmdlets y otros tipos de comandos. Para obtener el tema de ayuda de un script, escriba Get-Help seguido de la ruta de acceso y el nombre de archivo del script. Si la ruta de acceso del script está en la variable de entorno Path, puede omitir esta.
Por ejemplo, para obtener ayuda para el script de ServicesLog.ps1, escriba:
get-help C:\admin\scripts\ServicesLog.ps1
Cómo escribir un script
Un script puede contener cualquier comando válido de PowerShell, incluidos comandos únicos, comandos que usan la canalización, las funciones y las estructuras de control, como instrucciones If y bucles For.
Para escribir un script, abra un nuevo archivo en un editor de texto, escriba los comandos y guárdelos en un archivo con un nombre de archivo válido con la extensión de archivo .ps1.
El ejemplo siguiente es un script sencillo que obtiene los servicios que se ejecutan en el sistema actual y los guarda en un archivo de registro. El nombre de archivo de registro se crea a partir de la fecha actual.
$date = (get-date).dayofyear
get-service | out-file "$date.log"
Para crear este script, abra un editor de texto o un editor de scripts, escriba estos comandos y guárdelos en un archivo denominado ServiceLog.ps1.
Parámetros en scripts
Para definir parámetros en un script, use una instrucción Param. La instrucción Param debe ser la primera instrucción de un script, excepto los comentarios y las instrucciones #Require.
Los parámetros de script funcionan como parámetros de función. Los valores de parámetro están disponibles para todos los comandos del script. Todas las características de los parámetros de función, incluido el atributo Parameter y sus argumentos con nombre, también son válidas en scripts.
Al ejecutar el script, los usuarios escriben los parámetros después del nombre del script.
En el ejemplo siguiente se muestra un script de Test-Remote.ps1 que tiene un parámetro ComputerName. Ambas funciones de script pueden tener acceso al valor de parámetro ComputerName.
param ($ComputerName = $(throw "ComputerName parameter is required."))
function CanPing {
$error.clear()
$tmp = test-connection $computername -erroraction SilentlyContinue
if (!$?)
{write-host "Ping failed: $ComputerName."; return $false}
else
{write-host "Ping succeeded: $ComputerName"; return $true}
}
function CanRemote {
$s = new-pssession $computername -erroraction SilentlyContinue
if ($s -is [System.Management.Automation.Runspaces.PSSession])
{write-host "Remote test succeeded: $ComputerName."}
else
{write-host "Remote test failed: $ComputerName."}
}
if (CanPing $computername) {CanRemote $computername}
Para ejecutar este script, escriba el nombre del parámetro después del nombre del script. Por ejemplo:
C:\PS> .\test-remote.ps1 -computername Server01
Ping succeeded: Server01
Remote test failed: Server01
Para obtener más información sobre la instrucción Param y los parámetros de función, vea about_Functions y about_Functions_Advanced_Parameters.
Ayuda para escribir guiones
Puede escribir un tema de ayuda para un script mediante cualquiera de los dos métodos siguientes:
Ayuda basada en comentarios para scripts
Cree un tema de Ayuda mediante palabras clave especiales en los comentarios. Para crear ayuda basada en comentarios para un script, los comentarios deben colocarse al principio o al final del archivo de script. Para obtener más información sobre la Ayuda basada en comentarios, vea about_Comment_Based_Help.
Ayuda de XML-Based para scripts
Cree un tema de Ayuda basado en XML, como el tipo que normalmente se crea para cmdlets. La Ayuda basada en XML es necesaria si va a traducir temas de Ayuda a varios idiomas.
Para asociar el script al tema de ayuda basado en XML, use la palabra clave de comentario de ayuda .ExternalHelp. Para obtener más información sobre cómo usar la palabra clave ExternalHelp, consulte about_Comment_Based_Help. Para obtener más información sobre la ayuda basada en XML, consulte Cómo escribir ayuda para cmdlets.
Devolver un valor de salida
De forma predeterminada, los scripts no devuelven un estado de salida cuando finaliza el script. Debe usar la instrucción exit para devolver un código de salida de un script. De forma predeterminada, la instrucción exit devuelve 0. Puede proporcionar un valor numérico para devolver un estado de salida diferente. Normalmente, un código de salida distinto de cero indica un error.
En Windows, se permite cualquier número entre [int]::MinValue y [int]::MaxValue.
En Unix, solo se permiten números positivos entre [byte]::MinValue (0) y [byte]::MaxValue (255). Un número negativo en el intervalo de -1 a través de -255 se traduce automáticamente en un número positivo agregando 256. Por ejemplo, -2 se transforma en 254.
En PowerShell, la instrucción exit establece el valor de la variable $LASTEXITCODE. En el Shell de comandos de Windows (cmd.exe), la instrucción exit establece el valor de la variable de entorno %ERRORLEVEL%.
Cualquier argumento que no sea numérico o fuera del intervalo específico de la plataforma se traduce al valor de 0.
Ámbito de script y uso del operador punto
Cada script se ejecuta en su propio ámbito. Las funciones, variables, alias y unidades de disco que se crean en el script solo existen en el ámbito del script. No puede acceder a estos elementos ni a sus valores en el ámbito en el que se ejecuta el script.
Para ejecutar un script en un ámbito diferente, puede especificar un ámbito, como Global o Local, o bien puede usar el operador punto en el script.
La característica de uso del operador punto permite ejecutar un script en el ámbito actual en lugar de en el ámbito de script. Al ejecutar un script que con uso del operador punto, los comandos del script se ejecutan como si los hubiera escrito en la línea de comandos. Las funciones, variables, alias y unidades que crea el script se generan en el ámbito en el que usted trabaja. Una vez que se ejecute el script, puede usar los elementos creados y acceder a sus valores en la sesión.
Para usar el operador punto en un script, escriba un punto (.) y un espacio antes de la ruta de acceso del script.
Por ejemplo:
. C:\scripts\UtilityFunctions.ps1
o
. .\UtilityFunctions.ps1
Después de ejecutar el script de UtilityFunctions.ps1, las funciones y variables que crea el script se agregan al ámbito actual.
Por ejemplo, el script UtilityFunctions.ps1 crea la función New-Profile y la variable $ProfileName.
#In UtilityFunctions.ps1
function New-Profile
{
Write-Host "Running New-Profile function"
$profileName = split-path $profile -leaf
if (test-path $profile)
{write-error "Profile $profileName already exists on this computer."}
else
{new-item -type file -path $profile -force }
}
Si ejecutas el script de UtilityFunctions.ps1 en su propio ámbito de script, la función New-Profile y la variable $ProfileName solo existen mientras se ejecuta el script. Cuando se cierra el script, se quitan la función y la variable, como se muestra en el ejemplo siguiente.
C:\PS> .\UtilityFunctions.ps1
C:\PS> New-Profile
The term 'new-profile' is not recognized as a cmdlet, function, operable
program, or script file. Verify the term and try again.
At line:1 char:12
+ new-profile <<<<
+ CategoryInfo : ObjectNotFound: (new-profile:String) [],
+ FullyQualifiedErrorId : CommandNotFoundException
C:\PS> $profileName
C:\PS>
Al usar el operador punto en el script y ejecutarlo, el script crea la función New-Profile y la variable $ProfileName en su sesión y ámbito. Una vez que se ejecute el script, puede usar la función New-Profile en la sesión, como se muestra en el ejemplo siguiente.
C:\PS> . .\UtilityFunctions.ps1
C:\PS> New-Profile
Directory: C:\Users\juneb\Documents\WindowsPowerShell
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 1/14/2009 3:08 PM 0 Microsoft.PowerShellISE_profile.ps1
C:\PS> $profileName
Microsoft.PowerShellISE_profile.ps1
Para obtener más información sobre el ámbito, consulte about_Scopes.
Scripts en módulos
Un módulo es un conjunto de recursos de PowerShell relacionados que se pueden distribuir como una unidad. Puede usar módulos para organizar los scripts, funciones y otros recursos. También puede usar módulos para distribuir el código a otros usuarios y obtener código de orígenes de confianza.
Puede incluir scripts en los módulos o puede crear un módulo de script, que es un módulo que consta completamente o principalmente de un script y recursos auxiliares. Un módulo de script es simplemente un script con una extensión de archivo .psm1.
Para obtener más información sobre los módulos, consulte about_Modules.
Otras características de script
PowerShell tiene muchas características útiles que puede usar en scripts.
#Requires: puede usar una instrucción#Requirespara evitar que un script se ejecute sin módulos o complementos especificados y una versión especificada de PowerShell. Para obtener más información, consulte about_Requires.$PSCommandPath: contiene la ruta de acceso completa y el nombre del script que se está ejecutando. Este parámetro es válido en todos los scripts. Esta variable automática se presenta en PowerShell 3.0.$PSScriptRoot: contiene el directorio desde el que se ejecuta un script. En PowerShell 2.0, esta variable solo es válida en módulos de script (.psm1). A partir de PowerShell 3.0, es válido en todos los scripts.$MyInvocation: la variable automática$MyInvocationcontiene información sobre el script actual, incluida la información sobre cómo se inició o "se invocó". Puede usar esta variable y sus propiedades para obtener información sobre el script mientras se ejecuta. Por ejemplo, la variable$MyInvocation.MyCommand.Path contiene la ruta de acceso y el nombre de archivo del script.$MyInvocation. La línea contiene el comando que inició el script, incluidos todos los parámetros y valores.A partir de PowerShell 3.0,
$MyInvocationtiene dos nuevas propiedades que proporcionan información sobre el script que llamó o invocó el script actual. Los valores de estas propiedades se rellenan solo cuando el invocador o el autor de la llamada es un script.PSCommandPath contiene la ruta de acceso completa y el nombre del script que llamó o invocó el script actual.
PSScriptRoot contiene el directorio del script que llamó o invocó el script actual.
A diferencia de las variables automáticas
$PSCommandPathy$PSScriptRoot, que contienen información sobre el script actual, las propiedades PSCommandPath y PSScriptRoot de la variable$MyInvocationcontienen información sobre el script desde donde se llamó al script actual.Secciones de datos: puede usar la palabra clave
Datapara separar los datos de la lógica en los scripts. Las secciones de datos también pueden facilitar la localización. Para obtener más información, vea about_Data_Sections y about_Script_Internationalization.Firma de scripts: puede agregar una firma digital a un script. En función de la directiva de ejecución, puede usar firmas digitales para restringir la ejecución de scripts que podrían incluir comandos no seguros. Para obtener más información, consulte about_Execution_Policies y about_Signing.