Criar uma tarefa agendada com o módulo ScheduledTasks: ação, gatilho, principal e códigos de resultado

Objetivo

Registrar uma tarefa agendada a partir do PowerShell, com ação, gatilho e principal de execução definidos de forma explícita, e depois confirmar se ela de fato foi executada com sucesso.

Pré-requisitos

Direitos de administrador para registrar uma tarefa que roda como SYSTEM ou como outra conta; o módulo nativo ScheduledTasks.

Passos

1. Defina o que será executado: $action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-NoProfile -File C:\Scripts\cleanup.ps1".
2. Defina quando será executado: $trigger = New-ScheduledTaskTrigger -Daily -At 3am.
3. Defina com qual conta a tarefa roda. Para evitar armazenar e renovar uma senha, execute-a sob uma conta de sistema conhecida: $principal = New-ScheduledTaskPrincipal -UserId "NT AUTHORITY\SYSTEM" -LogonType ServiceAccount -RunLevel Highest. A documentação de Register-ScheduledTask informa que uma senha "is ignored for the well-known system accounts" (é ignorada para as contas de sistema conhecidas), que ela lista como NT AUTHORITY\SYSTEM, NT AUTHORITY\LOCALSERVICE e NT AUTHORITY\NETWORKSERVICE; -RunLevel aceita Limited ou Highest. Já para uma tarefa que precisa de credenciais de rede ou de uma identidade específica, use uma conta de domínio com -LogonType Password (e passe -User/-Password a Register-ScheduledTask), ou uma conta de serviço gerenciado de grupo (DOMAIN\svc-task$) com -LogonType Password e sem nenhuma senha — o Windows obtém a senha da gMSA no Active Directory.
4. Registre: Register-ScheduledTask -TaskName "NightlyCleanup" -Action $action -Trigger $trigger -Principal $principal.
5. Confirme o registro: Get-ScheduledTask -TaskName "NightlyCleanup".
6. Depois de uma execução, leia o último resultado em vez de presumir sucesso: Get-ScheduledTaskInfo -TaskName "NightlyCleanup" | Select-Object LastRunTime, LastTaskResult. Get-ScheduledTaskInfo "gets the last run-time information for a scheduled task" (obtém as informações da última execução de uma tarefa agendada). Um resultado 0 significa sucesso; entre as constantes documentadas do próprio Agendador de Tarefas está SCHED_S_TASK_RUNNING (0x00041301), um valor de status que indica que a instância da tarefa ainda está em execução, e não um erro — trate qualquer código diferente de zero e diferente de "ainda em execução" como uma falha a investigar.

Resultado esperado

Get-ScheduledTask mostra a tarefa como Ready; depois do horário agendado, Get-ScheduledTaskInfo mostra um LastRunTime recente e um LastTaskResult igual a 0.

Limites e base de verificação

Uma tarefa configurada para rodar apenas "when logged on" (somente com o usuário conectado), em vez dos tipos de logon ServiceAccount/Password, não será executada sem supervisão — verifique -LogonType se uma tarefa agendada nunca dispara e não dá nenhum aviso. Para desfazer: Unregister-ScheduledTask -TaskName "NightlyCleanup" -Confirm:$false a remove de forma limpa, sem interação; se talvez for preciso reimportá-la depois com Register-ScheduledTask -Xml, exporte-a antes com Export-ScheduledTask -TaskName "NightlyCleanup" > task-backup.xml. Não é necessário reiniciar; a tarefa fica ativa assim que é registrada.