about_Scripts

Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0

TEMA

about_Scripts

DESCRIPCIÓN BREVE

Describe cómo ejecutar y escribir scripts en Windows PowerShell®.

DESCRIPCIÓN LARGA

Un script es un archivo de texto sin formato que contiene uno o varios comandos de Windows PowerShell. Los scripts de Windows PowerShell tienen la extensión de nombre de archivo .ps1.

Ejecutar un script es muy parecido a ejecutar un cmdlet. Se escribe la ruta de acceso y el nombre de archivo del script y se usan parámetros para enviar los datos y establecer las opciones. Puede ejecutar scripts en el equipo o en una sesión remota en un equipo diferente.

Cuando se escribe un script, se guarda un comando para su uso posterior, lo que facilita compartirlo con otros usuarios. Y, lo es que más importante, 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 solo comando de un archivo o tan amplios como un programa complejo.

Los scripts tienen características adicionales, como el comentario especial #Requires, el uso de parámetros, la compatibilidad de las secciones de datos y la firma digital para mayor seguridad. También puede escribir temas de ayuda para los scripts y para las funciones del script.

CÓMO EJECUTAR UN SCRIPT

Para poder ejecutar un script, deberá cambiar la directiva de ejecución predeterminada de Windows PowerShell. La directiva de ejecución predeterminada, "Restricted", impide ejecutar todos los scripts, incluidos los scripts que se escriben en el equipo local. Para más información, vea about_Execution_Policies.

La directiva de ejecución se guarda en el Registro, por lo que necesitará cambiarla solo una vez en cada equipo.

Para cambiar la directiva de ejecución, use el procedimiento siguiente.

• 1. Inicie Windows PowerShell con la opción "Ejecutar como administrador".

• 2. En el símbolo del sistema, escriba:

              Set-ExecutionPolicy AllSigned
  

  O bien,

              Set-ExecutionPolicy RemoteSigned
  

El cambio se produce de inmediato.

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 del 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 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, Windows PowerShell no ejecuta scripts cuando se hace doble clic en el icono de script en el Explorador de archivos o cuando se escribe el nombre del script sin una ruta de acceso completa, aunque el script se encuentre en el directorio actual. Para más información sobre cómo ejecutar comandos y scripts en Windows PowerShell, consulte about_Command_Precedence.

EJECUTAR CON POWERSHELL

A partir de Windows PowerShell 3.0, puede ejecutar scripts desde el Explorador de archivos (o el Explorador de Windows, en versiones anteriores de Windows).

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

En el Explorador de archivos (o el Explorador de Windows), haga clic con el botón derecho en el nombre de archivo del script y, a continuación, seleccione "Ejecutar con PowerShell".

La característica "Ejecutar con PowerShell" está diseñada para ejecutar scripts que no tienen los parámetros necesarios y no devuelven la salida del símbolo del sistema.

Para más información, consulte about_Run_With_PowerShell.

EJECUTAR 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 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 script Get-ServiceLog.ps1 en los equipos remotos Server01 y Server02.

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

OBTENER AYUDA SOBRE LOS SCRIPTS

El cmdlet Get-Help obtiene los temas de ayuda sobre scripts, así como 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 se encuentra en la variable de entorno Path, puede omitir la ruta de acceso.

Por ejemplo, para obtener ayuda sobre el script ServicesLog.ps1, escriba:

        get-help C:\admin\scripts\ServicesLog.ps1

CÓMO ESCRIBIR UN SCRIPT

Un script puede contener cualquier comando de Windows PowerShell válido, incluidos comandos individuales, comandos que usan la canalización, funciones y estructuras de control, como instrucciones If y bucles For.

Para escribir un script, inicie un editor de texto (como el Bloc de notas) o un editor de scripts (como el Entorno de scripting integrado [ISE] de Windows PowerShell). Escriba los comandos y guárdelos en un archivo con un nombre de archivo válido y la extensión .ps1.

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, a continuación, guárdelos en un archivo denominado ServiceLog.ps1.

PARÁMETROS DE SCRIPTS

Para definir los parámetros de un script, use una instrucción Param. La instrucción Param debe ser la primera instrucción de un script, excepto para comentarios e instrucciones #Requires.

Los parámetros de script funcionan como los 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 los argumentos con nombre, también son válidas en los scripts.

Cuando se ejecuta el script, los usuarios del script escriben los parámetros después del nombre del script.

En el ejemplo siguiente se muestra un script Test-Remote.ps1 que tiene un parámetro ComputerName. Ambas funciones de script pueden acceder 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 acerca de la instrucción Param y los parámetros de función, vea about_Functions y about_Functions_Advanced_Parameters.

ESCRIBIR AYUDA PARA SCRIPTS

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

• -- Ayuda basada en comentarios para scripts

  Cree un tema de ayuda usando 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 acerca de la ayuda basada en comentarios, vea about_Comment_Based_Help.

• -- Ayuda basada en XML para scripts

  Cree un tema de ayuda basado en XML, del tipo que suele crearse para cmdlets. La ayuda basada en XML es necesaria si los temas de ayuda se traducen a varios idiomas.

  Para asociar el script con el tema de ayuda basado en XML, use la palabra clave de comentario de ayuda .ExternalHelp. Para obtener más información acerca de la palabra clave ExternalHelp, consulte about_Comment_Based_Help. Para obtener más información acerca de la Ayuda basada en XML, consulte "Cómo escribir ayuda de cmdlets" en MSDN (Microsoft Developer Network) Library en el vínculo https://go.microsoft.com/fwlink/?LinkID=123415.

ÁMBITO DEL SCRIPT Y SCRIPTS PREFIJADOS POR PUNTOS

Cada script se ejecuta en su propio ámbito. Las funciones, las variables, los alias y las unidades que se crean en el script solo existen en el ámbito del script. No se puede acceder a estos elementos o 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 puede usar scripts prefijados por puntos.

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

Para convertir un script en un script prefijado por puntos, escriba un punto (.) y un espacio antes de la ruta de acceso del script.

Por ejemplo:

        . C:\scripts\UtilityFunctions.ps1

O bien,

        . .\UtilityFunctions.ps1

Después de que se ejecute el script UtilityFunctions, las funciones y las variables que el script crea 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 "There is already a $profileName profile on this computer."}
            else
       {new-item -type file -path $profile -force }
        }

Si ejecuta el script UtilityFunctions.ps1 en su propio ámbito, la función New-Profile y la variable $ProfileName solo existen mientras se ejecuta el script. Cuando se cierra el script, la función y la variable se quitan, tal 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>

Cuando se crea un script prefijado por puntos y se ejecuta, el script crea la función New-Profile y la variable $ProfileName en la sesión en el ámbito. Después de 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 más información sobre el ámbito, consulte about_Scopes.

SCRIPTS EN MÓDULOS

Un módulo es un conjunto de recursos de Windows 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 entre otros usuarios y para obtener código de fuentes de confianza.

Puede incluir scripts en los módulos o crear un módulo de script, que es un módulo que se compone en parte o en su totalidad de un script y recursos de soporte. Un módulo de script es simplemente un script con una extensión de nombre de archivo .psm1.

Para obtener más información sobre módulos, vea about_Modules.

OTRAS CARACTERÍSTICAS DE SCRIPTS

Windows PowerShell tiene muchas características útiles que se pueden usar en scripts.

• #Requires
  Puede usar una instrucción #Requires para evitar que un script se ejecute sin los módulos o complementos especificados y una versión especificada de Windows PowerShell. Para 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 introdujo en Windows PowerShell 3.0.

• $PSScriptRoot
  Contiene el directorio desde el que se ejecuta un script. En Windows PowerShell 2.0, esta variable es válida únicamente en los módulos de script (.psm1). A partir de Windows PowerShell 3.0, es válida en todos los scripts.

• $MyInvocation
  La variable automática $MyInvocation contiene información sobre el script actual, incluida información sobre cómo se inició o "invocó". Puede usar esta variable y sus propiedades para obtener información sobre el script mientras se está ejecutando. Por ejemplo, la variable $MyInvocation.MyCommand.Path contiene la ruta de acceso y el nombre de archivo del script. $MyInvocation.Line contiene el comando que inició el script, incluidos todos los parámetros y valores.

  A partir de Windows PowerShell 3.0, $MyInvocation tiene dos propiedades nuevas que proporcionan información sobre el script que llamó o invocó al script actual. Los valores de estas propiedades se rellenan solo cuando el invocador o el llamador es un script.

  • -- PSCommandPath contiene la ruta de acceso completa y el nombre del script que llamó o invocó al script actual.

  • -- PSScriptRoot contiene el directorio del script que llamó o invocó al script actual.

  A diferencia de las variables automáticas $PSCommandPath y $PSScriptRoot, que contienen información sobre el script actual, las propiedades PSCommandPath y PSScriptRoot de la variable $MyInvocation contienen información sobre el script que llamó o invocó al script actual.

• Secciones de datos
  Puede usar la palabra clave Data para separar los datos de la lógica en los scripts. Las secciones de datos también facilitan la localización. Para más información, consulte about_Data_Sections y about_Script_Localization.

• 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 pueden incluir comandos no seguros. Para más información, consulte about_Execution_Policies y about_Signing.

VEA TAMBIÉN

about_Command_Precedence

about_Comment_Based_Help

about_Execution_Policies

about_Functions

about_Modules

about_Profiles

about_Requires

about_Run_With_PowerShell

about_Scopes

about_Script_Blocks

about_Signing

Invoke-Command