Loading...
Area: Episerver Customer-Centric DXP
Applies to versions: Not applicable

Deploy using PowerShell

This topic describes how to deploy using the Deployment API for Episerver Customer-Centric Digital Experience Platform (DXP), and the Powershell module provided with the API.

EpiCloud Powershell module

To simplify usage of the Deployment API, a PowerShell module EpiCloud, is available which contains the following cmdlets:

  • Connect-EpiCloud. Simplifies overall cmdlet usage by supplying the required credentials to other commands in the module.
  • Get-EpiDeploymentPackageLocation. Returns a SAS link to upload deployment packages to using Add-EpiDeploymentPackage.
  • Add-EpiDeploymentPackage. Upload a deployment package to the DXC-S environment to use for deployments; requires the Azure PowerShell modules (Azure.Storage or Az.Storage) to run.
  • Start-EpiDeployment. Starts a new deployment.
  • Get-EpiDeployment. Fetches information about deployments (ongoing or finished).
  • Complete-EpiDeployment. Completes a deployment which is in the verification stage. (Same as Complete/Go Live in the management portal)
  • Reset-EpiDeployment. Resets a deployment which is in the verification stage. (Same as Reset in the management portal.) Note that this will not restore the database (also same as in the management portal).

All cmdlets have built-in help that you can access in the PowerShell console using the Get-Help cmdlet. This help includes examples on how to use the commands and descriptions on all parameters. For example:

Get-Help Start-EpiDeployment -Full

Or if you want a graphical interface to access the help:

Get-Help Start-EpiDeployment -ShowWindow

Installation

The module is available at the PowerShell Gallery. To install it, open PowerShell and run the following command:

Install-Module -Name EpiCloud -Scope CurrentUser

This installs the module for the current user (and does not require Administrator privileges). For instructions about using the PowerShell Gallery and the related PowerShell cmdlets for managing modules and scripts, see Microsoft's documentation.

Sample usage

If you install the module from the PowerShell Gallery, the module will be loaded automatically when you call a cmdlet. To explicitly import the module you can use the following command:

Import-Module EpiCloud

Optionally, you can add your credentials to the current PowerShell scope by calling the Connect-EpiCloud cmdlet with your ClientKeyClientSecret and ProjectId after which you do not have to specify the ClientKey, ClientSecret or ProjectId for any other of the cmdlets in the module during the session. It is also possible to specify these for each cmdlet if running on a build server for example.

Connect-EpiCloud -ClientKey <ClientKey> -ClientSecret <ClientSecret> -ProjectId <ProjectId>

To upload a code package to your DXP project, run Get-EpiDeploymentPackageLocation to get the SAS link where the package should be uploaded, and then Add-EpiDeploymentPackage to upload that package, as follows. Refer to Code package format for details on what the package should look like.

$saslink = Get-EpiDeploymentPackageLocation
Add-EpiDeploymentPackage -SasUrl $saslink -Path C:\MyDeploymentPackages\cms.app.1.0.0.nupkg

The code package is now available for deployment.

To start the code deployment, you can use either code packages or source environment approaches. 

Using code packages

To deploy this package to the Preproduction environment, use the following command:

Start-EpiDeployment -DeploymentPackage cms.app.1.0.0.nupkg -TargetEnvironment Preproduction

Using source environment

To deploy code from a source environment, use the following command:

Start-EpiDeployment -SourceEnvironment Integration -TargetEnvironment Preproduction -SourceApp cms,commerce
  • -SourceApp accepts app type names, CMS and Commerce to specify which app from a source environment to copy

To deploy content, use the following command:

Start-EpiDeployment -SourceEnvironment Integration -TargetEnvironment Preproduction -IncludeBlob -IncludeDb
  • -IncludeBlob copy BLOBs from source to target environment
  • -IncludeDb copy the DB from source to target environment

The deployment starts immediately and the cmdlet returns an object that contains the Id of the deployment. If you specify the -Wait switch the cmdlet will wait for the deployment to finish before it returns. -UseMaintenancePage switch can be used to enable a maintenance page during the deployment if there are DB changes.

For additional logging information, -Verbose can be specified. This switch can be added to any cmdlet.

If you want to check the status of deployment or just list deployments made through the API for the project, use the following command:

Get-EpiDeployment

To get the details of a specific deployment, specify the Id of that deployment; (it returns the same type of object as Start-EpiDeployment):

PS> Get-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060
 
id                 : 2a52c873-b39c-4f44-b842-aab5009c3060
projectId          : 2a561398-d517-4634-9bc4-aab5008a8e1a
status             : InProgress
startTime          : 2019-08-26T09:28:39.479Z
endTime            :
percentComplete    : 2
validationLinks    : {}
deploymentErrors   : {}
deploymentWarnings : {}
parameters         : @{targetEnvironment=Preproduction; packages=System.Object[]; maintenancePage=False}

To see details, expand the parameters property. You can also get the output as JSON:

Get-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060 | ConvertTo-Json

After the deployment finishes, run Reset or Complete using the respective functions such as in the following examples:

Complete

Complete-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060

Reset

Reset-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060

Reset-EpiDeployment and Complete-EpiDeployment also have a -Wait switch if you want the cmdlets to return after the action has finished.

Most of the cmdlets in the module also support pipelining, such as the following example:

Get-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060 | Complete-EpiDeployment

Related topics

Do you find this information helpful? Please log in to provide feedback.

Last updated: Feb 19, 2020