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 cmdlet Register-ScheduledJob crea trabajos programados en el equipo local.

Un trabajo programado es un trabajo en segundo plano 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, por lo que pueden administrarse en el Programador de tareas o mediante los cmdlets de trabajos programados de 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-Job y Receive-Job para iniciar, ver y obtener los resultados de las instancias de trabajo.

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

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

El parámetro Trigger de Register-ScheduledJob agrega uno o más 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 cmdlet Start-Job para iniciar el trabajo inmediatamente en cualquier momento o guardar el trabajo programado no registrado como plantilla para otros trabajos.

El parámetro Options permite personalizar la configuración de las opciones del trabajo programado. El parámetro Options también es opcional, por lo que puede establecer las opciones de trabajo al crear el trabajo programado o cambiarlas 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 más información sobre los trabajos programados, vea los temas 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: Create un trabajo programado

PS C:\> Register-ScheduledJob -Name "Archive-Scripts" -ScriptBlock { dir $home\*.ps1 -Recurse | Copy-Item -Destination "\\Server\Share\PSScriptArchive" }

Este comando crea el trabajo programado Archive-Scripts. El valor del parámetro ScriptBlock contiene un comando que busca archivos .ps1 de forma recursiva en el directorio $home y los copia en un directorio de un recurso compartido de archivos.

Como el trabajo programado no contiene un desencadenador, no se inicia automáticamente. Puede usar los desencadenadores de trabajo agregados más adelante, use el cmdlet Start-Job para iniciar el trabajo a petición o usar el trabajo programado como plantilla para otros trabajos programados.

Ejemplo 2: Create un trabajo programado con desencadenadores y opciones personalizadas

The first command uses the New-ScheduledJobOption cmdlet to create a job option object, which it saves in the $O parameter. The options start the scheduled job even if the computer is not idle, wake the computer to run the job, if necessary, and allows multiple instances of the job to run in a series.
PS C:\> $O = New-ScheduledJobOption -WakeToRun -StartIfNotIdle -MultipleInstancesPolicy Queue


The second command uses the New-JobTrigger cmdlet to create job trigger that starts a job every other Monday at 9:00 PM.
PS C:\> $T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2

This command creates the UpdateVersion scheduled job, which runs the UpdateVersion.ps1 script every Monday at 9:00 p.m. The command uses the *FilePath* parameter to specify the script that the job runs. It uses the *Trigger* parameter to specify the job triggers in the $T variable and the *ScheduledJobOption* parameter to specify the option object in the $O variable.
PS C:\> Register-ScheduledJob -Name "UpdateVersion" -FilePath "\\Srv01\Scripts\UpdateVersion.ps1" -Trigger $T -ScheduledJobOption $O

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

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

PS C:\> Register-ScheduledJob -FilePath "\\Srv01\Scripts\Update-Version.ps1" -Trigger @{Frequency=Weekly; At="9:00PM"; DaysOfWeek="Monday"; Interval=2} -ScheduledJobOption @{WakeToRun; StartIfNotIdle; MultipleInstancesPolicy="Queue"}

Este comando tiene el mismo efecto que el comando del ejemplo 2. Crea un trabajo programado, pero utiliza tablas hash para especificar los valores de los parámetros Trigger y ScheduledJobOption.

Ejemplo 4: Create trabajos programados en equipos remotos

PS C:\> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock {Register-ScheduledJob -Name "Get-EnergyData" -FilePath "\\Srv01\Scripts\Get-EnergyData.ps1" -ScheduledJobOption $O -Trigger $T } -Credential $Cred

Este comando crea el trabajo programado EnergyData en varios equipos remotos. El trabajo programado ejecuta un script que recopila los datos sin procesar y los guarda en un registro de ejecución. Los trabajos programados se crean en el equipo remoto, se ejecutan en el equipo remoto y almacenan los resultados en el equipo remoto.

El comando usa el cmdlet Invoke-Command para ejecutar un comando Register-ScheduledJob en los equipos del archivo Servers.txt. El comando Invoke-Command usa el parámetro Credential para proporcionar las credenciales de un usuario que tiene permiso para crear trabajos programados en los equipos del archivo Servers.txt.

El comando Register-ScheduledJob crea un trabajo programado en el equipo remoto que ejecuta el script de EnergyData.ps1 en el programado especificado por el desencadenador de trabajo en la variable $T. El script se encuentra en un servidor de archivos que está disponible para todos los equipos participantes.

Ejemplo 5: Create un trabajo programado que ejecuta un script en equipos remotos

PS C:\> Register-ScheduledJob -Name "CollectEnergyData" -Trigger $T -MaxResultCount 99 -ScriptBlock { Invoke-Command -AsJob -ComputerName (Servers.txt) -FilePath "\\Srv01\Scripts\Get-EnergyData.ps1" -Credential $Admin -Authentication CredSSP }

Este comando usa el cmdlet Register-ScheduledJob para crear el trabajo programado CollectEnergyData en el equipo local. El comando utiliza el parámetro Trigger para especificar la programación del trabajo y el parámetro MaxResultCount para aumentar el número de resultados guardados a 99.

El trabajo CollectEnergyData usa el cmdlet Invoke-Command para ejecutar el script de EnergyData.ps1 como fondo en los equipos enumerados en el archivo Servers.txt. El comando Invoke-Command usa el parámetro AsJob para crear el objeto de trabajo en segundo plano en el equipo local, aunque el script de Energydata.ps1 se ejecute en los equipos remotos. El comando utiliza el parámetro Credential para especificar una cuenta de usuario que tenga permiso para ejecutar scripts en los equipos remotos, y el parámetro Authentication con un valor de CredSSP para admitir credenciales delegadas.

Parámetros

-ArgumentList

Especifica valores para los parámetros del script que especifica el parámetro FilePath o para el comando que especifica 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. Los valores permitidos para este parámetro son los siguientes:

  • Default
  • Básico
  • Credssp
  • Digest
  • Kerberos
  • Negotiate
  • NegotiateWithImplicitCredential

El valor predeterminado es Default. Para obtener más información sobre los valores de este parámetro, vea AuthenticationMechanism Enumeration en MSDN Library.

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 que se va a autenticar, 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:Default
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 cmdlet Get-Credential. Si escribe solo un nombre de usuario, se le pedirá una contraseña.

Type:PSCredential
Position:Named
Default value:Current user
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 archivo .ps1 en el equipo local. Para especificar los valores predeterminados de los parámetros de script, use el parámetro ArgumentList. Cada comando Register-ScheduledJob 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 creada 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 ejecuta los comandos del 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 los directorios $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> del equipo en el que se crea el trabajo. Para ver el historial de ejecución, use el cmdlet Get-Job. Para obtener los resultados del trabajo, use el cmdlet Receive-Job.

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 cmdlet Set-ScheduledJob.

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:False
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 cmdlet Register-ScheduledJob . 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:False
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 cmdlet New-ScheduledJobOption o un valor de tabla hash.

Puede establecer opciones para un trabajo programado al registrar el trabajo de programación o usar los cmdlets Set-ScheduledJobOption 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, consulte 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 los valores predeterminados de los parámetros de comando, use el parámetro ArgumentList.

Cada comando Register-ScheduledJob 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 cmdlet New-JobTrigger 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 cmdlets Add-JobTrigger, Set-JobTrigger o Set-ScheduledJob para agregar o cambiar desencadenadores de trabajo más adelante o usar el cmdlet Start-Job 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:

@{Frequency="Once" (o Daily, Weekly, AtStartup, AtLogon); At="3am" (o cualquier cadena de tiempo válida); DaysOfWeek="Monday", "Wednesday" (o cualquier combinación de nombres de día); Interval=2 (o cualquier intervalo de frecuencia válido); RandomDelay="30minutes" (o cualquier cadena de intervalo de tiempo válido); User="Domain1\User01" (o cualquier usuario válido; solo se usa con el valor de frecuencia AtLogon) }

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 puede canalizar la entrada a este cmdlet.

Salidas

ScheduledJobDefinition

Notas

  • Cada trabajo programado se guarda en un subdirectorio del directorio $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs del equipo local. El subdirectorio se denomina para el trabajo programado y contiene un archivo XML para el trabajo programado y los registros de su historial de ejecución. Para más información sobre los trabajos programados en el disco, consulte about_Scheduled_Jobs_Advanced.

  • Los trabajos programados que se crean en Windows PowerShell aparecen en el Programador de tareas, en la carpeta Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs. Puede usar el Programador de tareas para ver y editar el trabajo programado.

  • Puede usar el Programador de tareas, la herramienta de línea de comandos SchTasks.exe y los cmdlets del Programador de tareas para administrar los trabajos programados que se crean con cmdlets ScheduledJob. Sin embargo, los cmdlets ScheduledJob no sirven para administrar las tareas que se creen 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.