Create and customize configurations

You can use tasks, parameters, config functions, and variables to customize the installation process. Custom tasks and config functions can also be packaged as a module, and included in configurations.

You can base your customization on one of the configurations provided by Sitecore, or you can create your own configuration. This section describes the different components that you can use in a Sitecore Installation Framework configuration.

Tasks

Tasks are actions that are conducted in sequence when you run the Install-SitecoreConfiguration cmdlet. A task is implemented as a PowerShell cmdlet.

Each task is identified by a unique name and must contain a Type property. A task can have parameters or a collection of parameters passed to it. Tasks map directly to PowerShell functions and are registered with the Register-SitecoreInstallExtension -Type task.

The following example, is a task of the Copy type that you can use in a configuration to copy files from one location to another:

{ 
    "Tasks": { 
        "CopyFiles" : { 
            "Description": "Copies files to the specified location",
            "Type": "Copy", 
            "Params": {
                "Source": "c:\files",
                "Destination": "c:\newfiles"
            }
        }
    }
}

Skipping tasks

A task can include a Skip property that refers to a parameter, variable, or config function. If the return value is true, the task is not executed.

{
    "Parameters : {
        "Param1" : {
            "Type" : "String"
            "DefaultValue" : ""
        }
    },
    "Tasks" :{
        "Task1" :{
            "Type" : "Copy
            "Params" :{
                "Source" : "C:\\Source",
                "Destination : "C:\\Destination"
            }
            "Skip" : "[not(Parameter('Param1'))]"
        }
    }
}
Note

To ensure that your configuration is valid, each task must have a unique name. This means that the task can be directly executed, and the task can be identified in a log. It also lets you use the same type of task multiple times in a configuration.

In this configuration, if Param1 is set to any value, Task1 is skipped.

Requires (prerequisites)

A task can include a Requires block that allows prerequisite checks to be performed prior to executing the task. The prerequisite checks are performed after the Skip section. Prerequisites should take the form of Config Functions which return a Boolean. If the prerequisite check returns false , SIF will try to enter a nested shell within the current host. You will then have an opportunity to correct the problem, either from the prompt provided or externally.

After you have corrected the problem, enter exit to return to SIF. The prerequisite checks are then performed again. Alternatively, you can enter the SkipRequire command to skip this prerequisite. If the current host does not support a nested shell, the requirements are skipped.

{
    "Variables": {
        "Requires.Success" : [TestPath(Path:'C:\\Windows')]
    },
    "Tasks": {
        "Task1":{
            "Type": "WriteOutput",
            "Params" :{
                "InputObject":"Simple Task, depends on a variable."
            },
            "Requires": "[variable('Requires.Success')]"
        }
    },
    "Settings" : {
        "AutoRegisterExtensions" : True
    }
}

In this configuration, Task1 requires the output of the Requires.Success variable to check that the presence of C:\Windows is true.

Parameters

Parameters let users change values inside a configuration at runtime. Parameters must declare a type. They can also declare a default value and a description.

When you add a parameter to a configuration, it can be passed into a task using the parameter config function. The task then points to the value provided in the configuration or the value passed when Install-SitecoreConfiguration is called.

For example, to pass the Source and Destination parameters to the CopyFiles task:

{
    "Parameters": {
        "Source": { "Type": "string", "Description": "The source of files" },
        "Destination": { "Type": "string", "DefaultValue": "c:\newfiles" }
    },
    "Tasks": {
        "CopyFiles" : { 
            "Type": "Copy", 
            "Params": {
                "Source": "[parameter('Source')]",
                "Destination": "[parameter('Destination')]"
            }
        }
    }
}

The Source parameter does not contain the DefaultValue property, and therefore it is required when Install-SitecoreConfiguration is called.

However, the Destination parameter does have a default value. If the user does not provide the value, the DefaultValue from the configuration is used.

The values at runtime are then passed to the CopyFiles task you use the parameter config function.

To pass the values at the command line, you must use the name of the parameter with the standard PowerShell parameter syntax. For example:

Install-SitecoreConfiguration -Path .\configuration.json -Source c:\sourcefiles

Parameters validation

Parameter values can be validated before any tasks are started. Validation logic can be specified for each parameter using config functions:

{
    "Parameters": {
        "Source": {
            "Type": "string",
            "DefaultValue": "c:\\myfiles",
            "Validate": "[validatelength(4, 260, $_)]"
        },
    }
}

In this example, the Source parameter is validated by the validatelength config function, which ensures that the value is between 4 and 260 characters long.

The Validate property accepts any config function that returns bool.

The predefined functions that you can use for validation are:

  • ValidateCount - validates that the array length of the parameter is within the specified range.
  • ValidateLength - validates that the length of the parameter is within the specified range.
  • ValidateNotNull - verifies that the argument is not null.
  • ValidateNotNullOrEmpty - validates that the argument is not null and is not an empty string.
  • ValidatePattern - validates that the parameter matches the RegexPattern.
  • ValidateRange - validates that number parameter falls within the range specified by Min and Max.
  • ValidateSet - validates that the parameter is present in a specified set.

When you call Install-SitecoreConfiguration, all the parameters with validation logic are checked. If any validation fails, the installation command is aborted. To bypass validation, call Install-SitecoreConfiguration and use the –SkipValidation option.

Config functions

Config functions allow elements of the configuration to be dynamic, and allow you to calculate values, invoke functions, and pass these values to tasks so that a configuration can be flexible.

A config function is written as a string enclosed in square brackets [ ]. The function is identified by a name and can receive function parameters. For example:

[functionName(param1,param2,param3)]

Each function maps directly to a PowerShell function that is registered with the following cmdlet:

Register-SitecoreInstallExtension -Type ConfigFunction

Named parameters

To ensure that the correct values are passed to the expected parameter, you can reference the parameters of a config function directly.

Named parameters should be in a comma separated list. The parameter name must be followed by a colon:

{
    "Variables": {
        "Variable1": "GetFunction(Number:1234,String:'Text',Switch:True)]"
    }
}

In this example, Variable1 calls the GetFunction function and passes the Number parameter the value 1234, the string parameter the value 'Text', and the Switch parameter the value True. This is the equivalent of typing Get-Function -Number:1234 -String:"Text" -Switch:$True in the command line.

In the configuration Switch parameters, if declared, must be set to True or False.

Nested functions are also permitted and may refer to parameters, variables, or other config functions. For example:

[FunctionName1(functionName2(Switch1:'value1',Switch2:'value2'),Switch3:'value3')]

Variables

Variables are values that are calculated within the configuration itself. Unlike parameters, variables can use config functions to determine their value. Variables cannot be overridden at runtime. However, when they are calculated, they can use the values from parameters and other variables.

In the following example, the Destination variable uses the environment and concat config functions to determine the destination path:

{
    "Parameters": {
        "Source": { "Type": "string", "Description": "The source of files" }
    },
    "Variables": {
        "Destination": "[concat(environment('SystemDrive'),'\\newfiles')]"
    },
    "Tasks": {
        "CopyFiles" : { 
            "Type": "Copy", 
            "Params": {
                "Source": "[parameter('Source')]",
                "Destination": "[variable('Destination')]"
            }
        }
    }
}

Modules

SIF provides many tasks and config functions. You can load additional tasks and config functions by including them in a configuration.

If the module is available on PSModulePath, you can load modules by name. Alternatively, you must load modules using an explicit path. Modules are loaded at the beginning of an installation.

If the additional features are packaged in a module on your computer, you can import them into the install session by adding them in the Modules section of a configuration. For example:

  • To load a module by name –"MyCustomModule"
  • To load a module by explicit path – "C:\\extensions\\extensions.psm1"
{
    "Modules": [
        "MyCustomModule",
        "C:\\extensions\\extensions.psm1"
    ]
}

Uninstall tasks

Configurations can contain an optional UninstallTasks section. This section has the same form as the Tasks section. It should contain a list of tasks that undo all the actions completed in the Tasks section.

Uninstall tasks are invoked either by passing the –Uninstall switch to Install-SitecoreConfiguration or by calling the Uninstall-SitecoreConfiguration alias. If you call Uninstall-SitecoreConfiguration, you do not have to include the -Uninstall switch.

Uninstall tasks can be treated in the same way as normal tasks and support all the same functionality.

{
    "Parameters" :{
        "SolrService": {
            "Type": "string",
            "DefaultValue": "Solr-7.2.1",
            "Description": "The name of the Solr service."
        },
    },
    "UninstallTasks": {
        "RemoveSolrService": {
            "Type": "RemoveService",
            "Params": {
                "Name": "[parameter('SolrService')]"
            }
        },
    }
}

In this example, the RemoveSolrService uninstall task executes the RemoveService task and stops and removes the service specified in the SolrService parameter.

If you have referenced other configurations in the Includes section, the Uninstall Tasks for each of the included configurations are run, in reverse order, after the tasks in the first configuration.

Register

Each entry in the Register section allows you to expose PowerShell functions as SIF tasks or ConfigFunctions within the config file that you can use in the Variables or Tasks sections. They are registered automatically with the Register-SitecoreInstallExtension command.

The section takes the format:

{
    "Register": {
        "Tasks" : {
            "NewSMBShare" : "New-SMBShare",
            "Sleep": "Start-Sleep"
        },
        "ConfigFunction": {
            "GetRandom" : "Get-Random"
        }
    }
}

This configuration registers the New-SMBShare cmdlet as a task with the name NewSMBShare and registers Start-Sleep as a task with the name Sleep. The Get-Random cmdlet is registered as a config function with the name GetRandom.

Just like when you extend SIF, the Tasks section of Register is for functions that don't return anything and the ConfigFunctions section is for functions that return a value.

Automatic registration of extensions

Configuration files can optionally declare the AutoRegisterExtensions setting that allows you to dynamically register Tasks and ConfigFunctions. The default value is false.

Any PowerShell cmdlet can be referenced in a config file using a de-hyphenated version of its name.

{   
    "Tasks": {
        "RandomSleep": {
            "Type": "StartSleep",
            "Params": {
                "Seconds": "[GetRandom(10)]"
            }
                }
    },
    "Settings" : {
        "AutoRegisterExtensions" : true
    }
}

In this configuration, the RandomSleep task automatically registers and executes Start-Sleep as a task and Get-Random as a ConfigFunction. It is the equivalent of running Start-Sleep -Seconds (Get-Random 10) on the command line.

If two or more cmdlets match, the cmdlets are listed and an error is thrown.

Includes

To reuse elements and reduce repetition, configurations can refer to other configuration files.

For example, the following config is a pseudo config which configures a site. This is saved as CreateSite.json:

{
  "Parameters": {
    "Destination":{
      "Type": "string"
    },
    "SourcePackage":{
      "Type": "string"
    },
    "SiteName":{
        "Type": "string"
    }
  },
  "Tasks":{
    "CreateSite":{
      "Type": "CreateSite",
      "Params":{
        "SiteName": "[parameter('SiteName')]",
        "Path": "[parameter('Destination')]"
      }
    },
    "InstallPackage":{
      "Type": "CreateSite",
      "Params":{
        "Source": "[parameter('SourcePackage')]",
        "Path": "[parameter('Destination')]"
      }
    }
  }
}

Another config can be created which includes the previous example:

{
    "Includes":{
        "CreateSite":{
            "Source": ".\\CreateSite.json"
        }
    }
}

You can override elements of the included config by using the namespace it was imported as (in this case 'CreateSite'):

{
    "Parameters": {
        "CreateSite:Destination":{
            "Type": "string",
            "DefaultValue": "C:\\inetpub"
        }
    },
    "Includes":{
        "CreateSite":{
            "Source": ".\\CreateSite.json"
        }
    }
}

This example overrides the default value of the destination parameter imported by the CreateSite config. A similar syntax is used to override Variables and Tasks.

You can also include the same config multiple times, as the name is used to namespace each feature:

{
  "Parameters": {
    "CreateSite:Destination":{
      "Type": "string",
      "DefaultValue": "C:\\inetpub"
    },
    "CreateBackupSite:Destination":{
      "Type": "string",
      "DefaultValue": "C:\\inetpubbackup"
    }
  },
  "Includes":{
    "CreateSite":{
      "Source": ".\\CreateSite.json"
    },
    "CreateBackupSite":{
      "Source": ".\\CreateSite.json"
    }
  }
}

Settings

Settings let you configure the default requirements of the installation process. Some settings can be overridden at runtime for the user by passing them as parameters to the Install- SitecoreConfiguration cmdlet.

For example:

Install-SitecoreConfiguration -WarningAction Stop -InformationAction SilentlyContinue

The values in the settings are applied from lowest to highest in the following order:

  • Default value – contained in code.
  • Configuration – set in the configuration file.
  • Command line – passed at the command line.
NameDefault ValueAllowed ValuesCommand LineDescription
WarningActionContinueContinue

Ignore

Inquire

SilentlyContinue

Stop

Suspend
YesThe action to take when a warning occurs.
ErrorActionStopContinue

Ignore

Inquire

SilentlyContinue

Stop Suspend
YesThe action to take when an error occurs.
InformationActionContinueContinue

Ignore

Inquire

SilentlyContinue

Stop

Suspend
YesThe action to take when information is logged.
AutoRegisterExtensiosFalseTrue

False
NoEnables Dynamic registration of Tasks and Config Functions.

Settings within configuration files can be declared as:

{
    "Settings": {
        "AutoRegisterExtensions": true,
        "InformationAction": "SilentlyContinue"
    }
}

This configuration enables the AutoRegisterExtensions feature and sets the InformationAction preference to SilentlyContinue.

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