The Web Deploy Packages for a module

Last updated Friday, November 17, 2017 in Sitecore Azure Toolkit for Administrator, Developer
Keywords: Azure, Cloud

The following sections describe references and commands you can use to create Web Deploy packages (WDPs) that you can deploy either on-premise or on Azure, using ARM templates:

Before you start, you must install Sitecore Azure Toolkit and load the commandlets into a PowerShell session.

Generating an initial WDP

You can use a Sitecore module ZIP package or a Team Development for Sitecore .update package and convert it into an equivalent .scwdp.zip package that is compatible with MSDeploy using the following PowerShell call:

ConvertTo-SCModuleWebDeployPackage [-Path] <string> [[-Destination] <string>]

Parameters

Description

Path

The path to the original module ZIP package (or an .update package created by Team Development for Sitecore).

Destination

The path to the file or folder that you want to save the generated package into.

This creates a .scwdp.zip package with the following content:

Content

Description

Content/Website/*

The files that you want to install on the website.

Content/Website/App_Data/Poststeps/*.poststep

Post step of the original package, if it was defined.

core.sql

The SQL script that installs items into the core database. This file is only present when the package installs items in the core database.

master.sql

The SQL script that installs items into the master database. This file is only present when the package installs items in the master database.

The .scwdp.zip package accepts the following parameters:

Parameter

Description

Application Path

The path to the website where you will install the application (use an IIS application name or a physical folder path).

Core Admin Connection String

The connection string that connects to the core database during installation. This parameter is only added when the original package installs items onto the core database.

Master Admin Connection String

The connection string that connects to the master database during installation. This parameter is only added when the original package installs items onto the master database.

Advanced scenarios

Refer to the following sections (Applying transformations, Embedding dynamic transformations, Embedding files into the package, Adjusting parameters, Invoking multiple commands in a row, Testing your package) if you want to perform more advanced scenarios, such as:

  • Changing the default module configuration when you install it on Azure, for example, if you want to enable App Insights or Azure Search integration.
  • Generating multiple WDPs for different roles or configurations from a single Sitecore ZIP as a part of your build pipeline.
  • Installing a new database together with the module.
  • Updating a database (including adding new tables or users and roles), when installing a module.
  • Adding parameters to make a package installation more configurable.

Applying transformations

You can apply transformations to configure your module in the following scenarios:

  • If you want a non-standard installation of a module on Azure. For example, to enable Azure Search integration or to tweak performance parameters.
  • You can also use transformations to create role-specific packages from a single source package.

Note

You can only apply transformations to the content of a module package, that is, the transformations can only affect the files that the module delivers.

Use the following as a reference:

Update-SCWebDeployPackage [-CargoPayloadPath] <string[]> [-Path <string>] [-WhatIf]:

Parameters

Description

CargoPayloadPath

An array of paths to the SCCPL files that apply to the WDP.

Path

The path to the WDP that you want to modify.

WhatIf

A switch that enables a dry run of the transformation and produces the actions that would be performed, without modifying the package.

Embedding dynamic transformations

Dynamic transformations allow a module to transform the target Sitecore installation at the time the module is installed. For example, you can add an HTTP handler to the Web.config file.

Note

Dynamic transformations are applied to the entire Sitecore installation when the module package is deployed and can affect any preexisting files. Improper use of dynamic transformations can make your Sitecore instance unusable.

Use the following reference:

Update-SCWebDeployPackage [-EmbedCargoPayloadPath] <string[]> [-Path <string>] [-WhatIf]

Parameters

Description

EmbedCargoPayloadPath

An array of paths to the SCCPL files that embed into the WDP. .Transformations are stored in the Content/Website/App_Data/Transformations folder and applied by Bootloader during the installation process.

Path

The path to the WDP that you want to modify.

WhatIf

A switch that enables a dry run of the transformation and produces the actions that would be performed, without having to modify the package.

Embedding files into the package

SCCPL transformations are convenient to add prebuilt sets of files and configuration changes into WDPs. However, you can also embed individual files, for example, dacpac files, for new databases into a WDP.

Use the following reference:

Update-SCWebDeployPackage [-SourcePath] <string> [-Path <string>]

Parameters

Description

SourcePath

The path to the file that you want to add.

Path

The path to the WDP that you want to modify.

Adjusting parameters

If you want to customize your deployment process, or if you need to deploy dacpac or SQL files with the module, you must create and embed a custom parameters.xml file into your deployment package. You can also define parameters by using the reference for IIS Web Application packages.

When you apply a parameters.xml file to your WDP, SAT automatically regenerates the package manifest to include the files you reference in your parameters. This means that your parameters.xml file becomes a kind of manifest, describing what is inside the package.

The following command adds parameters and regenerates the manifest:

Update-SCWebDeployPackage [-ParametersXmlPath] <string> [-Path <string>]

Parameters

Description

ParametersXmlPath

The path to the parameters.xml file that you want to embed.

Path

The path to the WDP that you want to update.

Invoking multiple commands in a row

It is also possible to pipe commands in a single command line:

$WDP = ConvertTo-SCModuleWebDeployPackage $ZIP or $Update | `
Update-SCWebDeployPackage -CargoPayloadPath @($SCCPL) | `
Update-SCWebDeployPackage -SourcePath $DACPAC | `
Update-SCWebDeployPackage -ParametersXmlPath $Parameters

When using .Net, replace ConvertTo-SCModuleWebDeloyPackage with dotnet, publish, and then manipulate the WDP as usual.

Testing your package

With Microsoft Web Deploy you can test your package installation on a local system with the following command line:

msdeploy -verb:sync -source:package=%CD%\test.scwdp.zip -dest:archiveDir=%CD%\output -setParam:X=TESTVALUE

Send feedback about the documentation to docsite@sitecore.net.