Register-ScheduledJob

Ссылка

Модуль:: PSScheduledJob

Создает запланированное задание.

Синтаксис

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>]

Описание

Командлет Register-ScheduledJob создает запланированные задания на локальном компьютере.

Запланированное задание — это Windows PowerShell фоновое задание, которое можно запускать автоматически в однократном или повторяющемся расписании. Запланированные задания хранятся на диске и регистрируются в планировщике заданий, поэтому ими можно управлять в планировщике или с помощью командлетов запланированных заданий в Windows PowerShell.

При запуске запланированного задания создается экземпляр запланированного задания. Экземпляры запланированного задания идентичны фоновым заданиям Windows PowerShell, за исключением того, что результаты сохраняются на диске. Используйте командлеты задания, такие как Start-Job, Get-Job и Receive-Job для запуска, просмотра и получения результатов экземпляров задания.

Используйте Register-ScheduledJob для создания нового запланированного задания. Чтобы указать команды, выполняемые запланированным заданием, используйте параметр ScriptBlock; чтобы указать выполняемый заданием сценарий, используйте параметр FilePath.

Windows PowerShell запланированные задания используют те же триггеры заданий и параметры заданий, которые планировщик задач использует для запланированных задач.

Параметр Trigger командлета Register-ScheduledJob добавляет один или несколько триггеров задания, запускающих задание. Параметр Trigger необязателен, поэтому вы можете добавлять триггеры при создании запланированного задания, добавлять триггеры задания позже, добавлять параметр RunNow для немедленного запуска задания, использовать командлет Start-Job для немедленного запуска задания или сохранять незапланированное запланированное задание в качестве шаблона для других заданий.

Параметр Options позволяет настраивать параметры для запланированного задания. Параметр Options также не является обязательным, поэтому можно указать параметры задания при создании запланированного задания или изменить их в любой другой момент. Поскольку значения параметров задания могут запрещать выполнение запланированного задания, проверьте параметры задания и внимательно настройте их.

Register-ScheduledJob — это одна из коллекций командлетов планирования заданий в модуле PSScheduledJob, включенном в Windows PowerShell.

Дополнительные сведения о запланированных заданиях см. в разделах описания в модуле PSScheduledJob. Импортируйте модуль PSScheduledJob, а затем введите Get-Help about_Scheduled* или просмотрите статью about_Scheduled_Jobs.

Этот командлет впервые появился в Windows PowerShell 3.0.

Примеры

Пример 1. Создание запланированного задания

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

Эта команда создает запланированное задание Archive-Scripts. Значение параметра ScriptBlock содержит команду, которая выполняет рекурсивный поиск PS1-файлов по каталогу $home и копирует их в каталог в общей папке.

Поскольку запланированное задание не содержит триггер, оно не запускается автоматически. Позже можно добавить триггеры заданий, использовать командлет Start-Job для запуска задания по запросу или использовать запланированное задание в качестве шаблона для других запланированных заданий.

Пример 2. Создание запланированного задания с триггерами и настраиваемыми параметрами

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

В этом примере показано, как создать запланированное задание, имеющее триггер задания и пользовательские параметры задания.

Пример 3. Использование хэш-таблиц для указания параметров триггера и задания

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"}

Данная команда работает аналогично командам из примера 2. Она создает запланированное задание, но использует хэш-таблицы для указания значений параметров Trigger и ScheduledJobOption.

Пример 4. Создание запланированных заданий на удаленных компьютерах

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

Эта команда создает запланированное задание EnergyData на нескольких удаленных компьютерах. Запланированное задание выполняет сценарий, который собирает необработанные данные и сохраняет их в журнале выполнения. Запланированные задания создаются на удаленном компьютере, выполняются на удаленном компьютере и сохраняют свои результаты на удаленном компьютере.

Команда использует командлет Invoke-Command для выполнения команды Register-ScheduledJob на компьютерах в файле Servers.txt. Команда Invoke-Command использует параметр Credential для предоставления учетных данных пользователя, имеющего разрешение на создание запланированных заданий на компьютерах в файле Servers.txt.

Команда Register-ScheduledJob создает запланированное задание на удаленном компьютере, на котором выполняется скрипт EnergyData.ps1 по расписанию, заданному триггером задания в переменной $T. Сценарий находится на файловом сервере, доступном для всех используемых в работе компьютерах.

Пример 5. Создание запланированного задания, запускающего скрипт на удаленных компьютерах

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 }

Эта команда использует командлет Register-ScheduledJob, чтобы создать запланированное задание CollectEnergyData на локальном компьютере. Команда использует параметр Trigger, чтобы указать расписание задания, и параметр MaxResultCount, чтобы увеличить число сохраненных результатов до 99.

Задание CollectData использует командлет Invoke-Command для запуска скрипта EnergyData.ps1 в качестве фона на компьютерах, перечисленных в файле Servers.txt. Команда Invoke-Command использует параметр AsJob для создания объекта фонового задания на локальном компьютере, даже если скрипт Energydata.ps1 выполняется на удаленных компьютерах. Эта команда использует параметр Credential, чтобы указать учетную запись пользователя, имеющего разрешение для запуска сценариев на удаленных компьютерах, и параметр Authentication со значением CredSSP, чтобы разрешить делегированные учетные данные.

Параметры

-ArgumentList

Указывает значения для параметров сценария, который определяется параметром FilePath, или для команды, которая определяется параметром ScriptBlock.

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

-Authentication

Задает механизм, используемый при проверке подлинности учетных данных пользователя. Допустимые значения для этого параметра:

Значение по умолчанию
Basic
Credssp
Digest (дайджест)
Kerberos
Согласование
NegotiateWithImplicitCredential

Значение по умолчанию — Default. Дополнительные сведения о значениях этого параметра см. в описании перечисления AuthenticationMechanism в библиотеке MSDN.

Внимание! Проверка подлинности CredSSP, при применении которой учетные данные пользователя передаются на удаленный компьютер, предназначена для команд, требующих проверки подлинности для нескольких ресурсов, например для доступа к удаленной сетевой папке. Этот механизм повышает риск безопасности удаленной операции. Если удаленный компьютер скомпрометирован, учетные данные, передаваемые ему, могут использоваться для управления сетевым сеансом.

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

Запрос подтверждения перед выполнением командлета.

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

-Credential

Указывает учетную запись пользователя, обладающую разрешением для выполнения запланированного задания. По умолчанию используется текущий пользователь.

Введите имя пользователя, например User01 или Domain01\User01, или введите объект PSCredential , например из командлета Get-Credential. Если ввести только имя пользователя, вам будет предложено ввести пароль.

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

-FilePath

Указывает сценарий, запускаемый запланированным заданием. Введите путь к PS1-файлу на локальном компьютере. Чтобы задать значения по умолчанию для параметров сценария, используйте параметр ArgumentList. Каждая команда Register-ScheduledJob должна использовать либо параметр ScriptBlock, либо параметр FilePath.

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

-InitializationScript

Указывает полный путь к сценарию Windows PowerShell (PS1). Сценарий инициализации выполняется в сеансе, который создается для фонового задания перед командами, которые задаются параметром ScriptBlock, или сценарием, который задается параметром FilePath. Сценарий инициализации можно использовать для настройки сеанса, например, для добавления файлов, функций или псевдонимов, создания каталогов или проверки наличия необходимых компонентов.

Чтобы задать сценарий, который выполняет команды основного задания, используйте параметр FilePath.

Если скрипт инициализации создает ошибку (даже неустранимую ошибку), текущий экземпляр запланированного задания не запускается и его состояние завершается сбоем.

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

-MaxResultCount

Указывает, сколько записей результатов задания хранится для запланированного задания. Значение по умолчанию: 32.

Windows PowerShell сохраняет журнал выполнения и результаты каждого активированного экземпляра запланированного задания на диске. Значение этого параметра определяет количество результатов экземпляра задания, сохраняемых для данного запланированного задания. Когда число результатов экземпляра задания превышает это значение, Windows PowerShell удаляет результаты самого старого экземпляра задания, чтобы освободить место для результатов более нового экземпляра задания.

Журнал выполнения задания и результаты задания сохраняются в каталоге $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> на компьютере, на котором создается задание. Чтобы просмотреть журнал выполнения, используйте командлет Get-Job. Чтобы получить результаты задания, используйте командлет Receive-Job.

Параметр MaxResultCount задает значение свойства ExecutionHistoryLength для запланированного задания.

Чтобы удалить текущий журнал выполнения и результаты задания, используйте параметр ClearExecutionHistory командлета Set-ScheduledJob.

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

-Name

Задает имя для запланированного задания. Данное имя также используется для всех запущенных экземпляров этого запланированного задания. Это имя должно быть уникальным на компьютере. Это обязательный параметр.

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

-RunAs32

Запускает запланированное задание в 32-разрядном процессе.

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

-RunEvery

Используется для указания частоты выполнения задания. Например, используйте этот параметр для запуска задания каждые 15 минут.

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

-RunNow

Сразу же запускает задание после запуска командлета Register-ScheduledJob . Этот параметр устраняет необходимость запуска планировщика заданий для выполнения сценария Windows PowerShell сразу после регистрации и не требует от пользователей создания триггера, который указывает начальную дату и время.

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

-ScheduledJobOption

Задает параметры для запланированного задания. Введите объект ScheduledJobOptions , например объект, создаваемый с помощью командлета New-ScheduledJobOption или хэш-табличного значения.

Параметры запланированного задания можно задать при регистрации задания расписания или с помощью командлетов Set-ScheduledJobOption или Set-ScheduledJob для изменения параметров.

Многие параметры и их значения по умолчанию определяют, запускается ли запланированное задание и когда это происходит. Обязательно просмотрите эти параметры перед планированием задания. Описание параметров запланированного задания, включая значения по умолчанию, см. в разделе New-ScheduledJobOption.

Чтобы отправить хэш-таблицу, используйте следующие ключи. Ключи в следующей хэш-таблице ключи приведены со значениями по умолчанию.

@{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

Указывает команды, выполняемые запланированным заданием. Чтобы создать блок скрипта, заключите команды в скобки ( { } ). Чтобы задать значения по умолчанию для параметров команды, используйте параметр ArgumentList.

Каждая команда Register-ScheduledJob должна использовать либо параметр ScriptBlock, либо параметр FilePath.

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

-Trigger

Задает триггеры для запланированного задания. Введите один или несколько объектов ScheduledJobTrigger , таких как объекты, возвращаемые командлетом New-JobTrigger, или хэш-таблицу ключей и значений триггера задания.

Триггер задания запускает задание расписания. Триггер может указывать однократное или регулярное расписание или событие, например вход пользователя в систему или запуск Windows.

Параметр Trigger не является обязательным. Триггер можно добавить при создании запланированного задания, использовать командлет Add-JobTrigger, Set-JobTrigger или Set-ScheduledJob для добавления или изменения триггеров задания позже или использовать командлет Start-Job, чтобы немедленно запустить запланированное задание. Можно также создать и поддерживать запланированное задание без триггера, используемое в качестве шаблона.

Чтобы отправить хэш-таблицу, используйте следующие ключи:

@{Frequency="Once" (или Daily, Weekly, AtStartup, AtLogon); At="3am" (или любая допустимая строка времени); DaysOfWeek="Monday", "Wednesday" (или любое сочетание имен дней); Interval=2 (или любой допустимый интервал частоты); RandomDelay="30minutes" (или любая допустимая строка интервала времени); User="Domain1\User01" (или любой допустимый пользователь; используется только со значением частоты AtLogon) }

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

-WhatIf

Показывает, что произойдет при запуске командлета. Командлет не выполняется.

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

Входные данные

None

В этот командлет нельзя передать входные данные.

Выходные данные

Microsoft.PowerShell.ScheduledJob.ScheduledJobDefinition

Примечания

Каждое запланированное задание сохраняется в подкаталоге каталога $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs на локальном компьютере. Подкаталог называется для запланированного задания и содержит XML-файл для запланированного задания и записей журнала выполнения. Дополнительные сведения о запланированных заданиях на диске см. в описании about_Scheduled_Jobs_Advanced.
Запланированные задания, созданные в Windows PowerShell, отображаются в планировщике заданий в папке "Библиотека планировщика заданий\Microsoft\Windows\PowerShell\ScheduledJobs". Планировщик заданий можно использовать для просмотра и изменения запланированного задания.
Планировщик заданий, средство командной строки SchTasks.exe и командлеты планировщика заданий можно использовать для управления запланированными заданиями, созданные с помощью командлетов запланированных заданий. Однако нельзя использовать командлеты запланированных заданий для управления задачами, созданными в планировщике заданий.
При сбое команды запланированного задания Windows PowerShell возвращает сообщение об ошибке. Однако если сбой задания происходит при попытке планировщика запустить его, ошибка в Windows PowerShell отсутствует.

Если запланированное задание не выполняется, используйте следующие методы, чтобы найти причину.

Убедитесь, что триггер задания настроен правильно. -- Убедитесь, что условия, заданные в параметрах задания, выполнены.
Убедитесь, что учетная запись пользователя, под которой выполняется задание, имеет разрешение на выполнение команд или скриптов в задании.
Проверка журнала планировщика задач на наличие ошибок
Проверьте журнал событий планировщика задач на наличие ошибок.

Дополнительные сведения см. в описании about_Scheduled_Jobs_Troubleshooting.