about_Scripts

Artículo
04/13/2023

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.

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 todos los scripts se ejecuten, incluidos los scripts 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 entra en vigor 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 esto:

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 la ejecución de comandos y scripts en PowerShell, consulte 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 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 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 siguiente comando 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

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 Path la 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, 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 .ps1 archivo.

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 Param instrucción debe ser la primera instrucción de un script, excepto 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, 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 Test-Remote.ps1 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, consulte about_Functions y about_Functions_Advanced_Parameters.

Escribir ayuda para scripts

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, consulte about_Comment_Based_Help.
Ayuda basada en XML 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 . Palabra clave de comentario de ExternalHelp Help. Para obtener más información sobre la palabra clave ExternalHelp, consulte about_Comment_Based_Help. Para obtener más información sobre la ayuda basada en XML, vea Cómo escribir ayuda de cmdlets.

Devolver un valor de salida

De forma predeterminada, los scripts no devuelven un estado de salida cuando finaliza el script. Debe usar la exit instrucción 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. 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 -255 se traduce automáticamente en un número positivo agregando 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 fuera del intervalo específico de la plataforma se traduce al valor de 0.

Ámbito de script y origen de puntos

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 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 generar puntos en el script.

La característica dot sourcing permite ejecutar un script en el ámbito actual en lugar de en el ámbito de script. Al ejecutar un script con origen de puntos, los comandos del script se ejecutan como si hubiera escritolos 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 ejecute el script, puede usar los elementos creados y acceder a sus valores en la sesión.

Para puntear un 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 que se ejecuta el UtilityFunctions.ps1 script, las funciones y variables que crea el script se agregan al ámbito actual.

Por ejemplo, el UtilityFunctions.ps1 script crea la New-Profile función y la $ProfileName variable .

#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 UtilityFunctions.ps1 script en su propio ámbito de script, la New-Profile función y la $ProfileName variable 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 generar el script y ejecutarlo, el script crea la New-Profile función y la variable en la $ProfileName sesión en el ámbito. Una vez que se ejecute el script, puede usar la New-Profile 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, 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 #Requires instrucción para 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 $MyInvocation variable automática contiene 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, . $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, $MyInvocation tiene 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 $PSCommandPath variables y $PSScriptRoot automáticas, que contienen información sobre el script actual, las propiedades PSCommandPath y PSScriptRoot de la $MyInvocation variable contienen información sobre el script que llamó al script actual.
Secciones de datos: puede usar la palabra clave para separar los Data datos de la lógica en scripts. Las secciones de datos también pueden facilitar la localización. Para obtener más información, consulte 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.