TEMA
    about_Scripts

DESCRIPCIÓN BREVE
    Describe como se escriben y ejecutan scripts en Windows PowerShell.

DESCRIPCIÓN DETALLADA
    Un script es un archivo de texto sin formato que contiene uno o 
    varios comandos de Windows PowerShell. Los scripts de Windows 
    PowerShell tiene la extensión .ps1. 

    Al escribir un script, se guarda un comando para utilizarlo 
    posteriormente y se facilita su uso compartido con otros 
    usuarios. Y lo que es más importante, un script permite ejecutar 
    los comandos escribiendo simplemente su ruta de acceso y nombre 
    de archivo. Los scripts pueden ser tan simples como un solo 
    comando en un archivo o tan extensos como un programa complejo.

    Los scripts tienen características adicionales, como el 
    comentario especial #Requires, el uso de parámetros, la 
    compatibilidad con secciones de datos y firmas digitales por 
    motivos de seguridad. Asimismo, se pueden escribir temas de Ayuda 
    para los scripts y para cualquier función en los scripts. 

 CÓMO ESCRIBIR UN SCRIPT

    Un script puede contener cualquier comando válido de Windows 
    PowerShell, como un solo comando, 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 Bloc de 
    notas, o un editor de scripts, como 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 están ejecutando en el sistema actual y los 
    guarda en un archivo de registro. El nombre del 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 
    "registroDeServicios.ps1". 


 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", evita la ejecución de 
    todos los scripts, incluidos los que se escriben en el equipo 
    local. Para obtener más información, vea about_Execution_Policies.

    Para ejecutar un script, escriba el nombre completo y la ruta de 
    acceso completa al archivo de script. 

    Por ejemplo, para ejecutar el script registroDeServicios en el 
    directorio C:\Scripts, escriba:

        c:\scripts\registroDeServicios.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 (.\).

    Por ejemplo, para ejecutar el script registroDeServicios.ps1 en 
    el directorio local, escriba:

        .\registroDeServicios.ps1

    Por motivos de seguridad, Windows PowerShell no ejecuta scripts 
    cuando se hace doble clic el icono de un script en el Explorador 
    de Windows o se escribe el nombre del script sin ruta de acceso 
    completa, incluso si el script se encuentra en el directorio 
    actual. Para obtener más información sobre la ejecución de comandos 
    y scripts en Windows PowerShell, vea about_Command_Precedence.


 EJECUTAR LOS SCRIPTS DE FORMA REMOTA

    Para ejecutar un script en un equipo remoto, utilice el parámetro 
    FilePath del cmdlet Invoke-Command.

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

    El comando siguiente ejecuta el script registroDeServicios.ps1 en 
    el equipo remoto Servidor01.

        invoke-command -computername Servidor01 -filepath C:\scripts\registroDeServicios.ps1 



 PARÁMETROS EN LOS SCRIPTS

    Para definir parámetros en un script, utilice una instrucción 
    Param. La instrucción Param debe ser la primera instrucción en un 
    script, salvo en el caso de los comentarios e instrucciones #requires.

    Los parámetros de script funcionan de la misma manera que los 
    parámetros de función. Los valores de parámetro están disponibles 
    para todos los comandos en el 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 un script, se escriben los parámetros después del 
    nombre del script. 

    En el ejemplo siguiente se muestra un script Prueba-Remota.ps1 
    que tiene un parámetro ComputerName. Ambas funciones del script 
    pueden obtener acceso al valor del parámetro ComputerName.

        param ($ComputerName = $(throw "El parámetro ComputerName es obligatorio."))

        function CanPing {
           $error.clear()
           $tmp = test-connection $computername -erroraction SilentlyContinue

           if (!$?) 
               {write-host "Error de ping: $ComputerName."; return $false} 
           else
               {write-host "Ping correcto: $ComputerName"; return $true} 
           }

        function CanRemote {
            $s = new-pssession $computername -erroraction SilentlyContinue

            if ($s -is [System.Management.Automation.Runspaces.PSSession]) 
                {write-host "Prueba remota correcta: $ComputerName."} 
            else
                {write-host "Error de prueba remota: $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> .\prueba-remota.ps1 -computername Servidor01

	Ping correcto: Servidor01
	Error de prueba remota: Servidor01


    Para obtener más información sobre la instrucción Param y los 
    parámetros de función, vea about_Functions y about_Functions_Advan
    ced_Parameters.



 AYUDA PARA LOS SCRIPTS

    El cmdlet Get-Help obtiene ayuda para los scripts, así como para 
    los cmdlets, proveedores y funciones. Si desea obtener la Ayuda para 
    un script, escriba Get-Help así como 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, podrá omitirla.

    Por ejemplo, si desea obtener la Ayuda para el script registroDeServi
    cios.ps1, escriba:

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

    Puede escribir la Ayuda de un script mediante cualquiera de los 
    dos métodos siguientes:

    --  Ayuda basada en comentarios para los scripts

        Se puede crear un tema de la Ayuda usando palabras clave 
        especiales en los comentarios. Para crear la 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 basada en XML para los scripts

        Se puede crear un tema de ayuda basado en XML, del tipo de 
        los que suelen crearse para los cmdlets. La Ayuda basada en 
        XML es necesaria cuando se van a traducir los temas de la Ayuda 
        a varios idiomas. 

        Para asociar el script al tema de la Ayuda basado en XML, se 
        utiliza la palabra clave de comentario de la Ayuda .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 el tema acerca de cómo se escribe 
        la Ayuda de los cmdlets en MSDN Library en 
        https://go.microsoft.com/fwlink/?LinkID=123415.



 ÁMBITO DE LOS SCRIPTS Y SCRIPTS PREFIJADOS POR PUNTOS

    Cada script se ejecuta en su propio ámbito. Los alias, funciones, 
    variables y unidades que se crean en el script existen únicamente 
    en el ámbito del script y no se puede obtener acceso 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 usar un script prefijado por punto.

    La característica de script prefijado por punto permite ejecutar 
    un script en el ámbito actual en lugar de ejecutarlo en el ámbito 
    del script. Cuando se ejecuta un script prefijado por punto, los 
    comandos del script se ejecutan como si se hubieran escrito en el 
    símbolo del sistema. Los alias, funciones, variables y unidades 
    que el script crea se crean en el ámbito en el que se está trabajando. 
    Después de ejecutar el script, se pueden usar los elementos creados 
    y se puede obtener acceso a sus valores en la sesión.

    Para usar un script prefijado por punto, escriba un punto (.) y 
    un espacio delante de la ruta de acceso al script.

    Por ejemplo:

        . C:\scripts\funcionesDeUtilidad.ps1

    -o bien,

        . .\funcionesDeUtilidad.ps1


    Después de ejecutarse el script funcionesDeUtilidad, las funciones y 
    variables creadas por el script se agregan al ámbito actual. 

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

        #En funcionesDeUtilidad.ps1

        function New-Profile
        {
            Write-Host "Se está ejecutando la función New-Profile" 
            $profileName = split-path $profile -leaf

            if (test-path $profile)
               {write-error "Ya hay un perfil $profileName en este equipo."} 
               else
	       {new-item -type file -path $profile -force } 
               }


    Si se ejecuta el script funcionesDeUtilidad.ps1 en su propio 
    ámbito, la función New-Profile y la variable $ProfileName solo 
    existen durante la ejecución del script. Cuando se cierra el 
    script, se quitan la función y la variable, tal y como se muestra 
    en el ejemplo siguiente.

        C:\PS> .\funcionesDeUtilidad.ps1

        C:\PS> New-Profile
        El término 'new-profile' no se reconoce como cmdlet, función, 
        programa ejecutable ni archivo de script. Compruebe el 
        término e inténtelo de nuevo.
        En línea:1 carácter:12
        + new-profile <<<< 
           + CategoryInfo          : ObjectNotFound: (new-profile:String) [], 
           + FullyQualifiedErrorId : CommandNotFoundException

        C:\PS> $profileName
        C:\PS>


    Si usa y ejecuta el script prefijado por punto, el script crea la 
    función New-Profile y la variable $ProfileName en su sesión en su 
    ámbito. Después de ejecutar el script, puede usar la función New-Profile 
    en su sesión, tal y como se muestra en el ejemplo siguiente.

        C:\PS> . .\funcionesDeUtilidad.ps1

        C:\PS> New-Profile


            Directory: C:\Users\juneb\Documents\WindowsPowerShell


            Mode    LastWriteTime       Length Name 
            ----    -------------       ------ ----
            -a---   1/14/2009 3:08 p. m.     0 Microsoft.PowerShellISE_profile.ps1


        C:\PS> $profileName
        Microsoft.PowerShellISE_profile.ps1


    Para obtener más información sobre los ámbitos, vea about_Scopes.



 SCRIPTS EN MÓDULOS

    Un módulo es un conjunto de recursos relacionados de Windows 
    PowerShell que se pueden distribuir como una unidad. Puede usar 
    módulos para organizar los scripts, funciones y otros recursos. 
    También puede utilizarlos para distribuir código a otros usuarios 
    y obtener código de orígenes de confianza.

    Puede incluir scripts en los módulos o crear un módulo de script, 
    que es un módulo que se compone completamente o principalmente de 
    un script y recursos auxiliares. Un módulo de script es 
    simplemente un script con la extensión .psm1.

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



 OTRAS CARACTERÍSTICAS DE LOS SCRIPTS 

    Windows PowerShell incluye numerosas características útiles que 
    se pueden usar en los scripts.

    #Requires 
        Puede usar una instrucción #Requires para evitar que un 
        script se ejecute sin los módulos o complementos 
        especificados y sin la versión especificada de Windows 
        PowerShell. Para obtener más información, vea about_Requires.

    $MyInvocation
        La variable automática $MyInvocation contiene información 
        sobre el comando actual, incluido el script actual. Puede 
        usar esta variable y sus propiedades para obtener información 
        sobre el script durante su ejecución. Por ejemplo, la variable 
        $MyInvocation.MyCommand.Path contiene la ruta de acceso y el nombre 
        de archivo del script.

    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 pueden facilitar la 
        localización. Para obtener más información, vea 
        about_Data_Sections y about_Script_Localization.

    Firma de los scripts
        Puede agregar una firma digital a un script. Según la 
        directiva de ejecución, puede usar firmas digitales para 
        restringir la ejecución de los scripts que podrían incluir 
        comandos inseguros. Para obtener más información, vea 
        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_Scopes
about_Script_Blocks
about_Signing
Invoke-Command




Tabla de contenido