Create tasks

Tasks are PowerShell functions that you can invoke from a SIF configuration. When you invoke a configuration, each task performs an action. Because a task is implemented as a PowerShell function, it benefits from all the features that PowerShell offers.

The CmdletBinding Attribute

When you create a task, you must use the CmdletBinding attribute. This provides support for common PowerShell parameters, such as those that control error handling.

It is best practice to use the SupportsShouldProcess parameter so that users can test the actions that the task takes, without applying them. The following example uses the CmdletBinding attribute in the Invoke-UnpackTask cmdlet:

Function Invoke-UnpackTask {
    [CmdletBinding(SupportsShouldProcess=$true)]
    param(
        # Parameters
    )
    # function code
}

For more information about the CmdletBinding attribute, see About Functions CmdletBindingAttribute in the Microsoft PowerShell documentation.

Task parameters

Task parameters are declared as normal PowerShell parameters. You can use validation and types to restrict the values that can be passed to the cmdlet. This includes marking parameters as mandatory, and support for multiple parameter sets.

When a task is called from a configuration, the Params property is mapped to the parameters that are declared in the PowerShell function. For example, the Invoke-CopyTask cmdlet declares the following parameters:

Function Invoke-CopyTask {
    [CmdletBinding(SupportsShouldProcess=$true)]
    param(        
      [Parameter(Mandatory=$true)]
      [ValidateScript({ Test-Path $_ })]
      [string]$Source,
      [Parameter(Mandatory=$true)]
      [ValidateScript({ Test-Path $_ -IsValid })]
      [string]$Destination
    )
# function code
}
  • The Source parameter is mandatory and checks that the given value is a string that points to a path that exists. 
  • The Destination parameter is mandatory and checks that the given value is a string that is a valid file path.

Here is an example of how to declare the Copy task in a configuration where only the mandatory parameters are used:

{
    "Tasks": {
        "CopySomeFiles": {
        "Type": "Copy",
        "Params": {
          "Source":"c:\somefile\example.txt",
          "Destination":"c:\copied\"
        }
      }
    }
}

Return values from task

Tasks do not need return values. When you invoke tasks through a configuration, the values returned from a task are not captured or processed directly. However, any value that you return from a task is shown in the installation logs.

Write to the logs

Previous versions of SIF used the Write-TaskInfo function to log information. This function has been deprecated and will be removed in a future version. Use the Write-Information function instead.

Write-Information -MessageData task "[Info] Updated"

Silent output

You cab specify silent output by re-directing all the streams to $null.

Install-SitecoreConfiguration -Path MyConfig.json *> $null

Creating a log file

In SIF version 1.x, every time you used the built-in PowerShell transcript features to invoke Install-SitecoreConfiguration, a log file was automatically created.

This feature has been removed due to issues with different hosts and with the information that was logged to a log file. To create a log file for an installation, use the following syntax:

c:\> Install-SitecoreConfiguration <parameters> *>&1 | Tee-Object <logfile>

*>&1 merges every stream - information, warning, and so on into the output stream.

| Tee-Object <logfile> outputs the stream to the console and to a log file.

Include tasks in a configuration

Once a task has been written, it must be registered with SIF. To include tasks in a configuration, you must package them as a PowerShell module and add them to the Modules section of a configuration, by directly registering them within a configuration, or enabling the autoregisterextensions function.

When you use the Register-SitecoreInstallExtension cmdlet, you can use the task in configurations. For example, to register the Copy-CustomItems cmdlet as the CustomCopy task, use the following cmdlet:

Register-SitecoreInstallExtension -Command Copy-CustomItems -As CustomCopy -Type Task
Note

You can replace an existing registered task by using the -Force parameter. The following custom cmdlet replaces the default copy task: Register-SitecoreInstallExtension -Command Copy-CustomItems -As Copy -Type Task –Force.

If you have suggestions for improving this article, let us know!