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