---
title: "Create and customize configurations"
slug: "create-and-customize-configurations"
abstract: ""
---
# 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:

```csharp
{ 
    "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.

```csharp
{
    "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.

```csharp
{
    "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:

```csharp
{
    "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:

```text
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:

```csharp
{
    "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:

```text
[functionName(param1,param2,param3)]

```

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

```text
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:

```csharp
{
    "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:

```text
[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:

```csharp
{
    "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](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_psmodulepath?view=powershell-7.4), 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`"

```csharp
{
    "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.

```csharp
{
    "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:

```csharp
{
    "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.

```csharp
{   
    "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`:

```csharp
{
  "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:

```csharp
{
    "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'`):

```csharp
{
    "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:

```csharp
{
  "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:

```text
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.

| Name | Default Value | Allowed Values | Command Line | Description |
| --- | --- | --- | --- | --- |
| WarningAction | Continue | Continue<br><br>Ignore<br><br>Inquire<br><br>SilentlyContinue<br><br>Stop<br><br>Suspend | Yes | The action to take when a warning occurs. |
| ErrorAction | Stop | Continue<br><br>Ignore<br><br>Inquire<br><br>SilentlyContinue<br><br>Stop Suspend | Yes | The action to take when an error occurs. |
| InformationAction | Continue | Continue<br><br>Ignore<br><br>Inquire<br><br>SilentlyContinue<br><br>Stop<br><br>Suspend | Yes | The action to take when information is logged. |
| AutoRegisterExtensios | False | True<br><br>False | No | Enables Dynamic registration of Tasks and Config Functions. |

Settings within configuration files can be declared as:

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

```

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