sc-powershell - SitecoreInstallFramework 2.0.0

Framework to install Sitecore instances

PM> Install-Package SitecoreInstallFramework -Version 2.0.0 -Source https://sitecore.myget.org/F/sc-powershell/api/v3/index.json

Copy to clipboard

> nuget.exe install SitecoreInstallFramework -Version 2.0.0 -Source https://sitecore.myget.org/F/sc-powershell/api/v3/index.json

Copy to clipboard

> dotnet add package SitecoreInstallFramework --version 2.0.0 --source https://sitecore.myget.org/F/sc-powershell/api/v3/index.json

Copy to clipboard
<PackageReference Include="SitecoreInstallFramework" Version="2.0.0" />
Copy to clipboard
source https://sitecore.myget.org/F/sc-powershell/api/v3/index.json

nuget SitecoreInstallFramework  ~> 2.0.0
Copy to clipboard

> choco install SitecoreInstallFramework --version 2.0.0 --source https://sitecore.myget.org/F/sc-powershell/api/v2

Copy to clipboard
Import-Module PowerShellGet
Register-PSRepository -Name "sc-powershell" -SourceLocation "https://sitecore.myget.org/F/sc-powershell/api/v2"
Install-Module -Name "SitecoreInstallFramework" -RequiredVersion "2.0.0" -Repository "sc-powershell" 
Copy to clipboard

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.

Owners

Kieran Marron Jonas Bang Christensen

Authors

Sitecore Corporation A/S

Project URL

http://doc.sitecore.net/

License

Sitecore MyGet license

Tags

sitecore powershell install config PSModule PSIncludes_Function PSFunction_Export-WebDeployParameters PSFunction_Get-SitecoreInstallExtension PSFunction_Install-SitecoreConfiguration PSFunction_Register-SitecoreInstallExtension PSFunction_Invoke-AndConfigFunction PSFunction_Invoke-CheckInstalledSoftwareConfigFunction PSFunction_Invoke-ConcatConfigFunction PSFunction_Invoke-EnvironmentConfigFunction PSFunction_Invoke-EqualConfigFunction PSFunction_Invoke-GetCertificateConfigFunction PSFunction_Invoke-GetCertificateThumbprintConfigFunction PSFunction_Invoke-IfConfigFunction PSFunction_Invoke-JoinConfigFunction PSFunction_Invoke-JoinPathConfigFunction PSFunction_Invoke-ModuleConfigFunction PSFunction_Invoke-NewPSCredentialConfigFunction PSFunction_Invoke-NotConfigFunction PSFunction_Invoke-OrConfigFunction PSFunction_Invoke-RandomStringConfigFunction PSFunction_Invoke-ReadJsonConfigFunction PSFunction_Invoke-ResolveCertificatePathConfigFunction PSFunction_Invoke-ResolvePathConfigFunction PSFunction_Invoke-RestAuthenticationConfigFunction PSFunction_Invoke-SqlConnectionStringConfigFunction PSFunction_Invoke-ValidateCountConfigFunction PSFunction_Invoke-ValidateLengthConfigFunction PSFunction_Invoke-ValidateNotNullConfigFunction PSFunction_Invoke-ValidateNotNullOrEmptyConfigFunction PSFunction_Invoke-ValidatePatternConfigFunction PSFunction_Invoke-ValidateRangeConfigFunction PSFunction_Invoke-ValidateSetConfigFunction PSFunction_Invoke-WindowsFeatureConfigFunction PSFunction_Write-TaskHeader PSFunction_Write-TaskInfo PSFunction_Invoke-AddWebFeatureSSLTask PSFunction_Invoke-AppPoolTask PSFunction_Invoke-CommandTask PSFunction_Invoke-CopyTask PSFunction_Invoke-CreateServiceTask PSFunction_Invoke-DownloadFileTask PSFunction_Invoke-EnsurePathTask PSFunction_Invoke-FilePermissionsTask PSFunction_Invoke-HostHeaderTask PSFunction_Invoke-HttpRequestTask PSFunction_Invoke-IISConfigurationTask PSFunction_Invoke-InsertXmlTask PSFunction_Invoke-InstallPSModuleTask PSFunction_Invoke-InstallSitecoreConfigurationTask PSFunction_Invoke-IoXmlTask PSFunction_Invoke-ManageAppPoolTask PSFunction_Invoke-ManageServiceTask PSFunction_Invoke-ManageSolrConfigTask PSFunction_Invoke-ManageSolrCoreTask PSFunction_Invoke-ManageSolrSchemaTask PSFunction_Invoke-ManageWebsiteTask PSFunction_Invoke-NewRootCertificateTask PSFunction_Invoke-NewSignedCertificateTask PSFunction_Invoke-RemoveAppPoolTask PSFunction_Invoke-RemoveServiceTask PSFunction_Invoke-RemoveSqlDatabaseTask PSFunction_Invoke-RemoveWebsiteTask PSFunction_Invoke-RemoveXmlTask PSFunction_Invoke-SetXmlTask PSFunction_Invoke-SitecoreUrlTask PSFunction_Invoke-TransformXmlDocTask PSFunction_Invoke-UnpackTask PSFunction_Invoke-WebBindingTask PSFunction_Invoke-WebDeployTask PSFunction_Invoke-WebRequestTask PSFunction_Invoke-WebsiteClientCertTask PSFunction_Invoke-WebsiteTask PSCommand_Export-WebDeployParameters PSCommand_Get-SitecoreInstallExtension PSCommand_Install-SitecoreConfiguration PSCommand_Register-SitecoreInstallExtension PSCommand_Invoke-AndConfigFunction PSCommand_Invoke-CheckInstalledSoftwareConfigFunction PSCommand_Invoke-ConcatConfigFunction PSCommand_Invoke-EnvironmentConfigFunction PSCommand_Invoke-EqualConfigFunction PSCommand_Invoke-GetCertificateConfigFunction PSCommand_Invoke-GetCertificateThumbprintConfigFunction PSCommand_Invoke-IfConfigFunction PSCommand_Invoke-JoinConfigFunction PSCommand_Invoke-JoinPathConfigFunction PSCommand_Invoke-ModuleConfigFunction PSCommand_Invoke-NewPSCredentialConfigFunction PSCommand_Invoke-NotConfigFunction PSCommand_Invoke-OrConfigFunction PSCommand_Invoke-RandomStringConfigFunction PSCommand_Invoke-ReadJsonConfigFunction PSCommand_Invoke-ResolveCertificatePathConfigFunction PSCommand_Invoke-ResolvePathConfigFunction PSCommand_Invoke-RestAuthenticationConfigFunction PSCommand_Invoke-SqlConnectionStringConfigFunction PSCommand_Invoke-ValidateCountConfigFunction PSCommand_Invoke-ValidateLengthConfigFunction PSCommand_Invoke-ValidateNotNullConfigFunction PSCommand_Invoke-ValidateNotNullOrEmptyConfigFunction PSCommand_Invoke-ValidatePatternConfigFunction PSCommand_Invoke-ValidateRangeConfigFunction PSCommand_Invoke-ValidateSetConfigFunction PSCommand_Invoke-WindowsFeatureConfigFunction PSCommand_Write-TaskHeader PSCommand_Write-TaskInfo PSCommand_Invoke-AddWebFeatureSSLTask PSCommand_Invoke-AppPoolTask PSCommand_Invoke-CommandTask PSCommand_Invoke-CopyTask PSCommand_Invoke-CreateServiceTask PSCommand_Invoke-DownloadFileTask PSCommand_Invoke-EnsurePathTask PSCommand_Invoke-FilePermissionsTask PSCommand_Invoke-HostHeaderTask PSCommand_Invoke-HttpRequestTask PSCommand_Invoke-IISConfigurationTask PSCommand_Invoke-InsertXmlTask PSCommand_Invoke-InstallPSModuleTask PSCommand_Invoke-InstallSitecoreConfigurationTask PSCommand_Invoke-IoXmlTask PSCommand_Invoke-ManageAppPoolTask PSCommand_Invoke-ManageServiceTask PSCommand_Invoke-ManageSolrConfigTask PSCommand_Invoke-ManageSolrCoreTask PSCommand_Invoke-ManageSolrSchemaTask PSCommand_Invoke-ManageWebsiteTask PSCommand_Invoke-NewRootCertificateTask PSCommand_Invoke-NewSignedCertificateTask PSCommand_Invoke-RemoveAppPoolTask PSCommand_Invoke-RemoveServiceTask PSCommand_Invoke-RemoveSqlDatabaseTask PSCommand_Invoke-RemoveWebsiteTask PSCommand_Invoke-RemoveXmlTask PSCommand_Invoke-SetXmlTask PSCommand_Invoke-SitecoreUrlTask PSCommand_Invoke-TransformXmlDocTask PSCommand_Invoke-UnpackTask PSCommand_Invoke-WebBindingTask PSCommand_Invoke-WebDeployTask PSCommand_Invoke-WebRequestTask PSCommand_Invoke-WebsiteClientCertTask PSCommand_Invoke-WebsiteTask PSCommand_scinst PSCommand_Invoke-SitecoreInstall PSCommand_Uninstall-SitecoreConfiguration

Info

1266775 total downloads
16378 downloads for version 2.0.0
Download (690.78 KB)
Found on the current feed only

Package history

Version Size Last updated Downloads Mirrored?
2.1.0 709.13 KB Fri, 05 Apr 2019 09:27:06 GMT 7939
2.0.0 690.78 KB Wed, 28 Nov 2018 11:41:05 GMT 16378
1.2.1 606.95 KB Fri, 06 Apr 2018 09:15:01 GMT 33981
1.2.0 601.73 KB Fri, 23 Feb 2018 10:04:44 GMT 3391
1.1.0 545.89 KB Thu, 21 Dec 2017 11:06:17 GMT 4541
1.0.2 531.12 KB Thu, 12 Oct 2017 10:06:04 GMT 1200545