New Features

Invoke-DownloadFileTask updated to support authentication

Invoke-DownloadFileTask was extended with 2 optional parameters: -Credentials and -LoginSession to be able to download files from the sources that require authentication. In order to create session for -LoginSession parameter it is recommended to use Invoke-RestAuthenticationConfigFunction.

 "ShowMessage" : {
            "Type" : "DownloadFile",
            "Params" : {
                "SourceUri" : "https://dev.sitecore.net/~/media/F374366CA5C649C99B09D35D5EF1BFCE.ashx",
                "DestinationPath":"c:\\www\\902.zip",
                "LoginSession": "[RestAuthentication('https://dev.sitecore.net/api/authorization', 'user@sitecore.net', 'Password')]"
            }
        }

Includes (Partials)

Configurations may now refer to other configuration files to allow reuse of elements and reduce repetition in different configurations.

For example, the following config is a pseudo config which will configure 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 will include the above:

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

We 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"
    }
  }
}

The above overrides the default value for the destination parameter imported by the CreateSite config. Similar syntax is used to override Variables and Tasks

We can also include the same config multiple times, as the name will be 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"
    }
  }
}

Tasks are executed in the order that they are declared. Settings are preserved in the order declared, and do not overwrite once set.

Uninstall Tasks

Configurations may optionally contain an UninstallTasks section. This section takes the same form as the Tasks section. It should contain a list of tasks that will back out 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 alias Uninstall-SitecoreConfiguration. It is not necessary to include the -Uninstall switch if calling Uninstall-SitecoreConfiguration.

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

{
    "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 uninstall task RemoveSolrService will execute the RemoveService task and stop and remove the service specified in the SolrService parameter.

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

Requirements (Prerequisites)

A task may now include a Requires block that allows prerequisite checks to be performed prior to execution of 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 then the Sitecore Install Framework will attempt 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. Once you have corrected the problem enter exit to return to the Sitecore Install Framework. The prerequisite checks will be performed again. Alternatively the prerequisite can be skipped by entering the command SkipRequire. If the current host doesn't support a nested shell then the requirements will be 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 the task Task1 will require the output of the variable Requires.Success a config function to check the presence of C:\Windows to be true.

Named Parameters

Configurations now permit ConfigFunctions to be called using named parameters as they would be on the command line. Named parameters are a comma separated list denoted by following the parameter name with a colon:.

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

In this example Variable1 will call the function GetFunction and pass it the named parameter Number with the value 1234, the named parameter string with the value 'Text' and the switch parameter Switch with the value true. It is the equivalent of typing Get-Function -Number:1234 -String:"Text" -Switch:$True on the command line.

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

Registration in JSON

You can now register Tasks and ConfigFunctions in configuration files using the new Register section. The key for each entry is the name used in a configuration, the value for each entry is the PowerShell function to be invoked.

The section takes the format:

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

Auto Registration

Configuration files may now have an extra setting AutoRegisterExtensions that allows dynamic registration of Tasks and ConfigFunctions.

Any PowerShell cmdlet may 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 task RandomSleep will automatically register and execute Start-Sleep as a task and automatically register and execute Get-Random as a ConfigFunction. It is the equivalent of running Start-Sleep -Seconds (Get-Random 10) on the command line.

Parameters validation

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

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

In this example the Source parameter will be validated against the config function validatelength checking that the string in between 3 and 260 characters long. If user sets invalid value for Source parameter (e.g. C:), Install-SitecoreConfiguration command will be aborted.

Tasks

• Invoke-NewRootCertificateTask - Creates a self signed Root Certificate Authority
• Invoke-NewSignedCertificateTask - Creates a self signed Web Certificate signed by a Root Certificate Authority
• Invoke-RemoveXmlTask - Allows the removal of xml nodes
• Invoke-InsertXmlTask - Allows the insertion of sub xmldocuments to an existing document
• Invoke-AddWebFeatureSSLTask - Created a Root Certificate Authority and Web Certificate and bind it to a website
• Install-SitecoreConfiguration - Now skips tasks that do not implement WhatIf when -WhatIf is specified
• Install-SitecoreConfiguration - Now allows Tasks and ConfigFunctions to be registered directly from the config file.
• Uninstall-SitecoreConfiguration - Executes tasks in the specified configurations UninstallTask section
• Invoke-ManageSolrCoreTask - Now allows all possible Solr actions.
• Invoke-HostHeaderTask - Now supports remove host header action.
• Invoke-RemoveSqlDatabaseTask - Removes given databases from the SQL Server.
• Install-SitecoreConfiguration - New option SkipValidation allows to bypass parameters validation.
• Invoke-InstallSitecoreConfigurationTask - Installs Sitecore configuration to the remote server.
• Invoke-InstallPSModuleTask - Installs Powershell module to the remote server.

Config Functions

• Invoke-NewPSCredentialConfigFunction - Creates a Powershell Credential Object for use with tasks and config functions.
• Invoke-RandomStringConfigFunction - Generates a random string of ASCII characters.
• Invoke-WindowsFeatureConfigFunction - Determines installation status of a Windows Feature.
• Invoke-ModuleConfigFunction - Determines installation status and version of a PowerShell Module.
• Invoke-ValidateCountConfigFunction - Validates that the parameter array length is in the specified range.
• Invoke-ValidateLengthConfigFunction - Validates that the parameter length falls in the range.
• Invoke-ValidateNotNullConfigFunction - Verifies the argument is not null.
• Invoke-ValidateNotNullOrEmptyConfigFunction - Validates that the argument is not null and is not an empty string.
• Invoke-ValidatePatternConfigFunction - Validates that parameter matches the RegexPattern.
• Invoke-ValidateRangeConfigFunction - Validates that number parameter falls in the range specified by Min and Max.
• Invoke-ValidateSetConfigFunction - Validates that parameter is present in a specified set.

Bug Fixes

Tasks

• Invoke-SitecoreURLTask - Now supports Sitecore 9.1 Authentication cookies and also able to bypass an autoredirect from the legacy login page.

Breaking Changes

Logging

In version 1.x a log file was automatically created for every invocation of Install-SitecoreConfiguration using PowerShells built in transcript features. This feature has been removed due to issues with different hosts and the information that would be logged to a log file.

To create a log file for an install we suggest the following syntax:

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

*>&1 merges all streams (information, warning, etc) into the output stream.

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

Other

• If the SQLServer module is present Invoke-Sqlcmd is registered as both a task and a Config Function.
• SitecoreInstallFramework no longer requires Sitecore Fundamentals.