Getting started with deployment API in DXC

We just have released Deployment API in DXC-S as an Open Beta program. This feature allows partners and customers to automate deployment to DXC environments via API. 

There are two ways to deploy code changes via API: 

1. Using a source environment - this is a traditional way to push changes in DXC. The application code is deployed to the Integration environment using any preferred tool supported by Azure Web Apps, and then get promoted to the Preproduction environment, and after that to the Production environment. The deployment flow is sequential.
2. Using code packages - this is a new method. It requires to package your application code as a NuGet package first, and then it can be deployed to any environment. The deployment flow is much more flexible, but with great powers comes great responsibility, so we highly recommend to deploy your package to any non-production environment first before deploying it to Production.

It is possible to mix both ways, but it worth mentioning that we see the code packages as a primary way of doing deployments in the future.

How do I get started?

First, you will need to get Deployment API credentials. You can generate it using the DXC-S Management portal. The API credentials are specific per target environment. So if you are planning to deploy from Integration to Preproduction environment, you need to provide API credentials for Preproduction.

Next, install EpiCloud PowerShell module.

Now we are ready to start our first deployment via API. Let's deploy a CMS site from Integration to Preproduction. Open a PowerShell prompt and use the commands listed below.

The Import-Module command makes EpiCloud cmdlets available in the current PowerShell prompt:

Import-Module EPiCloud

The Connect-EpiCloud command stores API credentials in the console session, so we don't need to specify it again with every command:

Connect-EpiCloud -ClientKey <...> -ClientSecret <...>

And the Start-EpiDeployment will kick-off a deployment process:

Start-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -SourceApp cms -SourceEnvironment Integration -TargetEnvironment Preproduction

The command will respond with the current deployment status and deployment id:

id                 : 5eec46c4-df99-47e6-a6b9-aaf5010874f8
projectId          : ae874a90-08de-4a03-a865-aaf500f4830e
status             : InProgress
startTime          : 2019-10-29T16:00:51.123Z
endTime            :
percentComplete    : 0
validationLinks    : {}
deploymentWarnings : {}
deploymentErrors   : {}
parameters         : @{targetEnvironment=Preproduction; sourceEnvironment=Integration; sourceApps=System.Object[]; maintenancePage=False; includeBlob=False; includeDb=False}

The deployment id is needed to get the deployment status and to complete or reset the deployment. In order to get the deployment status use Get-EpiDeployment command:

Get-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -Id 5eec46c4-df99-47e6-a6b9-aaf5010874f8

Once the first stage of the deployment is finished, we can validate the site on the deployment slot. The URL to the slot can be found in the validationLinks property in the Get-Deployment command response:

id                 : 5eec46c4-df99-47e6-a6b9-aaf5010874f8
projectId          : ae874a90-08de-4a03-a865-aaf500f4830e
status             : AwaitingVerification
startTime          : 2019-10-29T16:10:14.198Z
endTime            :
percentComplete    : 100
validationLinks    : {http://sevodeploy275uzuprep-slot.dxcloud.episerver.net/}
deploymentWarnings : {}
deploymentErrors   : {}
parameters         : @{targetEnvironment=Preproduction; sourceEnvironment=Integration; sourceApps=System.Object[]; maintenancePage=False; includeBlob=False; includeDb=False}

Now we can either complete or reset the deployment. There are two corresponding commands for that:

Complete-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -Id 5eec46c4-df99-47e6-a6b9-aaf5010874f8 

or

Reset-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -Id 5eec46c4-df99-47e6-a6b9-aaf5010874f8

After running the Complete-EpiDeployment command we get the deployment status displayed:

id                 : 5eec46c4-df99-47e6-a6b9-aaf5010874f8
projectId          : ae874a90-08de-4a03-a865-aaf500f4830e
status             : Completing
startTime          : 2019-10-29T16:20:51.123Z
endTime            :
percentComplete    : 0
validationLinks    : {}
deploymentWarnings : {}
deploymentErrors   : {}
parameters         : @{targetEnvironment=Preproduction; sourceEnvironment=Integration; sourceApps=System.Object[]; maintenancePage=False; includeBlob=False; includeDb=False}

The Complete-EpiDeployment command swaps the slot and deployment is now completed!

If you want to learn more, you can find a detailed description of all commands provided with the EpiCloud module in the documentation.

Using Azure DevOps? This blog post describes how to configure a continuous delivery pipeline with DXC-S.