Compartir a través de

Register-ScheduledJob

  • Referencia
Módulo:
PSScheduledJob

Crea un trabajo programado.

Syntax

Register-ScheduledJob
        [-ScriptBlock] <ScriptBlock>
        [-Name] <String>
        [-Trigger <ScheduledJobTrigger[]>]
        [-InitializationScript <ScriptBlock>]
        [-RunAs32]
        [-Credential <PSCredential>]
        [-Authentication <AuthenticationMechanism>]
        [-ScheduledJobOption <ScheduledJobOptions>]
        [-ArgumentList <Object[]>]
        [-MaxResultCount <Int32>]
        [-RunNow]
        [-RunEvery <TimeSpan>]
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]
Register-ScheduledJob
        [-FilePath] <String>
        [-Name] <String>
        [-Trigger <ScheduledJobTrigger[]>]
        [-InitializationScript <ScriptBlock>]
        [-RunAs32]
        [-Credential <PSCredential>]
        [-Authentication <AuthenticationMechanism>]
        [-ScheduledJobOption <ScheduledJobOptions>]
        [-ArgumentList <Object[]>]
        [-MaxResultCount <Int32>]
        [-RunNow]
        [-RunEvery <TimeSpan>]
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]

Description

El Register-ScheduledJob cmdlet crea trabajos programados en el equipo local.

Un trabajo programado es un trabajo en segundo plano de Windows PowerShell que se puede iniciar automáticamente en una programación única o periódica. Los trabajos programados se almacenan en disco y se registran en el Programador de tareas. Los trabajos se pueden administrar en el Programador de tareas o mediante los cmdlets trabajo programados en Windows PowerShell.

Cuando se inicia un trabajo programado, crea una instancia del trabajo programado. Las instancias de trabajo programado son idénticas a trabajos en segundo plano de Windows PowerShell, salvo que los resultados se guardan en disco. Use los cmdlets job, como Start-Job, Get-Joby Receive-Job para iniciar, ver y obtener los resultados de las instancias de trabajo.

Use Register-ScheduledJob para crear un nuevo trabajo programado. Para especificar los comandos que ejecuta el trabajo programado, use el parámetro ScriptBlock . Para especificar un script que ejecuta el trabajo, use el parámetro FilePath .

Los trabajos programados de Windows PowerShell usan los mismos desencadenadores de trabajo y las mismas opciones de trabajo que usa el Programador de tareas para las tareas programadas.

El parámetro Trigger de Register-ScheduledJob agrega uno o varios desencadenadores de trabajo que inician el trabajo. El parámetro Trigger es opcional, por lo que puede agregar desencadenadores al crear el trabajo programado, agregar desencadenadores de trabajo más adelante, agregar el parámetro RunNow para iniciar el trabajo inmediatamente, usar el Start-Job cmdlet para iniciar el trabajo inmediatamente en cualquier momento o guardar el trabajo programado no registrado como plantilla para otros trabajos.

El parámetro Options le permite personalizar la configuración de opciones para el trabajo programado. El parámetro Options es opcional, por lo que puede establecer opciones de trabajo al crear el trabajo programado o cambiarlos en cualquier momento. Como la configuración de las opciones del trabajo puede impedir que se ejecute el trabajo programado, revíselas y configúrelas con cuidado.

Register-ScheduledJob es una de una colección de cmdlets de programación de trabajos en el módulo PSScheduledJob que se incluye en Windows PowerShell.

Para obtener más información sobre los trabajos programados, consulte los artículos Acerca de en el módulo PSScheduledJob . Importe el módulo PSScheduledJob y escriba: Get-Help about_Scheduled* o vea about_Scheduled_Jobs.

Este cmdlet se introdujo en Windows PowerShell 3.0.

Ejemplos

Ejemplo 1: Creación de un trabajo programado

En este ejemplo se crea un trabajo programado en el equipo local.

Register-ScheduledJob -Name "Archive-Scripts" -ScriptBlock {
  Get-ChildItem $HOME\*.ps1 -Recurse |
    Copy-Item -Destination "\\Server\Share\PSScriptArchive"
}

Register-ScheduledJob usa el parámetro Name para crear el Archive-Scripts trabajo programado. El parámetro ScriptBlock se ejecuta Get-ChildItem que busca en el $HOME directorio de forma recursiva los .ps1 archivos. El Copy-Item cmdlet copia los archivos en un directorio especificado por el parámetro Destination .

Dado que el trabajo programado no contiene un desencadenador, no se inicia automáticamente. Puede agregar desencadenadores de trabajo con Add-JobTrigger, use el Start-Job cmdlet para iniciar el trabajo a petición o usar el trabajo programado como plantilla para otros trabajos programados.

Ejemplo 2: Creación de un trabajo programado con desencadenadores y opciones personalizadas

En este ejemplo se muestra cómo crear un trabajo programado que tiene un desencadenador de trabajo y opciones de trabajo personalizadas.

$O = New-ScheduledJobOption -WakeToRun -StartIfIdle -MultipleInstancePolicy Queue
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
$path = "\\Srv01\Scripts\UpdateVersion.ps1"
Register-ScheduledJob -Name "UpdateVersion" -FilePath $path -ScheduledJobOption $O -Trigger $T

La $O variable almacena el objeto de opción de trabajo que creó el New-ScheduledJobOption cmdlet. Las opciones inician el trabajo programado incluso si el equipo no está inactivo, reactiva el equipo para ejecutar el trabajo, si es necesario, y permite que varias instancias del trabajo se ejecuten en una serie.

La $T variable almacena el resultado del New-JobTrigger cmdlet para crear un desencadenador de trabajo que inicia un trabajo cada otro lunes a las 9:00 p. m.

La $path variable almacena la ruta de acceso al archivo de UpdateVersion.ps1 script.

Register-ScheduledJob usa el parámetro Name para crear el trabajo programado UpdateVersion . El parámetro FilePath usa $path para especificar el script que ejecuta el trabajo. El parámetro ScheduledJobOption usa las opciones de trabajo almacenadas en $O. El parámetro Trigger usa los desencadenadores de trabajo almacenados en $T.

Ejemplo 3: Uso de tablas hash para especificar un desencadenador y opciones de trabajo programadas

Este ejemplo tiene el mismo efecto que el comando del ejemplo 2. Crea un trabajo programado, mediante tablas hash para especificar los valores de los parámetros Trigger y ScheduledJobOption . Las $O variables y $Tdefinidas en el ejemplo 2 se reemplazan por tablas hash.

$T = @{
  Frequency="Weekly"
  At="9:00PM"
  DaysOfWeek="Monday"
  Interval=2
}
$O = @{
  WakeToRun=$true
  StartIfNotIdle=$false
  MultipleInstancePolicy="Queue"
}
Register-ScheduledJob -Trigger $T -ScheduledJobOption $O -Name UpdateVersion -FilePath "\\Srv01\Scripts\Update-Version.ps1"

Ejemplo 4: Creación de trabajos programados en equipos remotos

En este ejemplo, el trabajo programado energyData se crea en varios equipos remotos. El trabajo programado ejecuta un script que recopila datos sin procesar y lo guarda en un registro en ejecución en el equipo remoto.

$Cred = Get-Credential
$O = New-ScheduledJobOption -WakeToRun -StartIfIdle -MultipleInstancePolicy Queue
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
Invoke-Command -ComputerName (Get-Content Servers.txt) -Credential $Cred -ScriptBlock {
  $params = @{
      Name = "Get-EnergyData"
      FilePath = "\\Srv01\Scripts\Get-EnergyData.ps1"
      ScheduledJobOption = $using:O
      Trigger = $using:T
  }
  Register-ScheduledJob @params
}

La $Cred variable almacena las credenciales en un objeto PSCredential para un usuario con permisos para crear trabajos programados. La $O variable almacena las opciones de trabajo creadas con New-ScheduledJobOption. La $T variable almacena los desencadenadores de trabajo creados con New-JobTrigger.

El Invoke-Command cmdlet usa el parámetro ComputerName para obtener una lista de nombres de servidor del Servers.txt archivo. El parámetro Credential obtiene el objeto de credencial almacenado en $Cred. El parámetro ScriptBlock ejecuta un Register-ScheduledJob comando en los equipos del Servers.txt archivo.

Los parámetros de Register-ScheduledJob se definen mediante $params. Los parámetros Name especifican que el trabajo se denomina Get-EnergyData en cada equipo remoto. FilePath proporciona la ubicación del EnergyData.ps1 script. El script se encuentra en un servidor de archivos que está disponible para todos los equipos participantes. El trabajo se ejecuta según la programación especificada por los desencadenadores de trabajo en $T y las opciones de trabajo de $O.

El Register-ScheduledJob @params comando crea el trabajo programado con los parámetros del bloque de script.

Ejemplo 5: Crear un trabajo programado que ejecute un script en equipos remotos

En este ejemplo se crea el trabajo programado CollectEnergyData en el equipo local. El trabajo se ejecuta en varios equipos remotos.

$Admin = Get-Credential
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
Register-ScheduledJob -Name "CollectEnergyData" -Trigger $T -MaxResultCount 99 -ScriptBlock {
  $params = @{
    AsJob = $true
    ComputerName = (Get-Content Servers.txt)
    FilePath = '\\Srv01\Scripts\Get-EnergyData.ps1'
    Credential = $using:Admin
    Authentication = 'CredSSP'
  }
  Invoke-Command @params
}

La $Admin variable almacena las credenciales de un usuario con permisos para ejecutar los comandos en un objeto PSCredential . La $T variable almacena los desencadenadores de trabajo creados con New-JobTrigger.

El Register-ScheduledJob cmdlet usa el parámetro Name para crear el trabajo programado CollectEnergyData en el equipo local. El parámetro Trigger especifica los desencadenadores de trabajo en $T y el parámetro MaxResultCount aumenta el número de resultados guardados a 99.

El parámetro ScriptBlock define los Invoke-Command parámetros con $params. El parámetro AsJob crea el objeto de trabajo en segundo plano en el equipo local, aunque el Energydata.ps1 script se ejecute en los equipos remotos. El parámetro ComputerName obtiene una lista de nombres de servidor del Servers.txt archivo. El parámetro Credential especifica una cuenta de usuario que tiene permiso para ejecutar scripts en los equipos remotos. Además, el parámetro Authentication especifica un valor de CredSSP para permitir credenciales delegadas.

Invoke-Command @params ejecuta el comando con los parámetros del bloque de script.

Parámetros

-ArgumentList

Especifica los valores de los parámetros del script especificados por el parámetro FilePath o para el comando especificado por el parámetro ScriptBlock .

Type:Object[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Authentication

Especifica el mecanismo que se utiliza para autenticar las credenciales del usuario. El valor predeterminado es Default.

Los valores permitidos para este parámetro son los siguientes:

  • Default
  • Basic
  • Credssp
  • Digest
  • Kerberos
  • Negotiate
  • NegotiateWithImplicitCredential

Para obtener más información sobre los valores de este parámetro, vea AuthenticationMechanism.

Precaución

La autenticación del proveedor de servicios de seguridad de credenciales (CredSSP), en la que las credenciales del usuario se pasan a un equipo remoto para autenticarse, está diseñada para comandos que requieren autenticación en más de un recurso, como el acceso a un recurso compartido de red remoto. Este mecanismo el riesgo de seguridad de la operación remota. Si el equipo remoto se ve comprometido, las credenciales que se pasen a él se pueden utilizar para controlar la sesión de red.

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

Le solicita su confirmación antes de ejecutar el cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Credential

Especifica una cuenta de usuario que tenga permiso para ejecutar el trabajo programado. El valor predeterminado es el usuario actual.

Escriba un nombre de usuario, como User01 o Domain01\User01, o escriba un objeto PSCredential , como uno del Get-Credential cmdlet. Si escribe solo un nombre de usuario, se le pedirá una contraseña.

Las credenciales se almacenan en un objeto PSCredential y la contraseña se almacena como SecureString.

Nota:

Para obtener más información sobre la protección de datos SecureString , consulte ¿Cómo es secure is SecureString?.

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-FilePath

Especifica un script que ejecuta el trabajo programado. Escriba la ruta de acceso a un .ps1 archivo en el equipo local. Para especificar valores predeterminados para los parámetros de script, use el parámetro ArgumentList . Cada Register-ScheduledJob comando debe usar los parámetros ScriptBlock o FilePath .

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-InitializationScript

Especifica la ruta de acceso completa a un script de Windows PowerShell (.ps1). El script de inicialización se ejecuta en la sesión que se crea para el trabajo en segundo plano antes de los comandos especificados por el parámetro ScriptBlock o el script especificado por el parámetro FilePath . Puede usar el script de inicialización para configurar la sesión, como agregar archivos, funciones o alias, crear directorios o comprobar los requisitos previos.

Para especificar un script que ejecute los comandos de trabajo principal, use el parámetro FilePath .

Si el script de inicialización genera un error, incluso un error de no terminación, la instancia actual del trabajo programado no se ejecuta y su estado es Error.

Type:ScriptBlock
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxResultCount

Especifica cuántas entradas de resultados de trabajo se mantienen para el trabajo programado. El valor predeterminado es 32.

Windows PowerShell guarda el historial de ejecución y los resultados de cada instancia desencadenada del trabajo programado en el disco. El valor de este parámetro determina el número de resultados de la instancia de trabajo que se guardan para este trabajo programado. Cuando el número de resultados de la instancia de trabajo supera este valor, Windows PowerShell elimina los resultados de la instancia de trabajo más antigua para dejar espacio a los resultados de la instancia de trabajo más reciente.

El historial de ejecución del trabajo y los resultados del trabajo se guardan en el $HOME\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> directorios en el equipo en el que se crea el trabajo. Para ver el historial de ejecución, use el Get-Job cmdlet . Para obtener los resultados del trabajo, use el Receive-Job cmdlet .

El parámetro MaxResultCount establece el valor de la propiedad ExecutionHistoryLength del trabajo programado.

Para eliminar el historial de ejecución actual y los resultados del trabajo, use el parámetro ClearExecutionHistory del Set-ScheduledJob cmdlet .

Type:Int32
Position:Named
Default value:32
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

Especifica un nombre para el trabajo programado. El nombre también se utiliza para todas las instancias iniciadas del trabajo programado. El nombre debe ser único en el equipo. Este parámetro es obligatorio.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-RunAs32

Ejecuta el trabajo programado en un proceso de 32 bits.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RunEvery

Se usa para especificar la frecuencia con la que ejecutar el trabajo. Por ejemplo, use esta opción para ejecutar un trabajo cada 15 minutos.

Type:TimeSpan
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RunNow

Inicia un trabajo inmediatamente, en cuanto se ejecuta el Register-ScheduledJob cmdlet. Este parámetro elimina la necesidad de desencadenar el Programador de tareas para ejecutar un script de Windows PowerShell inmediatamente después del registro y no requiere que los usuarios creen un desencadenador que especifique una fecha y hora de inicio.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ScheduledJobOption

Establece las opciones para un nuevo trabajo programado Escriba un objeto ScheduledJobOptions , como uno que cree mediante el New-ScheduledJobOption cmdlet o un valor de tabla hash.

Puede establecer opciones para un trabajo programado al registrar el trabajo de programación o usar los Set-ScheduledJobOption cmdlets o Set-ScheduledJob para cambiar las opciones.

Muchas de las opciones y sus valores predeterminados determinan si se ejecuta un trabajo programado y cuándo ocurre esto. Asegúrese de revisar estas opciones antes de programar un trabajo. Para obtener una descripción de las opciones de trabajo programadas, incluidos los valores predeterminados, vea New-ScheduledJobOption.

Para enviar una tabla hash, use las claves siguientes. En la siguiente tabla hash, las claves se muestran con sus valores predeterminados.

@{StartIfOnBattery=$False; StopIfGoingOnBattery=$True; WakeToRun=$False; StartIfNotIdle=$False; IdleDuration="00:10:00"; IdleTimeout="01:00:00"; StopIfGoingOffIdle=$True; RestartOnIdleResume=$False; ShowInTaskScheduler=$True; RunElevated=$False; RunWithoutNetwork=$False; DoNotAllowDemandStart=$False; MultipleInstancePolicy="IgnoreNew"}

Type:ScheduledJobOptions
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ScriptBlock

Especifica los comandos que ejecuta el trabajo programado. Incluya los comandos entre llaves ({}) para crear un bloque de script. Para especificar valores predeterminados para los parámetros de comando, use el parámetro ArgumentList .

Cada Register-ScheduledJob comando debe usar los parámetros ScriptBlock o FilePath .

Type:ScriptBlock
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Trigger

Especifica los desencadenadores para el trabajo programado. Escriba uno o varios objetos ScheduledJobTrigger , como los objetos que devuelve el New-JobTrigger cmdlet o una tabla hash de claves y valores del desencadenador de trabajo.

Un desencadenador de trabajo inicia el trabajo de programación. El desencadenador puede especificar una programación puntual o periódica, o un evento, como cuando un usuario inicia sesión o se inicia Windows.

El parámetro Trigger es opcional. Puede agregar un desencadenador al crear el trabajo programado, usar los Add-JobTriggercmdlets , Set-JobTriggero Set-ScheduledJob para agregar o cambiar desencadenadores de trabajo más adelante o usar el Start-Job cmdlet para iniciar el trabajo programado inmediatamente. También puede crear y mantener un trabajo programado sin un desencadenador que se utiliza como plantilla.

Para enviar una tabla hash, use las siguientes claves:

  • Frecuencia: Diaria, Semanal, AtStartup, AtLogon
  • En: Cualquier cadena de tiempo válida
  • DaysOfWeek : cualquier combinación de nombres de día
  • Intervalo : cualquier intervalo de frecuencia válido
  • RandomDelay: cualquier cadena de intervalo de tiempo válida
  • Usuario: cualquier usuario válido. Solo se usa con el valor de frecuencia AtLogon

Por ejemplo:

@{Frequency="Once"; At="3am"; DaysOfWeek="Monday", "Wednesday"; Interval=2; RandomDelay="30minutes"; User="Domain1\User01"}

Type:ScheduledJobTrigger[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Muestra lo que sucedería si se ejecutara el cmdlet. El cmdlet no se ejecuta.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

No se pueden canalizar objetos a este cmdlet.

Salidas

ScheduledJobDefinition

Este cmdlet devuelve un objeto ScheduledJobDefinition que representa el trabajo registrado.

Notas

Cada trabajo programado se guarda en un subdirectorio del $HOME\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs directorio en el equipo local. El subdirectorio se llama como la tarea programada y contiene un archivo XML para el trabajo programado y registros de su historial de ejecuciones. Para obtener más información sobre los trabajos programados en el disco, consulte about_Scheduled_Jobs_Advanced.

Los trabajos programados que cree en Windows PowerShell aparecen en el Programador de tareas en la carpeta Programador de Library\Microsoft\Windows\PowerShell\ScheduledJobs tareas. Puede usar el Programador de tareas para ver y editar el trabajo programado.

Puede usar el Programador de tareas, la schtasks.exe herramienta de línea de comandos y los cmdlets del Programador de tareas para administrar los trabajos programados que cree con los cmdlets trabajo programados. Sin embargo, no puede usar los cmdlets de trabajo programado para administrar las tareas que cree en el Programador de tareas.

Si se produce un error en un comando de trabajo programado, Windows PowerShell devuelve un mensaje de error. Sin embargo, si se produce un error en el trabajo cuando el Programador de tareas intenta ejecutarlo, el error no está disponible para Windows PowerShell.

Si no se ejecuta un trabajo programado, use los métodos siguientes para encontrar el motivo:

  • Compruebe que el desencadenador de trabajo está configurado correctamente.
    • Compruebe que se cumplen las condiciones establecidas en las opciones de trabajo.
  • Compruebe que la cuenta de usuario con la que se ejecuta el trabajo tiene permiso para ejecutar los comandos o scripts del trabajo.
  • Compruebe el historial del programador de tareas para ver si hay errores.
  • Compruebe si hay errores en el registro de eventos del Programador de tareas.

Para obtener más información, consulte about_Scheduled_Jobs_Troubleshooting.