Writing a Custom Component

When the first-party components do not cover a task, you can build your own. A component pairs a script (what runs on the machine) with a parameter form (what the person adding it to a workflow fills in).

Open the editor from Task Library, then Create Component. The left pane is the script editor; the right pane has Details, Parameters, Target Requirements, and (when editing) History.

The two-pane component editor with the script on the left and configuration tabs on the right

Write the script

Components run PowerShell on the target machine. Write the body in the left pane. A few rules keep a component reliable:

  1. 1

    Fail loudly

    Start with $ErrorActionPreference = 'Stop' so an unexpected error stops the step instead of continuing silently.

  2. 2

    Signal success with the exit code

    End with exit 0 on success. Use Write-Error and exit 1 on failure. The desktop agent reports the step as failed on a non-zero exit code.

  3. 3

    Be safe to re-run

    Check the current state first and do nothing if it is already correct. Deployments retry, so a component that is safe to run twice is far more reliable.

  4. 4

    Verify the change

    Before exiting, confirm the change actually took effect (the service is running, the value is set, the package is present).

Add parameters

To let people configure the component, reference a value in the script as {{name}} and define a matching field in the Parameters tab (see Building Parameter Forms). For example:

$ErrorActionPreference = 'Stop'
Set-TimeZone -Id '{{tz_id}}'
if ((Get-TimeZone).Id -ne '{{tz_id}}') { Write-Error 'Failed to set time zone.'; exit 1 }
Write-Output 'Time zone set.'
exit 0

Here {{tz_id}} is filled in per step when someone adds the component to a workflow. The value is substituted into the script before it reaches the machine.

Every {{name}} in the script must have a matching field, and every field must be used in the script. The editor blocks saving until they match, and shows which names are unused or undefined.

Use a file as a parameter

For a component that needs a file (an installer, a config), add a file field. Reference it as {{name}} like any other parameter. At run time the agent downloads the file and replaces the reference with its local path. See Files and Storage Quota.

Target requirements and versions

Use the Target Requirements tab to declare what a component needs (for example, Windows 10 or newer). Each save creates a new version; workflows pin the version they were built with, so improving a component never disturbs existing workflows. Publish a workflow to roll a new component version out to devices.

The History tab lists a component's saved versions, newest first. View any version's details, or restore it. Restoring is safe to try: your current content is saved as a new version first, so you can restore that one to undo. Version history is included on the Professional, Enterprise and Partner plans; on Starter, the tab explains how to get it. History keeps a component's 50 most recent versions. When a save adds one more, the oldest version is removed.