about_Scripts

Artículo
05/21/2021
Tiempo de lectura: 11 minutos

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 .ps1 extensión de archivo.

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 el equipo o en una sesión remota en otro equipo.

La escritura de un script guarda un comando para su uso posterior y facilita su uso compartido con otros usuarios. Lo más importante es que permite ejecutar los comandos simplemente escribiendo la ruta de acceso del script y el nombre de archivo. Los scripts pueden ser tan sencillos como un único comando en un archivo o tan amplios como un programa complejo.

Los scripts tienen características adicionales, como el comentario especial, el uso de parámetros, la compatibilidad con las secciones de datos y la #Requires 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, , impide que se ejecuten todos los scripts, incluidos Restricted los que se escriben 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

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 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 diagonal inversa de ruta de acceso ( .\ ).

Por ejemplo, para ejecutar el script 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 comando siguiente usa el parámetro ServiceName del script 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 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 cómo ejecutar comandos y scripts en PowerShell, vea about_Command_Precedence.

Ejecutar con PowerShell

A partir de PowerShell 3.0, puede ejecutar scripts desde Explorador de archivos.

Para usar la característica "Ejecutar con PowerShell":

Ejecute 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 resultados 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 Invoke-Command cmdlet .

Escriba la ruta de acceso y el nombre de archivo del script como valor del parámetro FilePath. El script debe encontrarse en el equipo local o en un directorio al que el equipo local pueda acceder.

El comando siguiente ejecuta el Get-ServiceLog.ps1 script en los equipos remotos denominados Server01 y Server02.

Invoke-Command -ComputerName Server01,Server02 -FilePath `
  C:\Scripts\Get-ServiceLog.ps1

Obtener 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 Path variable de entorno, puede omitir la ruta de acceso.

Por ejemplo, para obtener ayuda para el script 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, funciones y 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 .ps1 extensión de archivo.

El ejemplo siguiente es un script simple 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 Param instrucción debe ser la primera instrucción de un script, excepto para los comentarios y las #Require instrucciones.

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, incluidos el atributo Parameter y sus argumentos con nombre, también son válidas en los scripts.

Al ejecutar el script, los usuarios del script escriben los parámetros después del nombre del script.

En el ejemplo siguiente se Test-Remote.ps1 muestra un script que tiene un parámetro ComputerName. Ambas funciones de script pueden tener acceso al valor del 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.

Escritura de ayuda para scripts

Puede escribir un tema de ayuda para un script mediante cualquiera de los dos métodos siguientes:

Comment-Based ayuda 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.
XML-Based ayuda para scripts

Cree un tema de Ayuda basado en XML, como el tipo que se crea normalmente para los 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 . Palabra clave de comentario de La Ayuda de ExternalHelp. Para obtener más información sobre la palabra clave ExternalHelp, vea about_Comment_Based_Help. Para obtener más información sobre la ayuda basada en XML, vea How to Write Cmdlet Help.

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 exit instrucción devuelve 0 . Puede proporcionar un valor numérico para devolver un estado de salida diferente. Un código de salida distinto de cero suele indicar un error.

En Windows, se permite cualquier número [int]::MinValue entre [int]::MaxValue y .

En Unix, solo se permiten números positivos entre [byte]::MinValue (0) [byte]::MaxValue y (255). Un número negativo en el intervalo de -1 hasta se traduce automáticamente en un número positivo mediante la -255 adición de 256. Por ejemplo, -2 se transforma en 254 .

En PowerShell, la exit instrucción establece el valor de la $LASTEXITCODE variable. En el Shell de comandos de Windows (cmd.exe), la instrucción exit establece el valor de la %ERRORLEVEL% variable de entorno.

Cualquier argumento que no sea numérico o esté fuera del intervalo específico de la plataforma se traduce al valor de 0 .

Ámbito de script y dot sourcing

Cada script se ejecuta en su propio ámbito. Las funciones, variables, alias y unidades que se crean en el script solo existen en el ámbito del script. No se 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 incluir el origen del script.

La característica dot sourcing le permite ejecutar un script en el ámbito actual en lugar de en el ámbito del script. Cuando se ejecuta un script con origen de puntos, los comandos del script se ejecutan como si los hubiera escrito en el símbolo del sistema. Las funciones, variables, alias y unidades que crea el script se crean en el ámbito en el que está trabajando. Una vez que se ejecuta el script, puede usar los elementos creados y acceder a sus valores en la sesión.

Para dot source a script, escriba un punto (.) y un espacio antes de la ruta de acceso del script.

Por ejemplo:

. C:\scripts\UtilityFunctions.ps1

. .\UtilityFunctions.ps1

Una vez UtilityFunctions.ps1 que se ejecuta el script, las funciones y variables que crea se agregan al ámbito actual.

Por ejemplo, el UtilityFunctions.ps1 script crea la función y la variable New-Profile $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 ejecuta el script en su propio ámbito de script, la función y la UtilityFunctions.ps1 variable solo existen mientras se ejecuta el New-Profile $ProfileName 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 dot source el script y ejecutarlo, el script crea la función New-Profile y la variable en la sesión en el $ProfileName ámbito. Una vez que se ejecuta el script, puede usar New-Profile la función 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, vea 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, las funciones y otros recursos. También puede usar módulos para distribuir el código a otros usuarios y para 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 por completo o principalmente de un script y recursos de soporte técnico. 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, vea about_Modules.

Otras características de script

PowerShell tiene muchas características útiles que puede usar en scripts.

#Requires - Puede usar una instrucción para evitar que un script se ejecute sin módulos o complementos especificados y #Requires una versión especificada de PowerShell. Para obtener más información, vea about_Requires.
$PSCommandPath : contiene la ruta de acceso completa y el nombre del script que se ejecuta. Este parámetro es válido en todos los scripts. Esta variable automática se introdujo 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 contiene información sobre el script actual, incluida información sobre cómo $MyInvocation se inició o "invocó". Puede usar esta variable y sus propiedades para obtener información sobre el script mientras se ejecuta. Por ejemplo, $MyInvocation . La variable 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, tiene dos nuevas propiedades que proporcionan información sobre el script que llamó o $MyInvocation 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ó al script actual o lo invocó.
- PSScriptRoot contiene el directorio del script que llamó al script actual o lo invocó.
A diferencia de las variables automáticas y , que contienen información sobre el script actual, las propiedades $PSCommandPath $PSScriptRoot PSCommandPath y PSScriptRoot de la variable contienen información sobre el script que llamó $MyInvocation al script actual.
Secciones de datos: puede usar la palabra Data clave para separar los datos de la lógica en 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. Dependiendo 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, vea about_Execution_Policies y about_Signing.