/ScheduledTaskManagement

A PowerShell module for non-interactive management of Scheduled Tasks.

Primary LanguagePowerShellApache License 2.0Apache-2.0

ScheduledTaskManagement

azuredevops-build github-release powershellgallery-version

Introduction

A PowerShell module for non-interactive management of Scheduled Tasks.

Requirements

Installation

The module can either be installed, or imported from a local copy of this git repository.

via Install

# Latest, for the current user
Install-Module -Name ScheduledTaskManagement -Repository PSGallery -Scope CurrentUser -Verbose

# Specific version, for the current user
Install-Module -Name ScheduledTaskManagement -Repository PSGallery -RequiredVersion x.x.x -Scope CurrentUser -Verbose

# Latest, for all users
Install-Module -Name ScheduledTaskManagement -Repository PSGallery -Scope AllUsers -Verbose

If prompted to trust the repository, type Y and enter.

via Import

# Clone the git repository
git clone https://github.com/theohbrothers/ScheduledTaskManagement.git
cd ScheduledTaskManagement\

# Checkout version to use
git checkout vx.x.x

# Import the module
Import-Module .\src\ScheduledTaskManagement\ScheduledTaskManagement.psm1 -Force -Verbose

The module is now ready for use.

Usage

Scheduled tasks

To create or apply scheduled tasks, first define the properties of each task in .ps1 or .json definition file(s). Then feed definition file path(s), definition directory path(s), or definition objects to Setup-ScheduledTask to create or apply them non-interactively.

The properties of definition objects are based off the parameters of the following cmdlets from the ScheduledTasks module:

Several parameters such as -At of New-ScheduledTaskTrigger involve values whose types prevent them from being expressed purely in non-PowerShell code. The module accounts for such values by enabling them to be intuitively yet declaratively defined even in .json format. Those values will be converted into their relevant PowerShell types as part of a serialization process right before task creation or application. Through so, scheduled tasks can be managed as code as part of the practice of Infrastructure-as-Code (IaC).

Sample definition files can be found here.

Functions

Parameters

Setup-ScheduledTask -DefinitionFile <string[]> [-AsJson] [<CommonParameters>]
Setup-ScheduledTask -DefinitionDirectory <string[]> [-AsJson] [<CommonParameters>]
Setup-ScheduledTask -DefinitionObject <Object[]> [<CommonParameters>]

Examples

# Via .ps1 definition file
Setup-ScheduledTask -DefinitionFile "C:\path\to\definition.ps1"

# Via .json definition file
Setup-ScheduledTask -DefinitionFile "C:\path\to\definition.json" -AsJson

# Via directory containing .ps1 definition file(s)
Setup-ScheduledTask -DefinitionDirectory "C:\path\to\definition\directory\"

# Via directory containing .json definition file(s)
Setup-ScheduledTask -DefinitionDirectory "C:\path\to\definition\directory\" -AsJson

# Via definition object(s)
$tasks = . "C:\path\to\definition.ps1"                                                                                                                          # From .ps1 definition file
$tasks = Get-Content "C:\path\to\definition.json" | ConvertFrom-Json | % { $_ }                                                                                 # From .json definition file
$tasks = Get-ChildItem "C:\path\to\definition\directory\" -File | ? { $_.Extension -eq '.ps1' } | % { . $_.FullName }                                           # From directory containing .ps1 definition file(s)
$tasks = Get-ChildItem "C:\path\to\definition\directory\" -File | ? { $_.Extension -eq '.json' } | % { Get-Content $_.FullName | ConvertFrom-Json | % { $_ } }  # From directory containing .json definition file(s)
## Via parameter
Setup-ScheduledTask -DefinitionObject $tasks
## Via pipeline
$tasks | Setup-ScheduledTask

To list all available functions of the module:

Get-Command -Module ScheduledTaskManagement

Administration

Versions

To list versions of the module on PSGallery:

# Latest
Find-Module -Name ScheduledTaskManagement -Repository PSGallery -Verbose

# All versions
Find-Module -Name ScheduledTaskManagement -Repository PSGallery -AllVersions -Verbose

To update the module (Existing versions are left intact):

# Latest
Update-Module -Name ScheduledTaskManagement -Verbose

# Specific version
Update-Module -Name ScheduledTaskManagement -RequiredVersion x.x.x -Verbose

To uninstall the module:

# Latest
Uninstall-Module -Name ScheduledTaskManagement -Verbose

# All versions
Uninstall-Module -Name ScheduledTaskManagement -AllVersions -Verbose

# To uninstall all other versions other than x.x.x
Get-Module -Name ScheduledTaskManagement -ListAvailable | ? { $_.Version -ne 'x.x.x' } | % { Uninstall-Module -Name $_.Name -RequiredVersion $_.Version -Verbose }

# Tip: Simulate uninstalls with -WhatIf

Repositories

To get all registered PowerShell repositories:

Get-PSRepository -Verbose

To set the installation policy for the PSGallery repository:

# PSGallery (trusted)
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted -Verbose

# PSGallery (untrusted)
Set-PSRepository -Name PSGallery -InstallationPolicy Untrusted -Verbose

Development

To import / re-import the module:

# Installed version
Import-Module -Name ScheduledTaskManagement -Force -Verbose

# Project version
Import-Module .\src\ScheduledTaskManagement\ScheduledTaskManagement.psm1 -Force -Verbose

To remove imported functions of the module:

Remove-Module -Name ScheduledTaskManagement -Verbose

To list imported versions of the module:

Get-Module -Name ScheduledTaskManagement

To list all installed versions of the module available for import:

Get-Module -Name ScheduledTaskManagement -ListAvailable -Verbose