Web Deploy Packages for a module

Current version: 2.4

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.

Prerequisites

Before you start, you must install the Sitecore Azure Toolkit and load the commandlets into a PowerShell session. The required commandlets are defined in the following files:

tools\Sitecore.Cloud.Cmdlets.dll
tools\Sitecore.Cloud.Cmdlets.psm1

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 by using the following PowerShell call:

RequestResponseshell

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

Note

Only added items and files are supported in .update packages.

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 Cognitive 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 Cognitive 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:

RequestResponseshell

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:

RequestResponseshell

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, (such as .dacpac or .sql)

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:

RequestResponseshell

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

Parameters	Description
`SourcePath`	The path to the directory that contains the files 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:

RequestResponseshell

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 modify.

Invoking multiple commands in a row

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

RequestResponseshell

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

When using .Net, replace ConvertTo-SCModuleWebDeployPackage 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:

RequestResponseshell

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

Support for disabling dacpac SQL options to allow synching dacpac in update only mode

Use DisableDacPacOptions to create tables or users when you are deploying. You must disable SqlDatabaseOptions for the module WDP package if you want to deploy them to an on-premise instance. If you do not disable SqlDatabaseOptions, msDeploy will try to convert the contained database into an uncontained database and the attempts to apply these options while deploying the module package produces the wrong result.

The property, DisableDacPacOptions, that is available for ConvertTo-SCModuleWebDeployPackage and Update-SCWebDeployPackage, allows you to configure disabling the SqlDatabaseOptions for a module package.

The default value is empty. This means that the database options of the module WDP package is synched for all uses of dbdacfx.

If you provide the value: "*", then all uses of the dbdacfx provider will have the provider property, ScriptDatabaseOptions, set to "false". You may also receive a list of dbdacfx paths.

The following code samples are examples of:

Disabling SqlDatabaseOptions for all dbdacFx users.

RequestResponseshell

ConvertTo-SCModuleWebDeployPackage -Path .\example.zip -Destination .\output -DisableDacPacOptions '*'

Disabling SqlDatabaseOptions for particular dbdacFx paths.

RequestResponseshell

Update-SCWebDeployPackage -ParametersXmlPath .\parameters.xml -Path .\example.scwdp.zip -DisableDacPacOptions 'core.dacpac', 'master.dacpac'